MCP integration

Connect Claurst to external data sources and tools using the Model Context Protocol.

The Model Context Protocol (MCP) is a standard for extending AI tools with external data sources, APIs, and custom tools. Claurst ships a full MCP client in the cc-mcp crate that connects to any MCP-compliant server over a stdio subprocess transport.

How MCP works in Claurst

When Claurst starts, the McpManager in cc-mcp reads the mcpServers block from your settings, spawns each configured server as a subprocess, performs the JSON-RPC 2.0 initialize handshake, and discovers the server’s tool and resource capabilities. Those tools are then namespaced and injected into Claude’s tool list for the session.

Tool names are prefixed with the server name to avoid collisions. A server named filesystem that exposes a read_file tool appears in Claude’s tool list as filesystem_read_file.

Configuring MCP servers

MCP servers are configured in .claude/settings.json at the project level, or in ~/.claude/settings.json for global availability.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

Each server entry maps to a McpServerConfig struct:

Field	Type	Description
command	string	Executable to spawn
args	array	Command-line arguments
env	object	Additional environment variables
url	string (optional)	For HTTP-based servers
server_type	enum	Transport type

Available MCP tools

Claurst exposes four built-in tools for interacting with MCP servers at runtime:

Tool	Name	Description
MCPTool	MCPTool	Generic MCP tool execution — routes a tool call to the appropriate server
McpAuthTool	McpAuthTool	Handles MCP server authentication flows
ListMcpResourcesTool	ListMcpResources	Aggregates and lists resources from all connected MCP servers
ReadMcpResourceTool	ReadMcpResource	Reads a specific resource by URI from any connected server

ListMcpResources and ReadMcpResource are both implemented in cc-tools/src/mcp_resources.rs and delegate to ctx.mcp_manager. They return an error if no MCP manager is present (i.e., no servers configured).

Dynamic tool registration

MCP server tools appear automatically in Claude’s tool list once the server connects. No restart is required when a server’s capabilities change — reconnecting the server re-runs discovery. The McpManager namespaces tools and routes calls:

claude calls "github_search_repositories"
  → McpManager strips prefix → "search_repositories"
  → routes to McpClient for "github" server
  → sends tools/call JSON-RPC request
  → returns CallToolResult

Managing servers at runtime

Use the /mcp slash command to inspect and manage MCP servers during a session:

/mcp                    # List all configured servers and their status
/mcp connect <name>     # Reconnect a server
/mcp status             # Show connection health for all servers

Authentication

When an MCP server requires authentication, Claude uses McpAuthTool to handle the flow. The authentication exchange happens via the MCP protocol’s standard elicitation mechanism — the server requests credentials, the tool prompts the user, and the response is forwarded to the server.

Adding your first MCP server

1. Choose a server

   Select an MCP server for the data source or capability you need. The MCP ecosystem includes servers for filesystems, GitHub, databases, web search, and more.

2. Add to settings

   Add the server to your .claude/settings.json:

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

   When Claurst starts, the McpManager connects to the server, runs initialize, and discovers available tools. You should see the server listed when you run /mcp.

4. Use the tools

   MCP tools are available like any built-in tool. Ask Claude to use them directly, or they will be selected automatically when relevant:

   Read the file /home/user/documents/notes.txt using the filesystem server.
   

Example: adding a GitHub MCP server

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

Once connected, Claude can search repositories, read files from GitHub, list issues, and access any other capability the server exposes — all without any additional configuration.

MCP server processes are spawned as subprocesses of Claurst using StdioTransport. Each server communicates over stdin/stdout using JSON-RPC 2.0 line-delimited messages. The MCP protocol version used is 2024-11-05.