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

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