MCP (Model Context Protocol)

MCP lets you connect external tool servers to OpenCrust. Any MCP-compatible server - filesystem access, GitHub, databases, web search - becomes available as native agent tools.

How It Works

1. You configure MCP servers in config.yml or ~/.opencrust/mcp.json
2. At startup, OpenCrust connects to each enabled server and discovers its tools
3. MCP tools appear alongside built-in tools with namespaced names: server.tool_name
4. The agent can call them like any other tool during conversations

Transports

• stdio (default) - OpenCrust spawns the server process and communicates via stdin/stdout
• HTTP - Connect to a remote MCP server over HTTP (tracked in #80)

Configuration

MCP servers can be configured in two places. Both are merged at startup.

config.yml

Add an mcp: section to ~/.opencrust/config.yml:

mcp:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

mcp.json (Claude Desktop compatible)

You can also use ~/.opencrust/mcp.json, which follows the same format as Claude Desktop's MCP configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

If the same server name appears in both files, the config.yml entry takes precedence.

McpServerConfig Fields

CLI Commands

List configured servers

opencrust mcp list

Shows all configured MCP servers with their enabled status, command, args, and timeout.

Inspect tools

opencrust mcp inspect <name>

Connects to the named server, discovers all available tools, and prints each one as server.tool_name with its description. Disconnects after inspection.

List resources

opencrust mcp resources <name>

Connects to the server and lists all available resources with URI, MIME type, name, and description.

List prompts

opencrust mcp prompts <name>

Connects to the server and lists all available prompts with their names, descriptions, and arguments (including required flags).

Tool Namespacing

MCP tools are namespaced with the server name to avoid collisions. For example, if you have a server named filesystem that exposes a read_file tool, it appears as filesystem.read_file in the agent's tool list.

This means multiple MCP servers can expose tools with the same name without conflict.

Examples

Filesystem server

Give the agent access to read and write files in a specific directory:

mcp:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]

GitHub server

Let the agent interact with GitHub repositories:

mcp:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

SQLite server

Query a local database:

mcp:
  sqlite:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]

HTTP server (future)

Connect to a remote MCP server:

mcp:
  remote-tools:
    transport: http
    url: "https://mcp.example.com"
    timeout: 60

Implementation Details

• MCP support is feature-gated behind the mcp feature in opencrust-agents (enabled by default)
• Uses the rmcp crate (official Rust MCP SDK)
• McpManager in crates/opencrust-agents/src/mcp/manager.rs handles connections
• McpTool in crates/opencrust-agents/src/mcp/tool_bridge.rs bridges MCP tool definitions to the internal tool interface

Limitations and Future Work

Tracked in #80:

• HTTP transport support
• MCP resources integration
• MCP prompts integration
• Auto-reconnect on server crash