| name | mcp-tools-reference |
| description | MUST READ before first MCP tool call in a session. Complete Envoy tool catalog with parameters and usage. |
Envoy MCP Tool Reference
Operator Management
| Tool | Parameters | Description |
|---|
create_op | parent_path, op_type, name? | Create a new operator (e.g., baseCOMP, noiseTOP, textDAT, gridPOP) |
create_extension | parent_path, class_name, name?, code?, promote?, ext_name?, ext_index?, existing_comp? | Create a TD extension: baseCOMP + text DAT + extension wiring |
delete_op | op_path | Delete an operator |
copy_op | source_path, dest_parent, new_name? | Copy operator to new location |
rename_op | op_path, new_name | Rename an operator |
get_op | op_path | Get full operator info (type, family, parameters, inputs, outputs, children) |
query_network | parent_path?, recursive?, op_type?, include_utility? | List operators in a container |
find_children | op_path, name?, type?, depth?, tags?, text?, comment?, include_utility? | Advanced search using TD's findChildren |
cook_op | op_path, force?, recurse? | Force-cook an operator |
Parameter Control
| Tool | Parameters | Description |
|---|
set_parameter | op_path, par_name, value?, mode?, expr?, bind_expr? | Set value, expression, bind expression, or mode |
get_parameter | op_path, par_name | Get value, mode, expression, bind info, label, range, menu entries, default |
DAT Content
| Tool | Parameters | Description |
|---|
get_dat_content | op_path, format? | Get DAT text or table data ("text", "table", "auto") |
set_dat_content | op_path, text?, rows?, clear?, confirm_wipe? | Full-replace DAT content. Wipe guardrail: calls that would leave the DAT empty (text="", rows=[], or clear=True with no content) are refused unless confirm_wipe=True. For partial edits to text DATs, prefer edit_dat_content -- it sends only the changed substring (much cheaper for large DATs). Use set_dat_content for tables, full rewrites, or intentional wipes. |
edit_dat_content | op_path, old_string, new_string, replace_all?, confirm_wipe? | Surgical text edit on a DAT -- replaces old_string with new_string. Mirrors Claude Code's Edit tool: old_string must appear exactly once by default; widen with surrounding context for uniqueness, or pass replace_all=True to replace every occurrence. Token-efficient -- only the changed substring crosses the wire. Text DATs only; tables go through set_dat_content(rows=...). Refuses empty old_string, identical strings, and edits that would wipe the DAT (unless confirm_wipe=True). |
Operator Flags
| Tool | Parameters | Description |
|---|
get_op_flags | op_path | Get all flags |
set_op_flags | op_path, bypass?, lock?, display?, render?, viewer?, current?, expose?, allowCooking?, selected? | Set one or more flags |
Operator Positioning & Layout
| Tool | Parameters | Description |
|---|
get_op_position | op_path | Get position, size, color, and comment |
get_network_layout | comp_path, include_annotations? | Get positions of ALL operators (and annotations) in a COMP in one call. Returns bounding_box. Use instead of repeated get_op_position calls |
set_op_position | op_path, x?, y?, width?, height?, color?, comment? | Set position, size, color ([r,g,b] 0-1), or comment |
layout_children | op_path | Auto-layout all children in a COMP |
Annotations
| Tool | Parameters | Description |
|---|
create_annotation | parent_path, mode?, text?, title?, x?, y?, width?, height?, color?, opacity?, name? | Create annotation ("annotate", "comment", "networkbox") |
get_annotations | parent_path | List all annotations with properties and enclosed operators |
set_annotation | op_path, text?, title?, color?, opacity?, width?, height?, x?, y? | Modify annotation properties |
get_enclosed_ops | op_path | Get ops enclosed by annotation, or annotations enclosing an op |
Performance Monitoring
| Tool | Parameters | Description |
|---|
get_op_performance | op_path, include_children? | Get CPU/GPU cook times, memory, cook counts |
get_project_performance | include_hotspots? | Get project-level FPS, frame time, GPU/CPU memory, dropped frames, active ops, GPU temp. Optional hotspot ranking of top N COMPs by cook time |
Connections
| Tool | Parameters | Description |
|---|
connect_ops | source_path, dest_path, source_index?, dest_index?, comp? | Wire two operators. comp=True for COMP connectors |
disconnect_op | op_path, input_index?, comp? | Disconnect an input |
get_connections | op_path | Get all input/output connections |
Code Execution
| Tool | Parameters | Description |
|---|
execute_python | code | Execute Python in TD. Set result variable to return values |
Introspection & Diagnostics
| Tool | Parameters | Description |
|---|
get_td_info | (none) | TD version, build, OS, Envoy version |
get_op_errors | op_path, recurse? | Get error and warning messages for op and children |
exec_op_method | op_path, method, args?, kwargs? | Call a method on an operator |
get_td_classes | (none) | List all Python classes in td module |
get_td_class_details | class_name | Get methods, properties, docs for a TD class |
get_module_help | module_name | Python help text for a module |
MCP Prompts
| Prompt | Parameters | Description |
|---|
search_op | op_name, op_type? | Guide for searching operators |
check_op_errors | op_path | Guide for inspecting/resolving errors and warnings |
connect_ops | (none) | Guide for wiring operators |
create_extension_guide | (none) | Guide for creating extensions |
Embody Integration
| Tool | Parameters | Description |
|---|
externalize_op | op_path, tag_type? | Tag and externalize operator to disk (one step) |
remove_externalization_tag | op_path | Remove externalization tag |
get_externalizations | (none) | List all externalized operators |
save_externalization | op_path | Force re-export an already-externalized operator |
get_externalization_status | op_path | Get dirty state, build, timestamp, path |
TDN Network Format
| Tool | Parameters | Description |
|---|
read_tdn | comp_path?, include_dat_content?, max_depth?, embed_all? | Preferred for reading ≥3 operators. Returns live network as a TDN dict. ~20-90x fewer tokens than get_op+query_network walks thanks to default-omission, type_defaults, and par_templates. |
export_network | root_path?, include_dat_content?, output_file?, max_depth? | Write .tdn to disk. Same payload as read_tdn plus file I/O and stale-file cleanup. |
import_network | target_path, tdn, clear_first? | Recreate network from .tdn JSON |
When to prefer read_tdn: exploring or auditing ≥3 operators, checking structure and parameters-as-authored, mapping connections, reading annotations. Scope cost with comp_path; cap with max_depth on large roots.
When NOT to use read_tdn: evaluated-expression runtime values (get_parameter), cook errors (get_op_errors), DAT/CHOP/TOP output data (get_dat_content, capture_top), cook timing (get_op_performance), flag state after runtime mutation (get_op_flags). read_tdn is an authored-state snapshot, not a runtime probe.
TOP Capture
| Tool | Parameters | Description |
|---|
capture_top | op_path, format?, quality?, max_resolution? | Capture a TOP's output as an image. Returns file path + optional inline preview |
Logging
| Tool | Parameters | Description |
|---|
get_logs | level?, count?, since_id?, source? | Get recent log entries from ring buffer |
Auto-piggybacked logs: Every MCP response includes a _logs field with up to 20 recent entries. Log files inside Embody's logs directory (see the Logfolder parameter on the Embody COMP) have the complete picture.
Bridge Meta-Tools
These run locally on the STDIO bridge — they work even when TD is not running.
| Tool | Parameters | Description |
|---|
get_td_status | (none) | Check if TD is running, Envoy reachable, crash detection, process liveness. Includes instance registry |
launch_td | timeout? | Launch TD with the project's .toe file, wait for Envoy (default: 120s) |
restart_td | timeout? | Gracefully quit TD and relaunch, wait for Envoy (default: 120s) |
switch_instance | instance? | List all registered TD instances (omit instance) or switch the bridge to a different running instance (provide toe basename without .toe). See /multi-instance skill for workflow |
Batch Operations
| Tool | Parameters | Description |
|---|
batch_operations | operations | Execute multiple operations in a single request. Reduces latency and token overhead |
operations is a list of {"tool": str, "params": dict} objects. Each entry maps to an existing tool name and its parameters. Stops on first error.
When to use: 3+ calls to the same tool type (positioning, connecting, parameter setting, flags). Use execute_python instead when you need conditionals, loops, or computed values between operations.
Example — position 4 operators + connect them in one call:
{"operations": [
{"tool": "set_op_position", "params": {"op_path": "/project1/noise1", "x": 400, "y": 0}},
{"tool": "set_op_position", "params": {"op_path": "/project1/comp1", "x": 800, "y": 0}},
{"tool": "set_op_position", "params": {"op_path": "/project1/level1", "x": 1200, "y": 0}},
{"tool": "set_op_position", "params": {"op_path": "/project1/null1", "x": 1600, "y": 0}},
{"tool": "connect_ops", "params": {"source_path": "/project1/noise1", "dest_path": "/project1/comp1"}},
{"tool": "connect_ops", "params": {"source_path": "/project1/comp1", "dest_path": "/project1/level1"}},
{"tool": "connect_ops", "params": {"source_path": "/project1/level1", "dest_path": "/project1/null1"}}
]}
