MCPs

Crush supports the Model Context Protocol (MCP) for extending its capabilities with external tools and data sources.

Transport Types

MCP servers are supported through three transport types:

• stdio: Command-line servers
• http: HTTP endpoints
• sse: Server-Sent Events

Configuration

Shell-style value expansion ($VAR, ${VAR:-default}, $(command), quoting, nesting) works in command, args, env, headers, and url, so file-based secrets work out of the box. You can use values like "$TOKEN" or "$(cat /path/to/secret/token)". Expansion runs through Crush's embedded shell, so the same syntax works on every supported system, Windows included.

Unset variables expand to the empty string by default, matching bash. For required credentials, use ${VAR:?message} so an unset variable fails loudly at load time with message instead of silently resolving to empty:

{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }

Headers (both MCP headers and provider extra_headers) whose value resolves to the empty string are dropped from the outgoing request rather than sent as Header:. That keeps optional env-gated headers like "OpenAI-Organization": "$OPENAI_ORG_ID" clean when the variable is unset.

Provider extra_body is a non-expanding JSON passthrough; put env-driven values in extra_headers or the provider's api_key / base_url, all of which do expand.

Security note: crush.json is trusted code. Any $(...) in it runs at load time with your shell's privileges, before the UI appears. Don't launch Crush in a directory whose crush.json you haven't reviewed.

stdio

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["some-tool-name"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

http

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["create_issue", "create_pull_request"],
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    }
  }
}

sse

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "streaming-service": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "timeout": 120,
      "disabled": false,
      "headers": {
        "API-Key": "$(echo $API_KEY)"
      }
    }
  }
}

Disabling MCP Tools

You can disable specific tools from an MCP server without disabling the entire server using disabled_tools:

{
  "mcp": {
    "github": {
      "disabled_tools": ["create_issue", "create_pull_request"]
    }
  }
}