MCP and the assistant
Connect AI agents (Claude Code, Claude Desktop, Codex) to a running Oink through its built-in MCP server.
While the app runs, its backend serves the Model Context Protocol (MCP) on your machine only. Agents get the MCP tools: read the graph, inspect nodes, render preview frames, and (with your approval) create nodes, set knobs, import .nk and more. The Assistant panel in the app uses the same tools.
The server
| Setting | Value |
|---|---|
| Address | http://127.0.0.1:8765/mcp (Streamable HTTP, JSON replies) |
| Port | OPENCOMP_MCP_PORT: a number, 0 = any free port, off = disabled. A busy 8765 falls back to a free port. |
| Access | Localhost only; requests need Authorization: Bearer <token> |
| Token | ~/.config/opencomp/mcp_token (created on first start, readable only by you); OPENCOMP_MCP_TOKEN overrides it |
| Connection info | ~/.config/opencomp/mcp.json = {url, token, pid}, written by the instance that got the configured port (OPENCOMP_MCP_INFO changes the path) |
Connect a client
Claude Code (HTTP):
claude mcp add --transport http opencomp http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer $(cat ~/.config/opencomp/mcp_token)"The Assistant panel's Settings can copy this command for you.
Claude Desktop (claude_desktop_config.json), through the stdio bridge, which reads mcp.json:
{ "mcpServers": { "opencomp": { "command": "python3", "args": ["<install folder>/tools/mcp/opencomp_mcp_stdio.py"] } } }Codex (~/.codex/config.toml):
[mcp_servers.opencomp]
command = "python3"
args = ["<install folder>/tools/mcp/opencomp_mcp_stdio.py"]Any other client: use the stdio bridge, or HTTP with the bearer token. The bridge also takes OPENCOMP_MCP_URL and OPENCOMP_MCP_TOKEN.
What agents can do beyond the graph
The full list is in MCP tools. The groups:
| Group | Examples |
|---|---|
| Graph | read the graph (large graphs come back in pages: call again with next_offset), inspect nodes, set knobs, import .nk |
| AI jobs | start, watch, cancel and read the results of an AI node's job (ai_job_run, ai_job_status, ai_job_cancel) |
| Many shots | add an AI node or a list of edits to many shots as one proposal with one approval (ai_job_run_shots, shots_apply); shots_undo puts the comps back |
| Prep Show | run it, read the key shots and shot reports, apply a shot's proposals disabled (prep_show_run, key_shots, prep_apply) |
| Renders and farm | the Background Renders queue and the LAN farm |
| Viewer | read what the Viewer shows, change input, frame, region or compare |
| Review notes | read and add notes in the Review sidecar files |
| Localization, Collect, diagnostics | status and control of local copies, Collect Files, the diagnostic bundle |
| Production tracker | schedule, bids, time logs, proposed tasks from Prep Show (prod_* tools) |
Long jobs never block a call: the tool returns a task id, and task_status reports on it. Tools that only stop work (cancel) or only move the view need no approval.
To connect Claude Code or Claude Desktop in one line, run ./render.sh --mcp-setup [claude-code | claude-desktop] (add --print to see the config without writing it).
Approvals and undo
- Read tools run at once and never change the comp.
- Edit tools show a prompt in the app with the change as a diff: Approve, Deny or Trust this session. The agent's call waits up to 300 s (
OPENCOMP_MCP_APPROVAL_TIMEOUT); no answer = denied. With no app window connected, edits are refused. - Each edit call is one undo step named
AI (<client>): <tool>; a call that fails is rolled back.apply_changesbundles several edits into one approval and one undo step. - Unattended scripts:
OPENCOMP_MCP_AUTO_APPROVE=1, ormcp_auto_approvein the admin AI policy.
Policy and audit
- An admin policy file (
/etc/opencomp/ai_policy.json, orOPENCOMP_AI_POLICY) can disable MCP (allow_mcp), allow auto-approval, and allow or forbid cloud AI providers, and hide the non-commercial research models (allow_research_pack). - Every MCP session and tool call (arguments, decision, result, time) is logged to
~/.cache/opencomp/logs/ai-audit.jsonl.
Tools run on the backend's main thread through the same command handlers as the app, so agent edits appear live in the node graph and are saved with the comp.