[05] MCP

MCP

Built-in MCP server inside TouchDesigner. Connects AI agents (Claude Code, Cursor, Codex) to your live TD session over HTTP — they create operators, wire networks, read errors, run Python, capture screenshots, and reason about your patch through natural language.

What you can do

Things your agent can act on directly:

"Check errors inside *this comp"
"Why is this slow? List the top slow ops with cook times"
"Audit *this op and the surrounding chain — don't change anything yet"
"Refactor *this network: same result, fewer ops, no broken refs"
"Rebuild [.html / .pen] ui example into TD native panels, exactly and responsive to par.w/h"

The agent traverses your project, executes changes live in the editor, and returns structured results — all while you watch.

Setup

Auto-start on TD launch — Settings → MCP → auto start MCP → Yes. Server boots on next TD launch using the base port from Settings → MCP → MCP default port (default 40404).

One-time agent config — ask your agent once:

Add twozero TD MCP for me with server key "twozero_td" and URL "http://localhost:40404/mcp". Configure it globally (user scope).

After that the agent picks up TD automatically from any project / workspace. Configure only one MCP URL — twozero handles additional TD instances internally; do not add separate client entries per instance.

Starting a chat

Open every new agent chat with a priming prompt so the agent immediately uses MCP and confirms it can see your current TD context (project, network, selected ops):

Show me what you can see in my TD project.
check in TD: <your task here>
*here in TD: <your task here>
Check *this op in TD: <your task here>

Once the agent confirms context, drop the ritual and just talk normally.

Pointers — `*here` and `*this`

Two phrases that resolve to your current viewport / selection:

*here / *тут The network you are currently looking at in TD.
*this / *этот / *эту The single operator you have selected.
*these / *эти All operators you have currently selected (multi-select).

The asterisk is the magic: it never appears in normal code or text, so the agent treats these as unambiguous pointers and the response is rock-solid. Plain "here" / "this op" works too, but the asterisk version is bulletproof — use it when precision matters.

Built-in triggers

Phrases the agent recognises as named flows:

study this project / изучи проект Cold-start project analysis. Best for unfamiliar or large patches when you want a tour, not a single-op poke.
twozero bug report / twozero баг репорт Built-in bug report flow. The word twozero is required so generic "report a bug" doesn't trigger it accidentally.

Working safely

Two workflow phrases that keep the agent from breaking your patch:

Plan first, then change: diagnose, propose, wait for my approval.
After fixes: re-run error and performance checks to verify.

Combine with the asterisk pointers — *this to scope the work, *here to keep the agent inside the network you're looking at.

Russian and TD slang

Mix English and Russian freely — the agent normalises TD terms across languages:

TouchDesigner TD · тач
project / patch проект · патч · .toe file
operator op · оператор · оп
parameter par · параметр · пар
*here in TD в таче *тут
*this op in TD в таче *этот оп
*these ops in TD в таче *эти опы
Show me what you can see in my TD project. Посмотри, что у меня в таче.

How it works

Agent → MCP request → twozero server (inside TD) → executes in your live project → result back to agent. Everything happens on your machine; nothing leaves except whatever your agent's LLM provider sees in the conversation.

When several TD instances are open at once, twozero auto-claims the next free port for each (40404, 40405, …) and the agent lists them and asks which one to act on — no manual configuration.

Troubleshooting

Agent doesn't see TD Confirm twozero is running. On macOS check firewall. The base port (default 40404) must be free. Restart TD if the server didn't boot. In Claude Code: /mcp → twozero_td → reinitialize.
Commands fail silently TD build must be 2025.32820 or higher — older builds lack the APIs MCP depends on.

Notes

  • twozero must be running in TouchDesigner for the MCP server to be reachable.
  • Keep Settings → MCP → local only MCP = Yes (recommended).
  • Use Opus 4.6 or 4.7 for best results — smaller models hallucinate operator parameters more often.
  • Source & issues: github.com/404dotzero/twozero-td-mcp
Previous Toolset & Usage