LabscoMCP early access ↗
dylanroscoverMCP SERVER

Embody

An MCP server that runs inside your TouchDesigner project, so a coding agent can create operators, wire them, set parameters and look at what they render — in the session you already have open.

by dylanroscover ↗3D, CAD & Game EnginesCommunity

LABSCO SUMMARY

Shaped around one host app, down to the token budget.

Most MCP servers for a desktop app stop at "call the API". This one is built for a program that has no API, so the interesting part is what the tools refuse to do: CHOP and POP reads return statistics rather than raw arrays, table reads have a stats mode, capture_top writes the image to a temp file instead of inlining base64, and read_tdn exists so an agent can hold a whole network without a per-operator walk. The cost side is honest and short — you need TouchDesigner 2025.33070 on the machine, the component has to live in your .toe, and everything happens on loopback, so there is nothing to sign up for and nothing to expose. If you do not run TouchDesigner, none of it applies to you.

What it is

Embody is a TouchDesigner component you drag into a project. Inside it sits Envoy, an embedded MCP server that exposes the live TD session over HTTP on 127.0.0.1 — operators, parameters, connections, cook state and pixel output, not a saved snapshot. TouchDesigner has no external API of its own, so the server runs as a COMP extension in the .toe and starts and stops with your project. It also brings TDN, a YAML form of a network that Embody writes to disk, which is what lets an agent read a whole network as text and lets you diff one attempt against another.

What you get

  • Authoring the network: create_op, copy_op, rename_op, delete_op, connect_ops, disconnect_op, set_parameter, layout_children, set_op_position, create_extension, and batch_operations to send an ordered set of those in one round-trip
  • Reading it back: query_network, find_children, get_op, get_parameter, get_connections, get_network_layout, get_op_flags
  • Network as text: read_tdn returns the live network in memory (the docs put it at 20-90× fewer tokens than walking the same subtree with get_op), export_network writes a .tdn file, import_network rebuilds from one, diff_tdn shows what is live but not yet on disk
  • Reads that reduce instead of dump: get_chop_data gives per-channel min/max/mean, get_pop_data gives attribute metadata with value readback opt-in, get_dat_content has a stats format for large tables, edit_dat_content sends only the changed substring
  • Seeing the output: capture_top saves a TOP's frame to a temp file and returns a quality verdict (is_black / is_flat / fully_transparent / pass) so an empty render is caught without opening the image
  • Diagnosis: get_op_errors covers cook errors, Python tracebacks and GLSL compile failures; get_op_performance and get_project_performance read cook times, dropped frames and hotspots; get_logs, get_td_info, get_docs, get_guidance, get_focus
  • Running code and jobs: execute_python in TD's main thread, exec_op_method, run_tests, save_project, update_embody, polled through get_job_status
  • Externalization: externalize_op, save_externalization, get_externalizations, get_externalization_status, remove_externalization_tag
  • Working alongside other agent sessions: get_sessions, claim_scope, release_scope, announce_task, update_task, preflight_landing
  • Bridge tools that answer while TouchDesigner is closed: get_td_status, launch_td, restart_td, switch_instance
  • Convoy, for Embody nodes on a trusted LAN: convoy_list_nodes, convoy_ping, convoy_select_node, convoy_call, convoy_batch, convoy_get_job, convoy_restart_node, convoy_update_embody and the rest of the convoy_* set
  • MCP prompts ship alongside the tools: search_op, check_op_errors, connect_ops, create_extension_guide

Requirements

TouchDesigner 2025.33070 or later, on Windows or macOS. There is no account and no API key: the server binds 127.0.0.1 only and is not reachable from the network, and the bridge that connects your client runs locally too. Install by dropping the Embody .tox into your project; a setup wizard opens, and turning the assistant on installs the Python MCP dependencies (~30 MB via uv) into a per-project .venv built against TouchDesigner's own interpreter. Envoy then serves on 127.0.0.1:9870 — the Envoy Port parameter moves it, and a second TD instance in the same repo claims the next free port through 9879. It writes .mcp.json plus an AGENTS.md at the root set by the AI Project Root parameter, and client-specific config for whichever assistant you name in AI Client (Claude Code, Codex, OpenCode, Gemini CLI, Cursor, Windsurf, GitHub Copilot via VS Code). Claude Code prompts per tool call unless you let the wizard write the mcp__envoy wildcard into .claude/settings.local.json. Known limits: the TD timeline has to be running or Embody raises an error; clone and replicant operators, and Engine, time and annotate COMPs, cannot be externalized; anything longer than the 30-second operation timeout has to run as a background job.

Setup effort

Follow the published steps

See installation options