Cerebro MCP Server¶

Cerebro MCP is a Model Context Protocol server that connects AI assistants to Gnosis Chain's on-chain analytics infrastructure. It exposes 190+ tools that query a ClickHouse data warehouse, traverse ~1,200 dbt models, drive ten interactive surfaces, and orchestrate multi-phase analytical workflows — all over a single MCP connection.

What is MCP?¶

The Model Context Protocol (MCP) is an open standard that lets AI hosts (Claude Desktop, VS Code, Claude Code, custom clients) connect to external tools and data sources through a unified interface. A single MCP server can serve every MCP-compatible client without per-client integration work.

What's in this section¶

Architecture¶

flowchart TB
    H[MCP Host<br/>Claude Desktop / VS Code / Claude Code] -- stdio / HTTP / SSE --> S
    subgraph S[cerebro-mcp - FastMCP]
      direction TB
      T[Tool Registry<br/>190+ tools] --> CH[ClickHouse Client]
      T --> D[dbt Manifest<br/>BM25 + networkx]
      T --> ES[(Event Log<br/>SQLite WAL)]
      T --> RS[(Research Store<br/>JSON)]
      T --> SB[(Sandboxes<br/>DuckDB + Parquet)]
      T --> UI[Mini-App Bundles<br/>React + ECharts]
    end
    CH --> CHC[(ClickHouse Cloud<br/>Gnosis Chain)]

The server multiplexes four persistence layers:

1. Event log (~/.cerebro/cerebro_state.db) — append-only SQLite WAL holding workflows / events / gates. Powers crash recovery and resume hints. See Memory & Resume.
2. Research JSON store (~/.cerebro/research_projects/) — durable per-project state.
3. Sandbox snapshots (~/.cerebro/sandboxes/) — DuckDB + Parquet for what-if simulations.
4. In-memory singletons — storyteller phase machine, session counters.

At a glance¶

Transport modes¶

stdio (default)¶

Local-only. Claude Desktop / Claude Code spawn cerebro-mcp as a subprocess and talk over stdin/stdout.

cerebro-mcp

Streamable HTTP (remote, recommended)¶

For team deployments. Serves the MCP Streamable HTTP endpoint at /mcp and dual-serves the legacy /sse endpoint from the same server.

cerebro-mcp --http
# Defaults to 0.0.0.0:8000 — bind via FASTMCP_HOST / FASTMCP_PORT

SSE (remote, legacy)¶

cerebro-mcp --sse

The hosted team instance is at mcp.analytics.gnosis.io with bearer-token auth. See Setup for client configuration and the transport environment variables.

Capability summary¶

Discovery & query¶

• ~1,200 dbt models across 14 modules (execution, consensus, bridges, p2p, contracts, ESG, probelab, crawlers, celo, mixpanel_ga, mta, mmm, quarterly_data, revenue).
• Unified discovery: the find(query, mode) router answers "what do I use for X?" in one call with a pre-filled recommended_action; list(kind=...) unifies the listing family; the opt-in lean core (LEAN_CORE_ENABLED + load_tools) trims the advertised surface to ~18 everyday tools. See Finding Tools.
• Hybrid BM25 + RRF search (search_models, discover_models) — hit@1 improved 4× over the legacy ranker (see Hybrid Search).
• Data Catalog: OpenMetadata-style search + entity profiles over models, metrics, and glossary terms, with Elementary-backed run/test health. See Data Catalog.
• Deterministic networkx lineage (get_upstream_lineage, get_downstream_impact).
• Column-scoped schema injection for wide tables (get_relevant_columns).
• 5.3M+ Dune address labels, token metadata, ENS / Safe / Circles / GPay resolution.
• Bulk on-chain RPC scans (rpc_scan_logs, rpc_batch_call, rpc_scan_traces, …) that stream logs, view-call sweeps, storage slots, bytecode, and traces into ClickHouse scratch tables for SQL analysis. See RPC Scans.

Visualisation & reporting¶

• Batch chart generation with ECharts (generate_charts).
• Three report layouts: dashboard (generate_report), research essay (generate_research_report), scrollytelling case study (generate_case_study_report).
• Eight enforcement gates on generate_report (stock/flow discipline, residual buckets, stationarity, aggregator dedup, discovered-model coverage, …). See Quality Gates.
• Reports render as native UI in MCP-aware hosts; standalone HTML at ~/.cerebro/reports/.
• Grafana dashboard publishing: preview → validate → verify → publish, idempotent by UID with live per-panel data checks (GRAFANA_TOOLS_ENABLED). See Grafana Publishing.

Workflows¶

• Research projects — multi-phase plan/execute/verify with peer-review gate.
• Storyteller — eight-step narrative pipeline (context brief → big idea → storyboard → visual specs → final story).
• Simulation sandboxes — DuckDB + Parquet what-if isolation.
• Resumable workflows — every workflow phase logged; list_resumable_workflows recovers from crashes.

Mini-apps¶

Ten React + ECharts interactive surfaces that render inline in MCP-aware hosts: Report Renderer, Portfolio, Graph Explorer, Metric Lab, Contract Explorer, Model Lineage, Data Catalog, CoW Explorer, Governance Explorer, Report Studio. Each is also delivered as a standalone web app at GET /app/{app_id} on the HTTP/SSE server. See Mini-Apps.

Safety¶

• Read-only ClickHouse SQL (allowlisted statements, identifier validation, row + time caps).
• Tool-risk classification with detection-first JSONL audit log.
• Optional multi-tenant identity via SHA-256 owner hash on every workflow.
• 30-day reasoning trace retention with auto-redaction of secrets.

Where to go next¶

• New users → Setup → Usage Guide.
• Looking for a tool? → Available Tools.
• Building a report? → Report Generation + Quality Gates.
• Long-running analysis crashed? → Resumable Workflows.
• Want to write narrative deliverables? → Storyteller.
• Running counterfactuals? → Simulation Sandboxes.
• Dashboards / specific data? → Mini-Apps.