Setup Guide¶

This guide covers how to install Cerebro MCP and connect it to Claude Desktop, VS Code, and Claude Code.

Prerequisites¶

• Python 3.10+
• Node.js 20+ (for building the report UI)
• ClickHouse Cloud credentials for the Gnosis Chain instance (or access to the hosted endpoint)

Installation¶

From Source¶

git clone https://github.com/gnosischain/cerebro-mcp.git
cd cerebro-mcp

# Configure environment
cp .env.example .env
# Edit .env and set CLICKHOUSE_PASSWORD

# Build UI and install Python package
make install
# This runs: npm ci && npm run build -> pip install -e .

Docker¶

docker build -t cerebro-mcp .
docker run --env-file .env cerebro-mcp

Pre-built images are published to GitHub Container Registry on every push to main:

ghcr.io/gnosischain/gc-cerebro-mcp:latest
ghcr.io/gnosischain/gc-cerebro-mcp:<commit-sha>

Connecting to Claude Desktop¶

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Local Installation (stdio)¶

{
  "mcpServers": {
    "cerebro": {
      "command": "cerebro-mcp",
      "env": {
        "CLICKHOUSE_PASSWORD": "your_password"
      }
    }
  }
}

If cerebro-mcp is not on your PATH, use the full path to the executable or invoke via uv:

{
  "mcpServers": {
    "cerebro": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"],
      "env": {
        "CLICKHOUSE_PASSWORD": "your_password"
      }
    }
  }
}

Hosted Endpoint (Streamable HTTP)¶

Connect to the team-hosted instance at mcp.analytics.gnosis.io. If your deployment runs the current image (which starts with cerebro-mcp --http), the recommended endpoint is the Streamable HTTP path /mcp:

