# 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](/docs/reference/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):

```sh
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`:

```json
{ "mcpServers": { "opencomp": { "command": "python3", "args": ["<install folder>/tools/mcp/opencomp_mcp_stdio.py"] } } }
```

**Codex** (`~/.codex/config.toml`):

```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](/docs/reference/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_changes` bundles several edits into one approval and one undo step.
- Unattended scripts: `OPENCOMP_MCP_AUTO_APPROVE=1`, or `mcp_auto_approve` in the admin AI policy.

## Policy and audit

- An admin policy file (`/etc/opencomp/ai_policy.json`, or `OPENCOMP_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.


---
Sources: opencomp_server/mcp_server.py, opencomp_server/mcp_tools.py, opencomp_server/ai_policy.py, tools/mcp/opencomp_mcp_stdio.py, docs/notes/llm-mcp.md