> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```json theme={null}
{
  "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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Add to settings">
    Add the server to your `.claude/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/home/user/documents"
          ]
        }
      }
    }
    ```
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
    ```
  </Step>
</Steps>

## Example: adding a GitHub MCP server

```json theme={null}
{
  "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.

<Note>
  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`.
</Note>