# Model Context Protocol (MCP)

Connect Clew to external tools, data sources, and services via the Model Context Protocol — an open standard for AI-application integration.

MCP support is implemented in `src/services/mcp/`. Servers are discovered at startup and their tools, resources, and prompts are merged into Clew's runtime.

## How It Works

      MCP Server Config (JSON or inline)
           |
           v
      + MCP Manager (src/services/mcp/)
      |    Server connection lifecycle
      |    Tool discovery via tools/list
      |    Resource access via resources/read
      |    Paginated responses
      |
      + Tool Pool (assembleToolPool)
      |    MCP tools merged with built-in tools
      |    Availability toggled by permission rules
      |
      + Query Loop
           Model sees MCP tools alongside built-ins
           Tool calls routed to the appropriate MCP server

## MCP Commands

Command | Description
--- | ---
`/mcp` | Manage MCP servers — list, add, remove, view status

## CLI Configuration

MCP servers are configured at startup via CLI flags:

    # Load servers from a JSON config file
    clew --mcp-config ./mcp-servers.json

    # Load multiple configs
    clew --mcp-config ./servers.json ./extra.json

    # Pass inline JSON
    clew --mcp-config '{"servers":{...}}'

    # Strict mode (only use MCP servers, no built-ins)
    clew --strict-mcp-config

## MCP Server Config Format

Each MCP server is defined with a command, arguments, and environment variables:

    {
        "servers": {
          "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
            "env": {}
          },
          "database": {
            "command": "node",
            "args": ["./mcp/db-server.js"],
            "env": { "DB_URL": "postgresql://..." }
          }
        }
      }

## Tool Discovery

When an MCP server connects, Clew:

1. Sends `tools/list` to discover available tools
2. Merges discovered tools into the global tool pool via `assembleToolPool()`
3. Handles paginated responses for servers with many tools
4. Makes tools available to the model alongside built-in tools

MCP-provided tools inherit their schemas from the server and go through the same permission gating and hook system as built-in tools.

## Resources

MCP servers can also expose resources — structured data that Clew can read:

- ListMcpResources — List available resources from all connected servers
- ReadMcpResource — Read a specific resource by URI

Resources are useful for accessing database schemas, API documentation, configuration files, and other structured data through MCP servers.

## Plugin-Bundled MCP Servers

Plugins can declare MCP servers in their manifest. These are automatically started when the plugin is loaded and stopped when the plugin is unloaded. See Plugins for details.

## Architecture Files

Path | Role
--- | ---
`src/services/mcp/` | MCP server connection management, tool discovery, resource access
`src/tools.ts` | Tool registry — MCP tools merged via assembleToolPool()