MCP Server Integration

Viz Arc includes an MCP (Model Context Protocol) server that enables integration with AI assistants and development tools. MCP is an open standard (now under the Linux Foundation) that provides a universal way to connect AI tools to external data and capabilities.

Compatible MCP Clients

The Viz Arc MCP server works with any MCP-compatible client, including:

Client

Type

Notes

Claude Desktop

Desktop App

Anthropic's desktop application

ChatGPT Desktop

Desktop App

OpenAI's desktop application (MCP support added March 2025)

Cursor

IDE

AI-powered code editor with MCP support

VS Code + Copilot

IDE

GitHub Copilot agent mode supports MCP

Windsurf

IDE

Built-in MCP Plugin Store

Cline

VS Code Extension

Autonomous coding agent with MCP integration

Continue

IDE Extension

Open-source extension for VS Code and JetBrains

OpenAI Codex

CLI/IDE

Supports MCP servers in CLI and IDE extension

Architecture Overview

MCP Client VizArc.McpServer.exe Viz Arc
(Any compatible) <----> (Lightweight server) <----> (Main application)
stdio REST API

Benefits

  • Work with multiple AI tools, not locked to one provider.

  • Use your existing AI subscriptions.

  • Access Viz Arc documentation and templates from your preferred tool.

  • Create and modify templates through natural conversation.

  • Work alongside the main Viz Arc application.

Setup Instructions

Step 1: Locate the MCP Server

Find VizArc.McpServer.exe in your Viz Arc installation:

C:\Program Files\Vizrt\Viz Arc\MCP\VizArc.McpServer.exe

Step 2: Configure Your MCP Client

Configuration varies by client. Below are examples for popular MCP clients.

Claude Desktop

  1. Open configuration file: %APPDATA%\Claude\claude_desktop_config.json.

  2. Add the configuration:

    {
    "mcpServers": {
    "vizarc": {
    "command": "C:\\Program Files\\Vizrt\\Viz Arc\\MCP\\VizArc.McpServer.exe",
    "args": []
    }
    }
    }

  3. Restart Claude Desktop completely (check system tray).

ChatGPT Desktop

  1. Open ChatGPT Desktop settings.

  2. Navigate to MCP Servers section.

  3. Add new server with command: C:\Program Files\Vizrt\Viz Arc\MCP\VizArc.McpServer.exe.

  4. Restart ChatGPT Desktop.

Cursor

  1. Open Cursor Settings (CTRL + ,).

  2. Navigate to MCP section.

  3. Add server configuration:

    {
    "vizarc": {
    "command": "C:\\Program Files\\Vizrt\\Viz Arc\\MCP\\VizArc.McpServer.exe",
    "args": []
    }
    }

  4. Restart Cursor.

VS Code with GitHub Copilot

  1. Open VS Code Settings (CTRL + ,).

  2. Search for MCP.

  3. Edit settings.json and add:

    {
    "github.copilot.chat.mcpServers": {
    "vizarc": {
    "command": "C:\\Program Files\\Vizrt\\Viz Arc\\MCP\\VizArc.McpServer.exe",
    "args": []
    }
    }
    }

  4. Reload VS Code.

Windsurf

  1. Open Windsurf's MCP Plugin Store.

  2. Search for VizArc or add custom server.

  3. Set command path: C:\Program Files\Vizrt\Viz Arc\MCP\VizArc.McpServer.exe.

OpenAI Codex CLI
codex --mcp-server "C:\Program Files\Vizrt\Viz Arc\MCP\VizArc.McpServer.exe"

Important: Use double backslashes (\\) in JSON paths for Windows.

Step 3: Verify Connection

After configuring your MCP client:

  1. Start a new conversation.

  2. Ask: "What Viz Arc tools do you have access to?".

The AI should respond with information about available Viz Arc tools.

Example Prompts

