MCP servers

Model Context Protocol servers add tools from outside. Each one is started on launch and its tools are registered alongside the built-ins.

They live in ~/.config/raunen/mcp.json rather than the main config, so a server that needs a secret in its env is not shoulder-to- shoulder with the model defaults, and can be shared without dragging the rest of the config along.

Two transports

stdio runs a local subprocess and speaks JSON-RPC over its stdin and stdout. http posts to a remote Streamable-HTTP endpoint. Empty means stdio.

~/.config/raunen/mcp.json

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
  },
  "example": {
    "type": "http",
    "url": "https://example.com/mcp/",
    "headers": { "Authorization": "Bearer …" }
  }
}

Headers are forwarded verbatim and nothing expands variables. A token written here sits in the file in plain text — it is written 0600, but an env-var-based server (env on a stdio server) is the better place for a secret.

Defined but idle

A server can be defined and left out of mcp_enabled in the main config, so it stays configured but does not start. An empty list means start every defined server.

config.json

  "mcp_enabled": ["filesystem"]

Seeing what loaded

/mcp lists what is defined, what is active, and how many tools each one provided.

/mcp

──────────────────────────────────────────────── mcp
  filesystem       11 tools
  example          off
  1 servers · 11 tools

A server that is active but shows not started failed to launch or did not complete the handshake — /status and RAUNEN_DEBUG=1 say more.