API, MTR client and
MCP for AI assistants

The BGPScout API lets you query network data, retrieve ASN details, and submit traceroute results. All responses are JSON unless otherwise noted.

Base URL: https://bgpscout.io/api

Public endpoints need no credentials. Endpoints that write data - or that read your account's data - require an API key in the X-API-Key header.

Trace processing pipeline

Every traceroute submitted to BGPScout goes through a multi-stage enrichment pipeline before being included in any analysis or public results:

1. Submission - raw MTR/traceroute data is received via the API or RIPE Atlas.
2. Enrichment - each hop IP is resolved to an ASN (via BGP prefix tables), geolocated (via geofeed, IPinfo, MaxMind), and classified (anycast, IXP, cloud, etc.).
3. Quality scoring - a 0-10 data quality score is computed from PTR record coverage, geo coverage, hop completion ratio, and path coherence.
4. Display gating - traces scoring ≤ 2 are auto-rejected. Scores 3-5 go to pending review. Scores 6+ are auto-approved. Only approved traces appear in search results and analysis.

Boomerang detection

A "boomerang route" is detected when a traceroute from country A to a destination also in country A transits a different country. That indicates suboptimal routing where domestic traffic unnecessarily crosses international borders.

Data sources

• Traceroutes - user-submitted MTR tests, RIPE Atlas measurements, automated probes in 30+ countries
• ASN data - ARIN, RIPE NCC, APNIC, LACNIC, AFRINIC registry data
• PeeringDB - facility presence, IXP memberships, port speeds
• GeoIP - geofeed (RFC 8805), IPinfo, MaxMind, PTR hostname analysis
• Domain intelligence - Certificate Transparency, DNS enumeration, WHOIS

Some endpoints require an API key passed in the X-API-Key HTTP header. Public endpoints do not require authentication.

To obtain a key, log in and visit Account Settings. Organisation accounts can also issue org-wide keys from the org dashboard.

curl -H "X-API-Key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"traces": []}' \
     https://bgpscout.io/api/traceroutes/submit

REST API endpoints under /api are limited to 300 requests per 15-minute window, bucketed by client IP address. Exceeding the limit returns 429 with a JSON error body.

Response headers

429 response

{
  "success": false,
  "error": "Rate limit exceeded. Please slow down and try again later."
}

Two methods, both accepted on the same endpoint:

Get a key from Account Settings. An unauthenticated call returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which is what lets an OAuth-capable client start the login flow on its own.

Check your key works

curl -s -X POST https://bgpscout.io/mcp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The 160 tools are grouped into categories below, generated live from the same registry /mcp/docs renders - this list cannot drift from the server the way a hand-typed copy did (#258). The list_tools tool does the same from inside a conversation - call it first, optionally with a category, instead of loading everything.

Three more tools appear when your account belongs to an organisation, and 10 admin-only tools exist beyond that (not listed above - internal operational tools, not part of the documented public surface). Everything is access-checked server-side, so a tool you cannot use never appears in your list.

Focusing the tool list

160 tools is a lot of context for one conversation. The server publishes curated subsets you can paste into a client that supports a function-name filter (OpenWebUI, for example), generated from the same TOOL_PRESETS the server itself uses:

Once the connector is live, ask in plain language. These are real questions the tool set answers:

Claude Code (CLI)

Add the server once, with your API key as a header:

claude mcp add --transport http bgpscout https://bgpscout.io/mcp \
  --header "X-API-Key: YOUR_API_KEY"

# confirm it registered
claude mcp list
claude mcp get bgpscout

The default scope is the current project. Add --scope user to make it available in all your projects, or --scope project to share it with your team through a checked-in .mcp.json. Inside a session, /mcp shows connection status.

Claude Code with OAuth instead of a key

Register the server without a header, then authenticate in the browser - useful if you would rather not store a key in a config file:

