MCP Client Operator

The MCP Client LOP facilitates communication with external MCP (Model Context Protocol) servers. It allows you to define and manage connections to multiple MCP servers, execute tools provided by these servers, and integrate their functionality into your TouchDesigner projects. This operator is crucial for extending TouchDesigner’s capabilities by leveraging external services and applications that expose an MCP interface.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs, enabling AI models to connect with different data sources and tools.

Requirements

• Python Packages:
  • mcp: The core MCP Python SDK. Must be installed.
  • anyio: Asynchronous I/O library for MCP communication. Must be installed.
• ChatTD Operator: Required for dependency management and asynchronous operations. Ensure the ChatTD Operator parameter on the ‘About’ page points to your configured ChatTD instance.

Input/Output

This operator primarily manages connections and executes tools, rather than processing direct data inputs or outputs via TouchDesigner wires. Tool execution results are typically logged or can be retrieved via the last_result DAT.

Inputs

None directly via TouchDesigner inputs.

Outputs

• tools (Table DAT): A dynamically updated Table DAT containing a list of all discovered tools from connected MCP servers. Each row represents a tool with its name, description, and schema.
• last_result (Text DAT): A Text DAT that displays the result of the last executed tool call.

Parameters

Page: MCP Client

Status (Status) op('mcp_client').par.Status String

Default:

"" (Empty String)

Loadconfig (Loadconfig) op('mcp_client').par.Loadconfig Pulse

Default:

None

Disconnect (Disconnect) op('mcp_client').par.Disconnect Pulse

Default:

None

Sync Sequence from Config (Syncsequence) op('mcp_client').par.Syncsequence Pulse

Default:

None

Configfile (Configfile) op('mcp_client').par.Configfile File

Default:

me.path + '/servers_config.json'

Editconfig (Editconfig) op('mcp_client').par.Editconfig Pulse

Default:

None

Servers (Servers) op('mcp_client').par.Servers Sequence

Default:

0

Server name (Servers0servername) op('mcp_client').par.Servers0servername String

Default:

"" (Empty String)

Enable (Servers0enabled) op('mcp_client').par.Servers0enabled Toggle

Default:

false

Status (Servers0status) op('mcp_client').par.Servers0status String

Default:

"" (Empty String)

Tool Count (Servers0toolcount) op('mcp_client').par.Servers0toolcount Int

Default:

0

Description (Servers0description) op('mcp_client').par.Servers0description String

Default:

"" (Empty String)

Enable / Disable All (Enabledisableall) op('mcp_client').par.Enabledisableall Toggle

Default:

false

Auto-Sync on Config Change (Autosync) op('mcp_client').par.Autosync Toggle

Default:

false

Test Tool Name (Toolname) op('mcp_client').par.Toolname String

Default:

"" (Empty String)

Test Tool Arguments (JSON) (Toolarguments) op('mcp_client').par.Toolarguments String

Default:

"" (Empty String)

Call Test Tool (Calltool) op('mcp_client').par.Calltool Pulse

Default:

None

Page: Install / Debug

Status (Status2) op('mcp_client').par.Status2 String

Default:

"" (Empty String)

Install Dependencies (Installdeps) op('mcp_client').par.Installdeps Pulse

Default:

None

Check Dependencies (Checkdeps) op('mcp_client').par.Checkdeps Pulse

Default:

None

Page: About

Bypass (Bypass) op('mcp_client').par.Bypass Toggle

Default:

Off

Show Built-in Parameters (Showbuiltin) op('mcp_client').par.Showbuiltin Toggle

Default:

Off

Version (Version) op('mcp_client').par.Version String

Default:

1.2.0

Last Updated (Lastupdated) op('mcp_client').par.Lastupdated String

Default:

2025-07-13

Creator (Creator) op('mcp_client').par.Creator String

Default:

dotsimulate

Website (Website) op('mcp_client').par.Website String

Default:

https://dotsimulate.com

ChatTD Operator (Chattd) op('mcp_client').par.Chattd OP

Default:

"" (Empty String)