{
  "mcpServers": {
    "cerebro": {
      "url": "https://mcp.analytics.gnosis.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

If the client cannot set custom headers (for example, a native connector UI that only accepts a URL), append the token as a query parameter instead: https://mcp.analytics.gnosis.io/mcp?token=<your-token>. The Bearer header remains the preferred path -- query tokens can leak into access logs.

Hosted Endpoint (Legacy SSE)¶

Deployments still running the SSE-only transport (cerebro-mcp --sse), and current-image deployments during migration (--http dual-serves both), also accept the legacy /sse endpoint:

{
  "mcpServers": {
    "cerebro": {
      "url": "https://mcp.analytics.gnosis.io/sse",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Connecting to VS Code¶

Add the following to .vscode/mcp.json in your workspace, or to your user-level settings.json for global access.

Workspace Configuration (.vscode/mcp.json)¶

{
  "servers": {
    "cerebro": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"],
      "env": {
        "CLICKHOUSE_PASSWORD": "your_password"
      }
    }
  }
}

User Settings (settings.json)¶

{
  "mcp": {
    "servers": {
      "cerebro": {
        "command": "/path/to/uv",
        "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"],
        "env": {
          "CLICKHOUSE_PASSWORD": "your_password"
        }
      }
    }
  }
}

Hosted Endpoint¶

Use the Streamable HTTP endpoint /mcp if your deployment runs the current image; use the legacy /sse path for SSE-only deployments:

{
  "servers": {
    "cerebro": {
      "url": "https://mcp.analytics.gnosis.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Connecting to Claude Code¶

Claude Code supports MCP server configuration at both project and global scope.

Project-Level (.mcp.json)¶

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "cerebro": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"],
      "env": {
        "CLICKHOUSE_PASSWORD": "your_password"
      }
    }
  }
}

Global Configuration (~/.claude/.mcp.json)¶

For access across all projects:

{
  "mcpServers": {
    "cerebro": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"],
      "env": {
        "CLICKHOUSE_PASSWORD": "your_password"
      }
    }
  }
}

CLAUDE.md Instructions¶

You can also add instructions to your project's CLAUDE.md file to guide Claude Code on how to use the MCP tools effectively. The cerebro-mcp repository includes a CLAUDE.md with client-side instructions for optimal tool usage patterns.

Hosted Endpoint¶

Use the Streamable HTTP endpoint /mcp if your deployment runs the current image; use the legacy /sse path for SSE-only deployments:

{
  "mcpServers": {
    "cerebro": {
      "url": "https://mcp.analytics.gnosis.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Running a Remote Server¶

The server selects its transport from command-line flags, with precedence --http > --sse > stdio (no flag).

Streamable HTTP (Recommended)¶

To host your own remote instance:

cerebro-mcp --http
# Serves the MCP Streamable HTTP endpoint at /mcp
# and dual-serves the legacy /sse + /messages/ routes from the same process

Streamable HTTP is the modern, load-balancer-friendly MCP transport: a single /mcp endpoint, no long-lived idle stream for a proxy to reap, and -- with STREAMABLE_HTTP_STATELESS on (the default) -- no per-pod session affinity requirement, so requests can land on any replica. It is also the transport Claude Desktop's native remote connector speaks, removing the need for the mcp-remote bridge. Because --http dual-serves the legacy SSE routes, existing /sse clients keep working during migration -- a zero-downtime cutover rather than a hard switch.

The published Docker image starts with cerebro-mcp --http by default.

Client configuration points at the /mcp URL:

{
  "mcpServers": {
    "cerebro": {
      "url": "https://your-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

For clients that cannot set custom headers, /mcp additionally accepts the token as a query parameter: https://your-host.example.com/mcp?token=<your-token>. This is a fallback, not a replacement -- query tokens can leak into access logs, so prefer the Bearer header. The query-parameter fallback applies only to /mcp; the legacy /sse and /messages/ routes require the header.

Legacy SSE¶

To run the SSE-only transport (the previous remote default):

cerebro-mcp --sse
# Serves /sse + /messages/ only

Use this only if a client cannot speak Streamable HTTP and you do not want the dual-serving --http mode; new deployments should prefer --http.

Server Environment Variables¶

Both remote transports are configured with:

MCP_AUTH_TOKEN is required for both remote transports: the server refuses to start without it unless ALLOW_INSECURE_REMOTE_TRANSPORT=true. When set, all requests require an Authorization: Bearer <token> header (or, on /mcp only, the ?token= query parameter). The /health and /metrics endpoints bypass authentication for Kubernetes liveness/readiness probes and Prometheus scraping.

Multi-tenant identity¶

If multiple humans share one Cerebro deployment, set CEREBRO_OWNER to identify the caller. Cerebro hashes the value with CEREBRO_OWNER_HASH_SALT (SHA-256) and stamps every workflow row, so list_resumable_workflows and get_workflow_resume_hint can filter by owner. See Multi-Tenant for the full trust model.

stdio¶

{
  "mcpServers": {
    "cerebro": {
      "command": "cerebro-mcp",
      "env": {
        "CLICKHOUSE_PASSWORD": "your_password",
        "CEREBRO_OWNER": "alice@gnosis.io",
        "CEREBRO_OWNER_HASH_SALT": "rotate-me-quarterly"
      }
    }
  }
}

Remote (Streamable HTTP or SSE)¶

Send X-Cerebro-Owner per request:

{
  "mcpServers": {
    "cerebro": {
      "url": "https://mcp.analytics.gnosis.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "X-Cerebro-Owner": "alice@gnosis.io"
      }
    }
  }
}

If neither is set, workflows write owner=NULL and the server runs in single-tenant fallback mode.

Environment Variables¶

The authoritative source is src/cerebro_mcp/config.py (a pydantic Settings class); .env.example covers the common subset. The tables below list the variables you are most likely to touch.

Connectivity¶

Feature flags¶

Each flag gates the registration of a whole tool family — when off, the tools do not appear at all.

Web3 / RPC¶

Query and tool limits¶

Storage¶

Event log + workflows (Phase 3)¶

Sandboxes (Phase 2)¶

Multi-tenant¶

Remote transports / auth¶

Security Recommendations¶

Read-Only ClickHouse User¶

For production deployments, create a dedicated read-only database user:

CREATE USER mcp_reader IDENTIFIED BY '...';
GRANT SELECT ON execution.* TO mcp_reader;
GRANT SELECT ON consensus.* TO mcp_reader;
GRANT SELECT ON crawlers_data.* TO mcp_reader;
GRANT SELECT ON nebula.* TO mcp_reader;
GRANT SELECT ON dbt.* TO mcp_reader;
GRANT SELECT ON system.tables TO mcp_reader;
GRANT SELECT ON system.columns TO mcp_reader;

Token Rotation¶

When using a remote transport (--http or --sse) with MCP_AUTH_TOKEN, rotate the token periodically:

export MCP_AUTH_TOKEN=$(openssl rand -hex 32)

Verification¶

After configuring your client, verify the connection by asking your AI assistant:

• "Check the Cerebro system status"
• "List available databases"
• "Search for transaction models"

If the tools appear and respond, the connection is working correctly.

Troubleshooting¶

Testing with MCP Inspector¶

The MCP Inspector provides a web UI for testing tools interactively:

uv run mcp dev src/cerebro_mcp/server.py

This spawns the server with the Inspector UI, allowing you to call individual tools and inspect responses.