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.