RFD: MCP meta server

[Fluzko]

MCP meta-server

Symposium now registers one MCP server with your agent instead of one per plugin. It exposes two tools: list_tools (what's reachable here) and execute (run JavaScript with those tools in scope).

A script composes several calls and returns only what matters, so intermediate data never reaches the agent's context.

What's in this PR

• cargo agents mcp-serve: one "symposium" entry in agent config, replacing per-plugin entries
• Servers are workspace-conditional: one appears only if its depends-on holds
• list_tools answers with an index; full TypeScript declarations behind a filter or detail: "full"
• JSON Schema <> TypeScript, type-checked by tsc in CI
• QuickJS sandbox: no filesystem, network or process plus an uncatchable deadline and memory, stack and output limits
• Backing servers start on first call and restart with backoff
• The workspace is re-resolved mid-session when Cargo.lock changes; running servers are carried across

Not built: cancellation, progress notifications, tools/list_changed, an on-disk tool cache. HTTP/SSE backing servers are refused — stdio only.

Using it

Configure

A plugin declares the servers it provides:

# ~/.symposium/plugins/fs-tools/SYMPOSIUM.toml
name = "fs-tools"
depends-on = ["*"]

[[mcp_servers]]
name = "filesystem"
depends-on = ["serde"]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/data"]

name becomes the global a script calls (filesystem.read_text_file(...)).
depends-on gates the whole entry: this server exists only in workspaces that
depend on serde. command/args are the child process.

Then:

cargo agents sync

That writes a single entry into your agent's MCP config, whatever the agent:

{ "mcpServers": { "symposium": { "command": "cargo-agents", "args": ["mcp-serve"] } } }

The filesystem server is not in there. Nothing about it reaches the agent until
something asks.

Interact

Nothing changes in how you talk to your agent. You ask for what you want:

which files under /tmp/data mention a TODO?

The agent sees two tools, calls list_tools for signatures, then sends one
execute with a program like:

const listing = await filesystem.list_directory({ path: "/tmp/data" });
const names = listing.content
  .split("\n")
  .filter((line) => line.startsWith("[FILE] "))
  .map((line) => line.slice("[FILE] ".length));

const hits = [];
for (const name of names) {
  const file = await filesystem.read_text_file({ path: `/tmp/data/${name}` });
  if (file.content.includes("TODO")) hits.push(name);
}
return hits;

What the server does with it

1. Resolves the workspace and keeps the entries whose depends-on holds.
2. Installs filesystem in the sandbox as a proxy. No child process yet.
3. Runs the program in QuickJS under a deadline and memory/stack/output limits.
4. The script reaches await filesystem.list_directory({ path: "/tmp/data" }).
   That suspends it and crosses to the host, which runs the manifest's command -- npx -y @modelcontextprotocol/server-filesystem /tmp/data -- completes the MCP handshake, and checks list_directory against that server's real tools/list.
5. Dispatches tools/call, unwraps the result, resumes the script.
6. Later calls reuse the running child.
7. The return value is serialized back as the execute result.

The two file bodies are read at step 5, inside the sandbox. Only the matching
names come back, proxying one tool call at a time would have pulled every
file's contents through the agent's context.

A server the script never names is never started. Servers shut down when the
session ends.

Configuration

[mcp] in ~/.symposium/config.toml, all optional. script-timeout-secs (120), script-memory-limit-mb (64), max-result-bytes (32768), max-server-restarts (5), read-only (false), and a few more.

max-tool-calls, server-startup-timeout-secs and tool-call-timeout-secs parse but are not honored yet; startup and call timeouts are fixed at 30s and 60s. Per-server overrides on [[mcp_servers]] do work.

Design rationale: the RFD.

Disclosure questions

AI disclosure.

• The AI tool authored large parts of the code

Questions for reviewers.

[nikomatsakis]

Did a quick skim and left some thoughts. The tests looked pretty good!

[nikomatsakis]

Hmm, good catch. The truncation was not really intended.

[nikomatsakis]

Hmmm, perhaps we should instead convert the tool names into camel case so they read more like idiomatic typescript.

[nikomatsakis]

The claim is that it's not worth handling return types because they're rarely used? Not sure I buy that.

[nikomatsakis]

Hmm, I don't think we need a timeout. The MCP client can decide to timeout all on its own.

[nikomatsakis]

This is OK as an initial limitation but I'm not sure I buy the concern.