Doc · Extension model Classification · Public Subject · MCP without a marketplace

The MCP registry

Most agent ecosystems answer "what may the agent do?" with a marketplace. Browse a catalogue, install a stranger's code, hand it the process. I didn't want that on my machines. Talos answers with a file the operator owns. No catalogue, no install button, no third-party code in the agent process. MCP servers run only inside the UID-separated claude worker, behind a double gate.

This page is that model, written down as it ships. The operator guide with the full protocol is docs/claude-worker.md. A curated starting point ships as examples/mcp-servers.json.

3578automated tests
277/277adversarial
996gate lines
37gated tools
16servers, at most
0env fields, ever

Section 01The model

Talos itself never speaks MCP. The claude -p child inside a confined worker job does. That job writes only into its own kernel-derived disposable workspace, on a separate UID, with a hard deadline. Talos writes the MCP configuration and hands it through with --mcp-config. The socket frame that starts a job carries server names, never commands or arguments. The model can ask for a server by name. Naming is all it can do.

Which names exist at all is not a model question and not a market question. It is an operator decision, written down in one place.

Why not the agent process

An MCP server is somebody else's code with a tool list. Load it into the agent and it stands next to the kernel with rights of its own · exactly the second source of permission I built the gate to remove. Inside the worker it is a guest in a cell. The confinement form is the boundary. The agent only ever sees names and results.

Section 02The registry file

data/mcp-servers.json is operator-owned, gitignored, and fail-closed by the same convention as entities.json. The parser, talos/mcpservers.py, refuses things a friendlier parser would wave through:

  • version: 1 is mandatory. Anything else is not a registry.
  • A missing, broken, or oversized file (32 KB cap) parses as an empty registry. No error, no guessed partial state.
  • An invalid entry falls out on its own. Its neighbours stay readable. One bad entry does not take the good ones with it.
  • Names must match [a-z0-9-]{1,32} · they become tool prefixes (mcp__<name>) and file components.
  • command must be an absolute path · or empty, in which case npx <package> starts the server. A relative command would resolve against the job's workspace and could be swapped from there.
  • args is a capped string list. Sixteen servers at most.
  • An env field costs the whole entry. The server inherits exactly the minimised job environment. A private env table would be a second credential path, and an unchecked one.

Section 03The double gate

Existing in the registry is not being allowed. A server must be named in both of these, or the request is refused by name before any job starts:

GateWhereWhat it decides
registry filedata/mcp-servers.json The server exists, with exactly this command and these args.
worker allowlistTALOS_CLAUDE_WORKER_MCP_SERVERS in the worker's own env file This worker may start it. The agent-side TALOS_MCP_SERVERS intersects separately. The browser switches keep implying chrome-devtools, so existing installs don't break.

Per requested server, --allowedTools gets exactly one mcp__<name> prefix. Never more than was asked for.

Section 04A curated starting point

Two entries, in the shape the parser accepts. They ship as examples/mcp-servers.json. Copy to data/mcp-servers.json and replace every placeholder with infrastructure you control.

{
  "version": 1,
  "servers": [
    {
      "name": "chrome-devtools",
      "command": "/usr/local/bin/npx",
      "args": ["chrome-devtools-mcp@latest", "--headless=true"],
      "description": "Browser automation inside the job, via npx"
    },
    {
      "name": "filesystem",
      "command": "/usr/local/bin/npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/var/lib/talos/claude-jobs"],
      "description": "File access rooted at the worker root  ·  never wider"
    }
  ]
}

Keep the filesystem root at or below the worker root. The job can only write there anyway. A wider root would hand the child read access the confinement form does not account for.

Section 05What this deliberately costs

  • No discovery. You can't browse for a server from the chat. You read the server's code, then you write one entry. That is the price of there being nothing to social-engineer.
  • No per-action gate inside a job. What the confined Claude does with its MCP tools is bounded by the confinement form: workspace-only writes, read-only root, one deadline. Not by a verdict per call. The 27 gated tools on the agent side get that verdict; MCP tools inside a job don't. If that is more trust than you want to extend, the entry doesn't go in the file.
  • Network is on in job sandboxes. Claude needs it. The boundary is the filesystem, not the wire. I'd rather state that here than imply otherwise.