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#
| Order | File | Scope |
|---|---|---|
| 1 | ~/.rayu/config.json → mcpServers | Legacy Node v2 config, read-only fallback |
| 2 | ~/.rayu/mcp.json | Global |
| 3 | ~/.claude.json → mcpServers and per-project entries | Claude Code, live source |
| 4 | ~/.claude/mcp.json | Older Claude Code, live source |
| 5 | ./.mcp.json | This project, checked in |
| 6 | ./.rayu/mcp.json | This 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:
{
"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:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
},
"legacy": {
"type": "sse",
"url": "https://example.com/sse"
}
}
}| Field | Meaning |
|---|---|
command | Executable for a stdio server |
args | Argument list |
env | Environment variables for the child process |
type | stdio (default), http / streamable-http, or sse |
url | Endpoint for a remote server; a url with no command implies http |
headers | Static headers sent with every request |
shared | Whether one instance can serve several sessions (default true). Set false for stateful servers such as a browser. |
enabled | Set false to keep the definition but not connect |
disabled | Claude Code style; wins over enabled when both are present |
timeout_secs | Per-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#
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 credentialsrayu 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:
| Mode | Behaviour |
|---|---|
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. |
eager | Advertise 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. |
deferred | Alias for auto, kept for existing configs. |
[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: falsefor 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 →