For documentation queries (Viz Arc not required)

  • "Show me the available parameter types in Viz Arc"

  • "How do callbacks work in Viz Arc templates?"

  • "What is the difference between SetControlObject and UpdateTemplate?"

For live template work (Viz Arc must be running)

  • "What template do I have open in Viz Arc?"

  • "Add a text input parameter called 'headline' to my current template"

  • "Show me the control objects available in my template"

  • "Link the 'score' parameter to the 'ScoreText' control object"

Available AI Tools

The MCP server exposes its capabilities in three groups: static tools that work at any time, resources that provide documentation and reference material for the AI to read, and dynamic tools that operate on the running Viz Arc application. Dynamic tools require Viz Arc to be running with a valid AI license.

Static Tools (Always Available)

These tools work without Viz Arc running – they answer questions about scripting, parameters and best practices directly from the bundled documentation.

Tool

Description

start_template_generation

Entry point for creating a template: Returns the required JSON format and comprehensive guidelines, and points the assistant to the relevant documentation resources before it starts generating.

list_parameter_types

Lists all Viz Arc UI parameter types (button, text, slider, dropdown, toggle, table, and so on) with their properties, usage examples and best practices.

query_documentation

Searches the Viz Arc API documentation for specific topics, functions or concepts and returns the relevant sections.

Resources

In addition to tools, the MCP server publishes MCP resources (read-only reference documents that compatible AI clients can load as context). This replaces the former get_documentation, get_parameters_reference and get_sample_templates tools.

Resource

Description

Documentation

The complete Viz Arc scripting API reference: All functions, callbacks and global objects available in template scripts.

Parameters Reference

Comprehensive reference for all parameter types, including properties, methods and usage examples.

Sample Templates

Sample template implementations demonstrating best practices and common patterns.

Reference Templates

Complete, production-ready template examples with full JavaScript implementations.

Structured Samples

A library of template patterns in JSON format with metadata and keywords for easy discovery.

Template Schema

The JSON schema and structure guide for Viz Arc templates, including parameter definitions and the expected response format.

Dynamic Tools (Require Viz Arc Running)

Dynamic tools work on the live application – the project, the template currently open in the Template Designer, the scripts and the playlist.

Project and Templates

Tool

Description

get_current_project

Returns information about the loaded project: name, path, templates and configuration.

list_templates

Lists all templates in the current project with names, IDs, types and metadata.

get_template

Returns the details of a specific template, including its script code, parameters and configuration.

create_template

Creates a new template and opens it in the Template Designer for editing.

get_current_editing_template

Returns the template currently open in the Template Designer (the basis for the live-link workflow).

modify_current_template

Applies changes to the open template: script code, parameters to add/update/remove, and control object links (all in a single call).

validate_template_code

Validates JavaScript or VBScript template code for syntax errors and common issues.

Visual Verification

The assistant can check its own work visually and geometrically, iterating until the template layout is clean.

Tool

Description

get_template_snapshot

Captures a PNG screenshot of the template open in the Template Designer, exactly as the operator sees it at runtime.

analyze_template_layout

Analyzes the parameter layout without an image: Reports overlapping parameters, children sticking out of panels, misaligned columns and labels that may be clipped.

Control Object Linking

Tool

Description

get_control_objects

Returns all control objects of the open template with types, properties, linkage status and a suggested parameter type for each.

link_parameter_to_control_object

Creates a UI linkage between a parameter and a control object.

unlink_parameter

Removes the linkage from a parameter.

get_parameter_linkages

Lists all current linkages between parameters and control objects, both UI and code linkages.

is_control_object_linked

Checks whether a specific control object is linked to a parameter, and with which linkage type.

generate_set_control_object_code

Generates correct JavaScript code for SetControlObject to link a parameter value programmatically.

generate_update_template_code

Generates correct JavaScript code for UpdateTemplate to send control object values to the graphics engine.

Script Editing

Script tools that are aware of Viz Arc's current mode, plus direct access to the project's global script.

