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.

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

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.