claude mcp add --transport http bgpscout https://bgpscout.io/mcp
# then, inside Claude Code:
#   /mcp  →  select "bgpscout"  →  Authenticate

claude.ai and Claude Desktop (custom connector)

1. Open Settings → Connectors.
2. Click Add custom connector.
3. Paste the URL https://bgpscout.io/mcp and click Add.
4. Click Connect. You are sent to BGPScout to sign in with Google or PeeringDB, then back to Claude with the tools enabled.

To connect BGPScout to ChatGPT as an MCP app:

1. Go to ChatGPT Settings → Apps → Add App.
2. Set Name to bgpscout.io.
3. Set MCP Server URL to https://bgpscout.io/mcp.
4. Set Authentication to OAuth.
5. Leave Registration method on Dynamic Client Registration. BGPScout implements RFC 7591 at /oauth/register and advertises it in its metadata, so the client registers itself and is issued a client ID automatically - there is no fixed ID to paste.
6. Only if your client cannot do dynamic registration, register once by hand and use the ID it returns:

   curl -X POST https://bgpscout.io/oauth/register \
     -H 'Content-Type: application/json' \
     -d '{"client_name":"My Client","redirect_uris":["https://example.com/callback"]}'

   The response contains the client_id to use below. Client secrets are not issued: this is a public client, so token_endpoint_auth_method is none and PKCE (S256) is mandatory.
7. The remaining fields:

   OAuth Client ID	From dynamic registration, or the client_id returned above
   OAuth Client Secret	Leave empty
   Token endpoint auth method	none
   Auth URL	https://bgpscout.io/oauth/authorize
   Token URL	https://bgpscout.io/oauth/token

8. Check "I understand and want to continue", then click Create.

OAuth endpoints reference

Grant types are authorization_code and refresh_token. PKCE is mandatory - the authorization endpoint requires a code_challenge with code_challenge_method=S256 and rejects anything else. Before a code is issued you see an explicit consent screen naming the application and the scopes it asked for; nothing is granted silently.

Cursor reads .mcp.json. Add BGPScout with an API key header - the same block works in any config-file client:

{
  "mcpServers": {
    "bgpscout": {
      "type": "http",
      "url": "https://bgpscout.io/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Get the key from Account Settings. Cursor does not do the OAuth flow that ChatGPT and claude.ai use, so the header is the route here.

Add an OpenAPI tool server pointing at https://bgpscout.io/mcp (spec at /mcp/openapi.json), with auth set to Bearer and your API key as the token.

160 tools is a lot of context for one conversation. OpenWebUI supports a function-name filter, so paste one of the curated presets from the Tool catalogue into it to narrow what loads.

Returns aggregate statistics about all collected traceroutes, plus a breakdown of the source countries they came from.

Example request

curl https://bgpscout.io/api/traceroutes/stats

Example response

Live values, captured when this page was rendered.

{
  "success": true,
  "stats": {
    "total_traces": 283361,
    "source_countries": 146,
    "unique_destinations": 9036,
    "unique_source_asns": 3654,
    "boomerang_count": "482",
    "leaves_country_count": "50450",
    "leaves_canada_count": "32088",
    "earliest_trace": "2026-04-02T14:24:53.000Z",
    "latest_trace": "2026-08-29T09:15:10.000Z"
  },
  "top_source_countries": [
    { "source_country": "CA", "trace_count": 75260 },
    { "source_country": "US", "trace_count": 24103 }
  ]
}

Submit one or more traceroute results for storage and analysis.

Headers

Request body

{
  "traces": [
    {
      "host": "example.com",
      "dest_ip": "93.184.216.34",
      "source_ip": "192.168.1.1",
      "source_country": "CA",
      "platform": "linux",
      "tool": "mtr",
      "completed": true,
      "hops": [
        {
          "hop_number": 1,
          "ip": "192.168.1.1",
          "hostname": "gateway.local",
          "rtt_avg": 1.2,
          "rtt_min": 0.8,
          "rtt_max": 2.1,
          "loss_pct": 0
        },
        {
          "hop_number": 2,
          "ip": "10.0.0.1",
          "rtt_avg": 5.4
        }
      ]
    }
  ]
}

Hop fields

Example response

{
  "success": true,
  "trace_ids": [1042, 1043],
  "count": 2
}

Error response

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "trace_index": 0, "errors": ["Invalid dest_ip format"] }
  ]
}