Tool

Description

get_current_editing_mode

Returns the current editing mode (Template Design, Global Script, Actions, On Air, …) so the assistant knows which context it is working in.

get_current_editing_script

Reads the currently editing script (automatically routes to the template or the global script depending on the current mode).

modify_current_script

Modifies the currently editing script (code and parameters), automatically routed by mode.

get_global_script

Reads the project-level global script, regardless of the current mode.

modify_global_script

Modifies the project-level global script, regardless of the current mode.

apply_script_from_file

Applies a script from a local UTF-8 file (the reliable way to transfer long, AI-generated scripts that would exceed inline tool-argument limits).

Playlist

The assistant can build and manage complete playlists. Describe the desired rundown and it assembles the playlist from your templates, ready for playout.

Tool

Description

get_template_fields

Returns the fillable fields of a template action (names, types, labels and current values) so generated payloads match the template exactly.

create_ai_playlist

Creates a playlist from AI-generated data: Each item becomes a playlist entry that applies its field values to the template when executed.

list_playlist

Lists all items in a playlist tab as a hierarchy with UUIDs, names, types, durations and payload data.

update_playlist_item_payload

Updates field values on an existing payload item; fields are merged with the existing payload data.

duplicate_playlist_item

Clones a playlist row or folder (with all children); the clone is inserted right after the original.

rename_playlist_item

Renames a folder or payload item label.

remove_playlist_item

Removes a playlist item or folder (with all children) by UUID.

clear_playlist

Removes all items from a folder or an entire playlist tab.

move_playlist_items

Moves one or more items into a folder or to the tab root, including cross-tab moves.

reorder_playlist_item

Changes an item's position within its current parent.

set_playlist_item_duration

Sets the duration of a playlist item; parent folder durations and the tab total are recalculated automatically.

  • "Take a snapshot of the template and fix any overlapping or misaligned parameters."

  • "Build a playlist for tonight's match from this fixture list, one lower third per player."

  • "Add a callback to the global script that writes every DataMap change to the log."

Modifying Parameters

When using modify_current_template, you can update various parameter properties:

Property

Description

x, y

Parameter position

width, height

Parameter dimensions

label

Display label

parameterColor / backgroundColor

Background color

Supported Color Formats

  • Hex: #FF5500 or #AARRGGBB

  • RGB function: RGB(255, 85, 0)

  • Comma-separated: 255, 85, 0

  • JSON object: {"R": 255, "G": 85, "B": 0}

Troubleshooting

AI Prompt Panel Not Visible

Cause: AI license not valid or not available.

Solution:

  1. Verify AI license status in System > Configuration > Info.

  2. Contact your Vizrt representative if license is missing.

MCP Server Not Connecting

Check 1: Configuration file syntax

  • Ensure claude_desktop_config.json has valid JSON syntax.

  • Verify double backslashes in Windows paths.

Check 2: Executable path

  • Confirm VizArc.McpServer.exe exists at the specified path.

  • Test by running the executable directly in a terminal.

Check 3: Restart Claude Desktop

  • Fully quit Claude Desktop (check system tray icon).

  • Relaunch the application.

"AI License Required" Error

Cause: Valid AI license not detected.

Solution:

  1. Ensure Viz Arc is running.

  2. Verify AI license in System > Configuration > Info.

  3. Contact your Vizrt representative for license issues.

Documentation Not Loading

Check that the documentation folder exists: %ProgramData%\Vizrt\VizArc\Resources\MCP\AI_Documentation\.

If missing, reinstall Viz Arc or contact support.

Dynamic Tools Not Working

Cause: Viz Arc application not running.

Solution:

  1. Start Viz Arc.

  2. Load a template in template editor.

  3. Try the tool again.

Note: Static tools (documentation, parameter types) work without Viz Arc running. Dynamic tools require Viz Arc to be running with a loaded template.