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.
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.
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: 1is 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. commandmust be an absolute path · or empty, in which casenpx <package>starts the server. A relative command would resolve against the job's workspace and could be swapped from there.argsis a capped string list. Sixteen servers at most.- An
envfield 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:
| Gate | Where | What it decides |
|---|---|---|
| registry file | data/mcp-servers.json |
The server exists, with exactly this command and these args. |
| worker allowlist | TALOS_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.