MCP servers
Guides

MCP servers

27. MCP servers#

The Model Context Protocol connects Rayu to external tool servers: an issue tracker, a database, a design tool, a browser. Each server publishes tools, resources, and prompts that the agent can call.

v3 loads MCP configuration but has no rayu mcp add command. You declare servers in JSON, and the CLI manages connections, auth, and testing.

Where server definitions load from#

OrderFileScope
1~/.rayu/config.json → mcpServersLegacy Node v2 config, read-only fallback
2~/.rayu/mcp.jsonGlobal
3~/.claude.json → mcpServers and per-project entriesClaude Code, live source
4~/.claude/mcp.jsonOlder Claude Code, live source
5./.mcp.jsonThis project, checked in
6./.rayu/mcp.jsonThis project, Rayu-specific

Later sources win for a server of the same name. The canonical key is mcpServers; Rayu also accepts its historical servers key. ${VAR} and ${VAR:-default} references in a command, argument, env value, URL, or header expand from the environment after the merge.

Set RAYU_DISABLE_CLAUDE_MCP=1 to stop reading the Claude Code sources.

Declaring a server#

A stdio server is a local process Rayu starts and talks to over stdin/stdout:

json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
    }
  }
}

A remote server is reached over Streamable HTTP (falling back to legacy SSE), or SSE directly:

json
{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    },
    "legacy": {
      "type": "sse",
      "url": "https://example.com/sse"
    }
  }
}
FieldMeaning
commandExecutable for a stdio server
argsArgument list
envEnvironment variables for the child process
typestdio (default), http / streamable-http, or sse
urlEndpoint for a remote server; a url with no command implies http
headersStatic headers sent with every request
sharedWhether one instance can serve several sessions (default true). Set false for stateful servers such as a browser.
enabledSet false to keep the definition but not connect
disabledClaude Code style; wins over enabled when both are present
timeout_secsPer-request reply timeout in seconds (default 30); raise it for slow tools

OAuth is separate from static headers: when a remote server has no Authorization header, Rayu uses tokens obtained with rayu mcp login.

Managing servers#

bash
rayu mcp list              # configured servers and local auth state, no connection
rayu mcp test github       # connect once, list info and tools, disconnect
rayu mcp login github      # OAuth sign-in for a remote server
rayu mcp logout github     # forget local OAuth credentials

rayu mcp logout forgets the local credential. It does not revoke the token on the server and does not remove a static header from the config.

rayu mcp test never starts OAuth, so it is safe in a script.

How tools appear#

Each server's tools enter the model's tool set, namespaced as mcp__<server>__<tool>. A server named my.db produces mcp__my_db__*.

Exposure is controlled by [tools] mcp_tools, or --mcp-tools:

ModeBehaviour
auto (default)Keep the cached tool list stable. Providers with native deferred loading get MCP tools as deferred definitions; others get a fixed mcp search/call surface, with newly added tools described in the transcript.
eagerAdvertise every MCP tool as a top-level definition in the first request. Costs prompt tokens, and adding a server mid-session invalidates the prompt cache.
deferredAlias for auto, kept for existing configs.
toml
[tools]
mcp_tools = "auto"

Tool schemas are captured when a session starts. Adding a server mid-session means restarting the session for its tools to appear, even after /refresh-model-list.

In a headless run#

rayu run loads ~/.rayu/mcp.json like the TUI does, so the same mcp__* tools are available in scripts. Server registration is non-blocking: cached schemas are advertised synchronously and the connection happens on the first tool call. When a server has never been used before, rayu run briefly waits for that first connection so the model actually sees the tools in a single-turn run.

MCP prompts and resources#

Beyond tools, some servers publish:

  • Resources — documents the model can list and read.
  • Prompts — templates that become commands.
  • Skills — published as <server>:<skill>.

Availability depends on the server.

Security#

  • A server process inherits the environment you give it and nothing more.
  • Remote servers receive only the headers you configure plus their OAuth token.
  • shared: false for stateful servers prevents two sessions from interleaving calls into one browser or REPL.
  • Treat a third-party MCP server as code you are running. Read the command before you add it, and prefer pinned versions.

Next: Subagents & the swarm →