Charm Docs

Appearance

MCPs ​

Crush supports Model Context Protocol (MCP) servers through three transport types: stdio for command-line servers, http for HTTP endpoints, and sse for Server-Sent Events.

bash
# crushrc

# Add a local MCP server that runs a Node.js script.
mcp add filesystem --command node --args /path/to/mcp-server.js \
  --timeout 10 --disabled-tools some-tool-name --env NODE_ENV production

# Add a GitHub MCP server that uses an API token.
mcp add github --type http --url https://api.github.com/mcp/ \
  --timeout 10 --header Authorization "Bearer $GH_PAT" \
  --disabled-tools create_issue --disabled-tools create_pull_request

# Add a streaming MCP server that uses SSE.
mcp add streaming-service --type sse --url "https://example.com/mcp/sse" \
  --timeout 10 --header API-Key "$API_KEY"

MCP OAuth ​

HTTP and SSE MCP servers that require OAuth can use Crush's built-in authorization-code flow instead of a static Authorization header. Set "oauth": true to enable it:

json
{
    "mcp": {
        "linear": {
            "type": "http",
            "url": "https://mcp.linear.app/mcp",
            "oauth": true
        }
    }
}

Pre-registered clients ​

Some servers (GitHub, Slack) don't support dynamic client registration. For those, register an OAuth app with the provider and supply the credentials directly. All values support shell expansion:

json
{
    "mcp": {
        "github": {
            "type": "http",
            "url": "https://api.github.com/mcp/",
            "oauth": true,
            "oauth_client_id": "Iv1.abc123def456",
            "oauth_client_secret": "$GITHUB_MCP_SECRET",
            "oauth_callback_port": 40704
        }
    }
}

When oauth_client_id is set, Crush skips dynamic client registration and authenticates as the specified client. When omitted, Crush attempts dynamic registration automatically (works with Linear, Notion, and other servers that support RFC 7591).

Sessionless servers ​

Some HTTP MCP servers are sessionless — they never issue a Mcp-Session-Id and reject the subscriptions/listen stream Crush opens for list-changed notifications, which would otherwise break the connection. Crush auto-detects known sessionless servers (GitHub MCP, api.githubcopilot.com/mcp), so those need no extra configuration.

For other sessionless servers, mark them explicitly with "sessionless": true (or --sessionless true in crushrc); set it to false to force the default behavior for an auto-detected URL. The tradeoff is that a sessionless server won't push live tool/prompt/resource list-changed notifications.

Command Reference ​

Manage Model Context Protocol servers.

text
Usage:
  mcp [command]

Available Commands:
  add       Add or update an MCP server
  remove    Remove an MCP server
  rm        Alias for remove

mcp add ​

Add an MCP server, or update an existing server with the same name.

text
Usage:
  mcp add <name> [flags]

Flags:
      --type string              stdio, sse, or http (default "stdio")
      --command string           executable for stdio servers
      --args string              command argument (repeatable)
      --env key value            environment variable (repeatable)
      --url string               URL for HTTP/SSE servers
      --header key value         HTTP header (repeatable)
      --timeout int              startup timeout in seconds
      --disabled bool            disable without removing
      --disabled-tools string       deny a server tool (repeatable)
      --enabled-tools string        allow only these server tools (repeatable)
      --oauth bool                  enable OAuth 2.1 flow (HTTP only)
      --oauth-client-id string      pre-registered OAuth client ID
      --oauth-client-secret string  pre-registered OAuth client secret
      --oauth-callback-port int     fixed localhost port for the OAuth callback
bash
mcp add github --type http \
  --url "https://api.githubcopilot.com/mcp/" \
  --header Authorization "Bearer $GH_PAT"

As with providers, a header whose value resolves to the empty string is dropped from the outgoing request.

mcp remove ​

Remove an MCP server.

text
Usage:
  mcp remove <name>
  mcp rm <name>