MCP Overview

​

Endpoints

​

Protocol negotiation

• By default, initialize supports both 2025-03-26 and 2025-06-18.
• Clients requesting 2025-06-18 receive 2025-06-18; clients pinned to 2025-03-26 continue receiving 2025-03-26.
• Setting MCP_PROTOCOL_FLOOR_2025_06_18=off pins the server back to the legacy 2025-03-26-only floor; a client that then requests 2025-06-18 receives the safe default 2025-03-26.

​

Streamable HTTP responses

• Clients that omit text/event-stream from Accept receive the standard JSON-RPC JSON response body.
• Clients that send Accept: application/json, text/event-stream can receive a text/event-stream response for successful JSON-RPC POSTs.
• initialize SSE responses include Mcp-Session-Id; follow-up POSTs should send that same Mcp-Session-Id header.
• Each SSE response carries the JSON-RPC result as a single message event with an event id. There is no leading empty priming event — per the WHATWG SSE spec an empty data: field still dispatches a message (with data === ""), which causes strict handshake scanners to fail on JSON.parse("").
• If the client disconnects after the sole event, it can reconnect by sending GET /mcp with Accept: text/event-stream, the same Mcp-Session-Id, and Last-Event-ID; resuming after the delivered event returns an empty stream. A client that dropped before receiving the event has no acknowledged Last-Event-ID and re-issues the POST instead.
• A bare GET /mcp — one without Last-Event-ID — is a client opening the optional standalone server→client SSE stream. This stateless edge route offers no server-initiated stream, so it answers 405 Method Not Allowed (advertising Allow), which the MCP spec defines as the graceful “no standalone stream” signal. MCP SDK clients handle this transparently and complete the handshake; the GET verb itself is reserved for the authenticated Last-Event-ID replay above.

​

Authentication

1. OAuth 2.1 bearer — Authorization: Bearer <token> where <token> was issued by /api/oauth/token. This is what Claude Desktop, claude.ai, Cursor, and MCP Inspector use automatically. Required for any client that hits MCP from a browser origin.
2. Direct API key — X-WorldMonitor-Key: wm_0123456789abcdef0123456789abcdef01234567 for user-issued keys, or an opaque operator-issued enterprise key. Intended for server-side scripts, curl, and custom integrations. Do not send an API key as a Bearer token — it will fail OAuth resolution and return 401 invalid_token.

​

Redirect URI allowlist

• https://claude.ai/api/mcp/auth_callback
• https://claude.com/api/mcp/auth_callback
• http://localhost:<port> / http://127.0.0.1:<port> (any port) — for Claude Code, MCP Inspector, local development

​

Token lifetimes

​

Pro sign-in flow

