MCP Server

Overview

The Model Context Protocol (MCP) lets a language model call tools on your behalf. Each BGPHorizon tool covers one question, such as who holds a prefix, whether an origin change persisted, or whether an ASN's RPKI is clean. Results include warnings for the common misreadings: a transient announcement taken for a migration, or a single collector taken for the whole internet.

Both routes call the same metered /api/v1 with your API key. Self-hosting does not change your limits or what you can access.

Connect a client

The hosted endpoint is https://bgphorizon.com/mcp. Clients that support MCP sign-in (OAuth) only need that URL: they open a BGPHorizon page where you sign in and allow access. Other clients use an API key, which you create in your User Panel → API. Keys start with bgps_.

Hosted endpoint, with sign-in

Claude Desktop and claude.ai: open Settings → Connectors, choose Add custom connector, and enter https://bgphorizon.com/mcp. A BGPHorizon page opens; sign in and click Allow. Nothing to install.

Claude Code:

claude mcp add --transport http bgphorizon https://bgphorizon.com/mcp

Then run /mcp, select bgphorizon and choose Authenticate.

Cursor, VS Code and other clients with MCP sign-in: add the server by URL only:

{
  "mcpServers": {
    "bgphorizon": { "url": "https://bgphorizon.com/mcp" }
  }
}

Access lasts 90 days, after which the client asks you to sign in again. Each sign-in creates a key named after the client in your API tab. It counts toward your daily API allowance, and revoking it there disconnects the client. Signing in requires an account with API access.

Hosted endpoint, with an API key

For scripts, agents and clients without MCP sign-in, send the key as a bearer token. Claude Code:

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

Config files that accept a remote url with headers (Cursor and similar):

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

Claude Desktop's config file only starts local programs, so an API key there needs the mcp-remote bridge and Node.js. Use the connector above instead unless you need a fixed key. The config is in the setup guide.

ChatGPT / OpenAI Responses API (hosted MCP):

tools=[{
  "type": "mcp",
  "server_label": "bgphorizon",
  "server_url": "https://bgphorizon.com/mcp",
  "authorization": "Bearer bgps_your_key_here",
  "require_approval": "never"
}]

Self-hosted (local, via uv)

Clone the repository and let uv handle the environment. The package is not on PyPI yet, so uvx bgphorizon-mcp will not resolve; use the checkout, or the hosted endpoint above, which needs no install at all.

git clone https://github.com/bgphorizon/bgphorizon-mcp.git
cd bgphorizon-mcp && uv sync

claude mcp add bgphorizon \
  --env BGPHORIZON_API_KEY=bgps_your_key_here \
  -- uv run --directory "$PWD" bgphorizon-mcp

Or in a config file:

{
  "mcpServers": {
    "bgphorizon": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bgphorizon-mcp", "bgphorizon-mcp"],
      "env": { "BGPHORIZON_API_KEY": "bgps_your_key_here" }
    }
  }
}

Verify any setup with uv run bgphorizon-mcp --selftest. It prints ✓ API reachable ✓ key valid ✓ 25 tools ✓ 9 resources ✓ 8 prompts. In Claude Code, run /mcp to confirm it's connected.

Authentication

The hosted endpoint reads a bearer token from the Authorization header on each request: either a key from your API tab or the key issued when you sign in through a connector. A request without a valid token gets an HTTP 401 that tells the client where to sign in. The self-hosted server reads the key from BGPHORIZON_API_KEY. Usage is metered per key, and tier entitlements (history window, detections, firehose) apply exactly as they do in the web app. Over-quota and permission errors come back as structured tool errors, so the model can explain the limit rather than retry blindly.

Tools (25)

Every tool returns warnings[] (may be empty) and a meta block with source (rollup / raw_events / registry / composed). Give ASNs with or without AS; prefixes as plain CIDR.

Investigation analyzing a network you don't run

Operator watching a network you own

Your monitoring your own alerts, for reports

Resources (9)

Read-only reference material. Reading a resource does not count as a tool call.

• bgphorizon://reference/detection-types: every detection type, its severities, and how to read actor_as against baseline_asns.
• bgphorizon://reference/collectors: the RouteViews and RIPE RIS collectors, and how to use concentration metadata.
• bgphorizon://reference/glossary: BGP terms in plain language, for use in report output.
• bgphorizon://reference/data-horizon: the retention floor, rollup versus raw events, why first_seen is not a persistence signal, why withdrawals have no origin, how far relationship data lags, and what counts as a covering holder.
• bgphorizon://reference/report-template: the HTML report skeleton with the stylesheet already inlined.
• bgphorizon://reference/writing-guide: the style rules for reports.
• bgphorizon://reference/qa-checklist: the checks to run before publishing a report.
• bgphorizon://reference/methodology: the investigation procedure.
• bgphorizon://reference/report-examples: published reports with the error each one caught in review.

Prompts (8)

Guided workflows that follow the methodology. In Claude Code they appear as slash commands, for example /bgphorizon:audit_my_network.

• investigate_entity: full workup of an ASN or prefix, findings only. For a suspected hijack or leak by one network it starts from origin_episode and origin_reach.
• write_report: a complete HTML report using the methodology and template. It asks first whether you want to review the findings before it writes, so you can question or correct them while the report is still a draft.
• alert_report: pull your alerts for a period and write them up, separating security findings from routine registry changes.
• triage_incident: a quick verdict: real event, measurement artifact, or nothing.
• locate_infrastructure: geolocation from routing data, with a stated confidence.
• audit_my_network: hygiene report for your ASN with prioritized remediation.
• preflight_change: go or no-go for an announcement or renumbering.
• explain_incident: plain-language incident summary for a non-technical reader.

Write your own investigative reports

The server ships the methodology and templates used for BGPHorizon reports, so a connected model can produce a complete report. The write_report prompt runs the process.

Run it. In Claude Code:

/bgphorizon:write_report AS54994 over the last 60 days

It asks whether you want to review the findings before it writes. Say yes and it gathers the evidence, then stops and walks you through what it found, numbered, with the confidence behind each one and what it could not determine. You can question it, ask for more lookups, or correct it from what you know about the network while the report is still a draft. If your input changes a conclusion, the report records the correction.

What cloning adds: the two scripts the server cannot run for you. style-lint.py checks the prose against the banned list, and build-report.sh inlines the CSS, validates the HTML, runs that lint, and renders a PDF and PNG. Clone when you want the build to fail on a style violation and to get rendered output. The standards are the same either way.

git clone https://github.com/bgphorizon/bgphorizon-mcp
./reporting/build-report.sh my-report.html

The method requires two checks, and the tools' warnings enforce them: confirm persistence before describing a change (a prefix seen for a few days is transient, not a migration), and confirm attribution before describing an anomaly (a spike from one collector is a measurement artifact).

The same methodology, writing guide, HTML template, QA checklist and worked examples are also on disk under reporting/ in the GitHub repository, for editing or for use without a connected server.

Self-host from GitHub

The server is open source. Fork it, read the tools, add your own. A self-hosted server still calls the metered /api/v1 with your key, so your access does not change.

Repository: https://github.com/bgphorizon/bgphorizon-mcp

From source:

git clone https://github.com/bgphorizon/bgphorizon-mcp && cd bgphorizon-mcp
uv sync
export BGPHORIZON_API_KEY=bgps_your_key_here
uv run bgphorizon-mcp --selftest

Host the HTTP transport yourself:

uv run bgphorizon-mcp --transport http --port 8931

Troubleshooting