Returns core information about an ASN, including peering quality and route scoring. For observed BGP adjacency (who this ASN is upstream/downstream of), see GET /api/asn/:asn/neighbours below.

Parameters

Example request

curl https://bgpscout.io/api/asn/577

Example response

{
  "asn": 577,
  "name": "Bell Canada Backbone",
  "country": "CA",
  "rir": "ARIN",
  "traffic_level": null,
  "network_type": "NSP",
  "on_ix": true,
  "peering_quality": {
    "crossing_rate": 6.33,
    "quality_tag": "good_peering"
  },
  "route_score": {
    "quality": 5.4,
    "route": 7.3,
    "overall": 6.4
  },
  "url": "https://bgpscout.io/asns/577"
}

Every ASN observed adjacent to this one in BGP AS_PATH data, in both directions - what the source historically used for ASN classification calls its #peers tab, while bgp.he.net shows on every ASN page. Same shape and same field names as the MCP tool get_asn_neighbours.

Example request

curl https://bgpscout.io/api/asn/33185/neighbours

Example response

Abridged, against the live table on 2026-08-24 (27 neighbours for AS33185). The neighbour arrays are trimmed here; the counts are real.

{
  "asn": 33185,
  "known": true,
  "neighbour_count": 27,
  "seen_upstream_ward_count": 5,
  "seen_downstream_ward_count": 22,
  "returned": 27,
  "limit": 100,
  "truncated": false,
  "seen_upstream_ward": [
    { "asn": 1299, "name": "Arelion (fka. Telia Carrier)", "country": "SE", "observations": 251, "peer_count": 9 },
    { "asn": 3257,  "name": "GTT Communications Inc.",     "country": "US", "observations": 151, "peer_count": 7 },
    { "asn": 6939,  "name": "Hurricane Electric LLC",       "country": "US", "observations": 125, "peer_count": 9 },
    { "asn": 174,   "name": "Cogent Communications, LLC",   "country": "US", "observations": 95,  "peer_count": 3 }
  ],
  "seen_downstream_ward": [
    { "asn": 398292, "name": "Babish Telecom", "country": "CA", "observations": 102, "peer_count": 17 }
  ],
  "observed_from": {
    "collectors": ["route-views.chicago", "route-views.eqix", "...", "rrc24"],
    "collector_count": 12,
    "collectors_unreachable_that_run": [],
    "built_at": "2026-08-22",
    "min_collector_peers_required": 2
  },
  "notes": {
    "relationship": "AS_PATH does not label relationships. An adjacency may be transit OR settlement-free peering OR a sibling, and it is not proof that money changes hands.",
    "direction": "\"seen_upstream_ward\" means the neighbour was observed further from the origin in observed paths, and \"seen_downstream_ward\" nearer to it. That is an observation, not proven hierarchy - leaks and siblings break it.",
    "coverage": "Observed from 12 BGP route collectors (8 RouteViews + 4 RIPE RIS) on 2026-08-22: route-views.chicago, route-views.eqix, ... rrc24.",
    "coverage_limit": "This is a FLOOR, not a peer census, and adding collectors does not lift the ceiling much ..."
  }
}

Fields

Returns a self-contained HTML card for an ASN that can be embedded in an iframe. It shows the ASN name, country, peering-quality badge, route score, and a link back to BGPScout.

Usage

<iframe src="https://bgpscout.io/api/embed/asn/577"
        width="320" height="200"
        frameborder="0"></iframe>