1. Add the server URL in your MCP client. The canonical entrypoint is:
   https://api.worldmonitor.app/mcp
   
   (https://worldmonitor.app/mcp works too — it proxies the same handler.)
2. Click “Sign in with WorldMonitor Pro” on the consent page. This is the default CTA. You’ll bounce through worldmonitor.app/mcp-grant (Clerk-protected — sign in if needed), then back to api.worldmonitor.app/oauth/authorize-pro, then to your client’s redirect.
3. Done. No wm_… key is created or stored on your machine. The client receives a standard OAuth 2.1 access token (1 h TTL, 7 d refresh).

​

Daily limit (Pro tier)

• 50 quota-consuming calls per UTC day, reset at 00:00 UTC.
• tools/call and resources/read of a data-bearing URI-template instantiation consume the Pro daily quota, except the metadata helper describe_tool.
• initialize, tools/list, prompts/list, prompts/get, resources/list, resources/templates/list, logging/setLevel, notifications/initialized, ping, and describe_tool do not count against the daily cap. resources/read of a public resource (a metadata-only freshness/health probe, e.g. worldmonitor://seed-meta/freshness) is likewise exempt — it carries no billable data.
• Hitting the cap returns JSON-RPC error -32029 plus HTTP 429 with a Retry-After header pointing at the next UTC midnight.
• The cap is hard: concurrent tools/call or resources/read requests near the boundary use an atomic Redis reservation, so exactly the call that crosses 50 rejects.

​

Connected MCP clients

• Manage connected clients in Settings → Connected MCP clients.
• See the live clientName (e.g. “Claude”, “Cursor”), lastUsedAt, and createdAt per token.
• A revoke takes effect on the next MCP request (no positive cache).
• Up to 5 active tokens per user. The 6th authorization silently revokes the least-recently-used existing one.

​

Plans & limits

​

Other rate limits

• OAuth authorize: 10 requests / minute / IP
• OAuth token: 10 requests / minute / IP
• Dynamic registration: 5 registrations / minute / IP

​

Client setup

​

Claude Desktop

{
  "mcpServers": {
    "worldmonitor": {
      "url": "https://worldmonitor.app/mcp"
    }
  }
}

​

Claude web (claude.ai)

• Name: WorldMonitor
• URL: https://worldmonitor.app/mcp

​

Cursor

{
  "mcpServers": {
    "worldmonitor": {
      "url": "https://worldmonitor.app/mcp"
    }
  }
}

​

MCP Inspector (debugging)

npx @modelcontextprotocol/inspector https://worldmonitor.app/mcp

​

Tool catalog

​

Markets & economy

​

Energy

​

Geopolitical & security

​

Movement & infrastructure

​

Environment & science

​

Health

​

Humanitarian & displacement

​

AI intelligence (live LLM)

​

API coverage

1. Copy the exact method and path from the OpenAPI page, for example GET /api/research/v1/list-tech-events.
2. Search this table. If the route appears, call the listed MCP tool.
3. If it does not appear, the REST route is not exposed through MCP as an API-equivalent path. A cache-only MCP tool may still return related domain data, but it is not claiming that REST route.
4. For code-level verification, search _apiPaths in api/mcp/registry/cache-tools.ts and api/mcp/registry/rpc-tools.ts; the parity test explains intentional REST-only exclusions.

• Cache-backed bootstrap aggregates — read Redis keys seeded directly by Railway crons (e.g. get_aviation_status, get_cyber_threats, get_country_macro, the three EU Eurostat tools).
• Static in-memory registries — filter a constant bundled with the MCP server’s edge binary, no upstream call at all (e.g. get_commodity_geo).
• Live tools without a public OpenAPI row — runtime proxies an HTTP call whose method drifts from the public spec, where a sibling tool already covers the spec-declared method (e.g. generate_forecasts POSTs /api/forecast/v1/get-forecasts while get_forecast_predictions owns the GET).

• Mutating endpoints — writes, queues, webhooks, cache refreshes, or persistent side effects. Example: GET /api/aviation/v1/list-airport-delays is intentionally REST-only because the GET handler refreshes/persists airport-delay cache state; get_aviation_status exposes the already-seeded cache-backed snapshot instead.
• Fetch-on-miss endpoints — may call paid or rate-limited upstreams when cache is cold. Examples: GET /api/conflict/v1/list-acled-events, GET /api/infrastructure/v1/list-service-statuses, and GET /api/supply-chain/v1/get-critical-minerals.
• High-cardinality lookups — arbitrary identifiers are not enumerable or cache-bundle friendly. Example: GET /api/aviation/v1/get-flight-status.
• LLM-cost endpoints — direct LLM passthroughs or fetch-on-miss paths with per-call model cost stay out of open MCP exposure unless wrapped by a purpose-built tool.
• Deferred future tools — pure reads whose cache keys are not yet exposed by an MCP bundle. Example: GET /api/cyber/v1/list-cyber-threats is slated for a future expanded-domain tool rather than claimed by today’s cache-backed get_cyber_threats.
• Manual mapping — parameterized cache keys or inline Redis/Convex handlers need human triage. Examples: GET /api/research/v1/list-arxiv-papers, GET /api/research/v1/list-trending-repos, and GET /api/research/v1/list-hackernews-items; get_research_signals declares only GET /api/research/v1/list-tech-events.

​

Prompts and resources

​

Prompts

​

Resources

​

MCP Apps (interactive UI)

• initialize declares support in the handshake. The response’s capabilities.extensions names the extension: {"io.modelcontextprotocol/ui": {}}. This is the negotiation signal a host (or agent-readiness scanner) reads to classify the endpoint as an MCP-App surface — the tools/list and resources/list entries below are the content it then renders.
• tools/list advertises the linkage on the tool. get_country_risk carries _meta.ui.resourceUri (and the deprecated flat ui/resourceUri alias) pointing at its UI resource.
• resources/list surfaces the UI resource itself, alongside the concrete data resource (the parameterised data templates live in resources/templates/list):

​

JSON-RPC example

WM_KEY="wm_0123456789abcdef0123456789abcdef01234567"

# 1. List tools
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 2. Call a cache tool
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":2,
    "method":"tools/call",
    "params":{"name":"get_country_risk","arguments":{"country_code":"IR"}}
  }'

​

Response shape

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{...json payload...}" }
    ],
    "isError": false
  }
}

​

Data freshness

​

Errors

• 401 + -32001 carries a WWW-Authenticate header with resource_metadata pointing at /.well-known/oauth-protected-resource. RFC 9728-aware clients re-run the OAuth flow on this header automatically.
• 429 + -32029 is the Pro daily cap (Retry-After: <seconds-until-UTC-midnight>). The per-minute rate limit returns -32029 inside HTTP 200, not 429 — see the catalog for the distinction.
• Soft envelopes return HTTP 200 with no JSON-RPC error field — clients that inspect only the JSON-RPC layer will silently treat them as successes. Always parse result.content[0].text and check for a leading-underscore discriminator key (_budget_exceeded, _jmespath_error) before consuming the payload as data.

​

Related

• MCP Quickstart — five-minute zero-to-first-call walkthrough
• JMESPath guide — projection grammar + 12 worked examples
• MCP Tools Reference — per-tool parameters and curl examples
• MCP Error Catalog — every JSON-RPC code, HTTP status, and soft envelope the server emits
• Authentication overview — browser vs bearer vs OAuth
• API Reference — the same data via REST
• Pro features