Connect an MCP server

An agent can use tools from a Model Context Protocol server. maiden launches the server as a subprocess, lists the tools it advertises, and registers each one alongside the agent’s WASM tools — the model sees them all as one flat set.

Add a connection

Create a file under connections/. Today the only transport is mcp-stdio, which runs the server as a child process and speaks to it over stdin/stdout:

my-agent/connections/calc.toml

kind = "mcp-stdio"
command = "./path/to/mcp-calc-server"
args = []

Key	Type	Description
kind	string	Transport. Must be mcp-stdio.
command	string	Executable to launch. Resolved relative to the process working directory (or absolute, or on PATH).
args	string[]	Arguments passed to the command.
env	table	Environment variables for the server process. Values support ${VAR} expansion, so a token is referenced by name rather than written here.
tools.allow	string[]	Surface only these tools. Empty (the default) surfaces every tool the server advertises.
tools.block	string[]	Drop these tools. Applied after allow.

The connection file’s name is only a label; the tool names come from the MCP server itself.

Narrow what the server exposes

A general-purpose MCP server can advertise dozens of tools, and every one of them costs room in the model’s tool list. tools.allow keeps the set to what this agent actually needs:

kind = "mcp-stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]
tools.allow = ["get-sum"]

Names are matched as the server reports them. A name in allow that the server never advertises is simply ignored, so a filter cannot fail loudly — check the tool list maiden logs on load if a tool you expected is missing.

Run it

Start or run the agent as usual — connections are established at load time:

maiden run my-agent "what is 6 * 7?"

On load, maiden connects each server, lists its tools, and adds them to the registry. From there they are dispatched exactly like WASM tools and subagents — see How maiden fits together.

Lifecycle and behavior

• One runtime, many servers. All stdio connections share a background runtime; each server stays alive as long as its tools are registered.
• Tool results. maiden returns the text content of an MCP tool call to the model; an empty result becomes {}.
• Failure. If a server can’t be launched or listed, loading the agent fails with an error naming the command — connections are part of assembling the agent, not an optional afterthought.

What’s not covered yet

Only the stdio transport is implemented. HTTP/SSE MCP transports are not wired up in this version — the same Tool seam would carry them, but the SDK glue isn’t there yet.