MCP (Model Context Protocol)

Open protocol for plugging external tools and data into CrabCode. Supports stdio, SSE, HTTP servers, with OAuth and built-in acosmi.com proxies.

What it is

MCP is an open protocol that lets CrabCode reach external "tools" and "data": run an MCP server (Slack, GitHub, filesystem, internal DB, ...), register it in config, and CrabCode can invoke its tools and read its resources during a conversation.

When you see this doc

• The /mcp server list
• A crabcode mcp add CLI argument error
• A .mcp.json parse-error link
• settings.json validation pointing at the MCP fields

Where to configure

Load order: user → project → local → policy; later loads override earlier ones for the same server name.

Example

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/code"],
      "env": { "LOG_LEVEL": "info" }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": { "Authorization": "Bearer ${SENTRY_TOKEN}" }
    },
    "internal-sse": {
      "type": "sse",
      "url": "https://internal.example.com/sse"
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/code"],
      "env": { "LOG_LEVEL": "info" }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": { "Authorization": "Bearer ${SENTRY_TOKEN}" }
    },
    "internal-sse": {
      "type": "sse",
      "url": "https://internal.example.com/sse"
    }
  }
}

Supported type: stdio / http / sse. (IDE extensions use internal sse-ide / ws-ide — not user-facing.)

Windows note

A bare command: "npx" doesn't resolve on Windows; route through cmd:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\code"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\code"]
    }
  }
}

CLI commands

crabcode mcp is the non-interactive admin entry point:

Startup flags

• --mcp-config <file> — load extra config files (space-separated, may repeat)
• --strict-mcp-config — use only --mcp-config sources; ignore user/project/local
• --mcp-debug — deprecated, use --debug

Slash commands

OAuth and built-in acosmi.com servers

• OAuth: sse / http servers can declare an oauth block (clientId / callbackPort / authServerMetadataUrl). The first tool call opens a browser for authorization; tokens cache in your local keychain
• Cross-App Access (XAA): configure the enterprise IdP once with crabcode mcp xaa setup; XAA-enabled servers then share that identity instead of logging in per server
• acosmi.com proxy servers: once signed in to Acosmi, a set of acosmi.com <Name> servers appears automatically, forwarded by the gateway — no manual config; they show up directly in /mcp

Limits and caveats

• stdio servers are long-lived: spawned at CrabCode startup, killed on session exit; a crash means waiting for next launch
• Header env-var interpolation: Bearer ${TOKEN} and $TOKEN both work; undefined vars expand to empty string
• .mcp.json trust: first load of a project's .mcp.json prompts for approval; decisions cache locally — use reset-project-choices to re-prompt
• Name collisions: later loads override earlier; crabcode mcp add refuses a duplicate name within the same scope
• Scope: defaults to user; use -s project for .mcp.json (team-shared) or -s local for the gitignored local file

Related

• settings
• hooks