BGPScout can POST an alert to an HTTPS endpoint you own, so a watch rule reaches your NOC without anyone opening BGPScout. Every request is signed with a per-destination HMAC-SHA256 secret. This section is the receiver's contract: the payload schema, the headers, and the exact verification recipe.

Requirements for your endpoint

Payload

The body is JSON, version-stamped by schema_version. Fields are added compatibly within a version; a receiver should ignore fields it does not recognise.

{
  "schema_version": 1,
  "event_id": "watchlist_alert:13112",
  "event_type": "ixp_joined",
  "occurred_at": "2026-08-26T02:14:07.000Z",
  "severity": null,
  "subject": { "type": "asn", "id": "64500" },
  "summary": "AS64500 joined DE-CIX Frankfurt (seen 2026-08-25) [rule: my rule]",
  "facts": {},
  "evidence": [],
  "links": { "reference": "/asns/64500" },
  "test": false
}

Headers

Verifying the signature

1. Read the BGPScout-Timestamp header and the raw request body exactly as received. Do not re-serialise the parsed JSON: key order and whitespace are part of what was signed.
2. Reject the request if abs(now - timestamp) exceeds your replay window. We recommend 300 seconds. This is what makes a captured request unreplayable, because the signature covers the timestamp.
3. Compute HMAC-SHA256(secret, timestamp + "." + rawBody) and hex-encode it.
4. Compare it against the value after v1= using a constant-time comparison. Never use a plain string equality on a secret-derived value.
5. During a secret rotation the sender may sign with either the current or the previous secret for a 24 hour overlap. A receiver holding both should accept either.

// Node.js reference implementation. Note express.raw:
// a JSON body parser would destroy the exact bytes that were signed.
const crypto = require('crypto');

app.post('/bgpscout-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts  = req.get('BGPScout-Timestamp');
  const sig = req.get('BGPScout-Signature') || '';
  const raw = req.body;                      // a Buffer, unparsed

  if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 300) {
    return res.status(400).send('stale timestamp');
  }

  const expected = crypto.createHmac('sha256', YOUR_SECRET)
                         .update(ts + '.' + raw.toString('utf8'))
                         .digest('hex');
  const given = Buffer.from(sig.replace(/^v1=/, ''), 'hex');
  const want  = Buffer.from(expected, 'hex');
  if (given.length !== want.length || !crypto.timingSafeEqual(given, want)) {
    return res.status(401).send('bad signature');
  }

  // Dedupe on the event id: delivery is at-least-once.
  if (alreadyHandled(req.get('BGPScout-Event-Id'))) return res.status(200).end();

  res.status(200).end();          // acknowledge FIRST, then do the work
  handleEvent(JSON.parse(raw));
});

The BGPScout MTR client collects traceroute data and submits it to the API automatically.

Download

Download latest release

Installation

# Linux / macOS
chmod +x bgpscout-mtr
sudo mv bgpscout-mtr /usr/local/bin/

# Verify installation
bgpscout-mtr --version

Configuration

# Set your API key (from /account)
bgpscout-mtr config --api-key YOUR_API_KEY

# Optionally set your source ASN
bgpscout-mtr config --source-asn 64500

Usage

# Run a single trace
bgpscout-mtr trace example.com

# Run against Tranco top sites (batch mode)
bgpscout-mtr batch --targets tranco-top100.txt

# Run with automatic submission
bgpscout-mtr trace --submit example.com

# Schedule recurring traces (cron-friendly)
bgpscout-mtr batch --targets targets.txt --submit --quiet

Example output

$ bgpscout-mtr trace --submit google.ca
Tracing google.ca (142.250.80.67)...
 1  gateway.local (192.168.1.1)    1.2ms
 2  10.0.0.1                       5.4ms
 3  isp-core.example.net           12.1ms
 ...
Submitted trace ID: 1042