The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. Ryvos includes a native MCP client that can connect to any MCP server, making their tools available to the agent as if they were built-in.

What MCP Provides

MCP servers expose:

• Tools — Functions the agent can call (e.g., read files, query databases, call APIs)
• Resources — Data the agent can read (e.g., documentation, configuration, live data)
• Prompts — Pre-defined prompt templates

Ryvos bridges all MCP tools into its native tool registry, so the agent can use MCP tools alongside the 86+ built-in tools seamlessly.

How It Works

Ryvos Agent
    │
    ▼
McpClientManager
    │
    ├── stdio: subprocess MCP server
    │   ├── JSON-RPC over stdin/stdout
    │   └── Tools: mcp__filesystem__read_file, mcp__filesystem__write_file, ...
    │
    └── SSE: remote MCP server
        ├── HTTP Server-Sent Events
        └── Tools: mcp__remote__custom_tool, ...

1. Ryvos starts configured MCP servers (or connects to remote ones)
2. McpClientManager discovers available tools via the MCP tools/list method
3. Each MCP tool is wrapped as a McpBridgedTool implementing the native Tool trait
4. Tools are registered in the ToolRegistry with the mcp__{server}__{tool} naming convention
5. The agent can now call these tools like any other tool

Tool Naming

MCP tools follow a consistent naming pattern:

mcp__{server_name}__{tool_name}

Examples:

• mcp__filesystem__read_file — The read_file tool from the filesystem server
• mcp__github__create_issue — The create_issue tool from the github server
• mcp__postgres__query — The query tool from the postgres server

Security

All MCP tools default to security tier T2 (medium), and the constitutional safety system evaluates each call.

The rationale: MCP servers are external code that Ryvos does not control. Classifying them at T2 gives the constitutional reasoning system appropriate context for evaluating these actions.

Configuration

MCP servers are configured in config.toml:

[mcp]
 
[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
 
[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
 
[mcp.servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
 
[mcp.servers.remote-api]
url = "http://localhost:3001/sse"

.mcp.json Compatibility

Ryvos also reads .mcp.json files (Claude Code format) from the workspace:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    }
  }
}

Place this file in your project root and Ryvos will discover it automatically.

Popular MCP Servers

Managing MCP Servers

Use the CLI to manage MCP servers:

# List configured servers and their tools
ryvos mcp list
 
# Add a new stdio server
ryvos mcp add github --command npx --args "-y" "@modelcontextprotocol/server-github"
 
# Add a remote SSE server
ryvos mcp add remote --url "http://localhost:3001/sse"

Resources

MCP servers can also expose resources. Ryvos provides the McpReadResourceTool that lets the agent read MCP resources:

{
  "server": "docs",
  "uri": "file:///path/to/document.md"
}

This is useful for MCP servers that expose documentation, configuration, or live data as resources.

Next Steps

• Connecting Servers — Detailed Stdio and SSE transport setup
• Custom Tools — Other ways to extend Ryvos
• Configuration — MCP config reference