Callbacks

This operator utilizes internal callbacks for managing asynchronous tool calls and connection status. The primary callback for external interaction is onToolCallComplete (or similar, handled by the HandleMCPToolCall method), which is triggered when a tool execution finishes.

Available Callbacks:

• onToolCallComplete

Example Callback Structure:

def onToolCallComplete(info):
# Called after an MCP tool call completes.
# info dictionary contains details like:
# - status: 'success' or 'error'
# - response: The result of the tool call (if successful)
# - error: Error message (if failed)
# - details: More detailed error information (if failed)
# - server: The name of the server the tool was called on
# - tool: The name of the tool that was called

if info['status'] == 'success':
  print(f"MCP Tool '{info['tool']}' on server '{info['server']}' completed successfully: {info['response']}")
else:
  print(f"MCP Tool '{info['tool']}' on server '{info['server']}' failed: {info['error']}")
  print(f"Details: {info.get('details', 'N/A')}")

Tool Integration

This operator exposes all discovered MCP server tools to other LOPs operators (e.g., Agent, Orchestrator) that can utilize external tools. This means you can dynamically access and execute functions from connected MCP servers directly within your LOPs workflows.

🔧 GetTool Enabled 1 tool

This operator exposes 1 tool that allow Agent and Gemini Live LOPs to dynamically discover and expose external MCP server tools for AI agent integration and remote system connectivity.

Use the Tool Debugger operator to inspect exact tool definitions, schemas, and parameters.

Usage Examples

1. Basic Server Connection and Tool Discovery

1. Create a servers_config.json file: Create a JSON file (e.g., servers_config.json in your project folder) with the following structure. This example assumes you have a simple Python MCP server script (my_server.py):

   {
       "mcpServers": {
           "my-python-server": {
               "transport": "stdio",
               "command": "python",
               "args": ["path/to/your/my_server.py"],
               "cwd": "path/to/your/server/working/directory",
               "description": "My example Python MCP server"
           }
       }
   }

   Replace path/to/your/my_server.py and path/to/your/server/working/directory with actual paths.

2. Configure MCP Client:

   • Drag and drop an mcp_client operator into your project.
   • Set the Config File parameter to the absolute path of your servers_config.json (e.g., project.folder + '/servers_config.json').

3. Install Dependencies:

   • Go to the Install / Debug page.
   • Pulse Install Dependencies to ensure mcp and anyio are installed.

4. Load Configuration:

   • Go back to the MCP Client page.
   • Pulse Load Config. The Status parameter should update, and the Servers sequence should populate with my-python-server.

5. Discover Tools:

   • Once connected, the tools Table DAT (output of the mcp_client operator) will list all tools exposed by my-python-server.

2. Calling an MCP Tool

1. Ensure a server is connected and its tools are discovered (as in Example 1).
2. Identify the tool name: From the tools DAT, find the name of the tool you want to call (e.g., my-python-server/my_tool_function).
3. Set Tool Parameters:
   • In the MCP Client page, set Test Tool Name to the full tool name (e.g., my-python-server/my_tool_function).
   • If the tool requires arguments, enter them as a JSON string in Test Tool Arguments (JSON) (e.g., {"param1": "value1", "param2": 123}).
4. Call the Tool:
   • Pulse Call Test Tool.
   • The result of the tool call will appear in the last_result Text DAT.

Technical Notes

• Asynchronous Operations: All MCP communication and tool executions are handled asynchronously via TDAsyncIO to prevent blocking the TouchDesigner UI.
• Dynamic Tool Discovery: The operator automatically discovers and lists tools exposed by connected MCP servers, making them available for use by other LOPs components.
• Error Handling: Includes robust error handling for connection issues, invalid configurations, and tool execution failures.
• Cross-Platform Compatibility: Supports both stdio-based (e.g., Python scripts) and HTTP-based MCP servers.

Related Operators

• ChatTD: Provides core services like dependency management and asynchronous task execution required by this operator.
• Agent: Can utilize the tools exposed by the MCP Client to extend its capabilities with external services.