bgphorizon-mcp

An MCP server that exposes BGPHorizon — global BGP routing intelligence — to any MCP-capable LLM client (Claude Code, Claude Desktop, Cursor, Gemini CLI, OpenAI Agents, …).

It is not a thin wrapper over the REST API. The surface is 15 task-shaped tools built around the operations investigators and operators actually perform, each returning aggregates plus warnings[] so a model cannot silently misread the data (persistence, single-vantage-point concentration, censored first_seen, …).

LLM client ──stdio│http──► bgphorizon-mcp ──► BGPHorizon /api/v1 ──► ClickHouse
                            (key auth, metering, tier entitlements inherited)

Install & run

The server needs a BGPHorizon API key (create one in your account's API panel), passed as BGPHORIZON_API_KEY.

Zero-install with uv:

export BGPHORIZON_API_KEY=bgps_xxx
uvx bgphorizon-mcp --selftest      # ✓ API reachable ✓ key valid ✓ 15 tools ✓ 8 resources ✓ 7 prompts

uvx bgphorizon-mcp fetches and runs on demand — nothing to install first. Or install it as a tool (uv tool install bgphorizon-mcp) / with pipx (pipx install bgphorizon-mcp).

From source:

git clone <this-repo> && cd bgphorizon-mcp
uv sync
uv run bgphorizon-mcp --selftest

Connect it

You can either use the hosted endpoint (nothing to install) or self-host (this repo). Both authenticate with the same bgps_ API key and go through the same metered /api/v1.

Hosted endpoint (no install)

claude mcp add --transport http bgphorizon https://bgphorizon.com/mcp \
  --header "Authorization: Bearer bgps_xxx"

{
  "mcpServers": {
    "bgphorizon": {
      "url": "https://bgphorizon.com/mcp",
      "headers": { "Authorization": "Bearer bgps_xxx" }
    }
  }
}

Self-hosted with Claude Code

claude mcp add bgphorizon --env BGPHORIZON_API_KEY=bgps_xxx -- uvx bgphorizon-mcp

Claude Desktop / Cursor / Zed (mcpServers block)

{
  "mcpServers": {
    "bgphorizon": {
      "command": "uvx",
      "args": ["bgphorizon-mcp"],
      "env": { "BGPHORIZON_API_KEY": "bgps_xxx" }
    }
  }
}

Point at a non-production API with "BGPHORIZON_API_URL" in the same env block.

Hosted / HTTP transport

bgphorizon-mcp --transport http --port 8931 --require-auth

Put it behind TLS with proxy_buffering off for streaming. See docs/SETUP.md for every client (Gemini CLI, OpenAI Agents SDK, LangChain, n8n, VS Code) and reverse-proxy config.

What's in the box

Investigation tools (12): identify, inventory, timeline, origin_history, reachability, detections, paths, compare_windows, locate, subprefixes, events_sample, platform_baseline.

Operator tools (3): health_check, validate_announcement, visibility.

Resources (8): bgphorizon://reference/{detection-types, collectors, glossary, data-horizon, report-template, writing-guide, qa-checklist, methodology} — reference the model can pull without a tool call. report-template ships with the house CSS already inlined, and the report standards are all here, so a hosted (no-clone) client still writes house-style reports.

Prompts (7): investigate_entity, write_report, triage_incident, locate_infrastructure, audit_my_network, preflight_change, explain_incident — where the house methodology lives. In Claude Code they surface as /bgphorizon:audit_my_network, etc.

Full tool contracts: docs/TOOLS.md. Design rationale and full docs: https://bgphorizon.com/docs/mcp.

Writing investigative reports

The server ships a complete report kit and a write_report prompt so you can generate defensible, house-style BGP routing reports from any client — Claude Code, Claude Desktop, OpenAI (Codex / Agents / ChatGPT), Gemini CLI, Cursor, and more.

It's three steps: connect the server → set your agent's system prompt to reporting/SYSTEM-PROMPT.md → ask for the report. The per-client, copy-paste guide is in reporting/README.md.

Configuration

Env var	Default	Purpose
BGPHORIZON_API_KEY	—	API key, forwarded as Authorization: Bearer.
BGPHORIZON_API_URL	https://bgphorizon.com	BGPHorizon base URL.
BGPHORIZON_TIMEOUT	30	Per-request timeout (seconds).
BGPHORIZON_LOG_LEVEL	INFO	DEBUG surfaces every upstream request.

Develop

uv sync --group dev
uv run pytest            # deterministic reshaping logic (transitions, direction, …)
uv run bgphorizon-mcp --selftest
npx @modelcontextprotocol/inspector uv run bgphorizon-mcp   # raw protocol inspection

Layout: client.py (one method per /api/v1 endpoint) · tools/ (analytical operations + _shape.py pure helpers) · resources.py + reference/ (bundled docs) · prompts.py (methodology). Adding a tool = one function under tools/ with an @mcp.tool() decorator; the input schema comes from its type hints.

License

MIT.