MCP Server

​

Endpoints

​

Protocol negotiation

• By default, initialize negotiates 2025-03-26.
• When MCP_PROTOCOL_FLOOR_2025_06_18=on is enabled for the deploy, the server supports both 2025-03-26 and 2025-06-18.
• With that flag on, clients requesting 2025-06-18 receive 2025-06-18; clients pinned to 2025-03-26 continue receiving 2025-03-26.
• With that flag off, a client that 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 starts with an empty priming event that has an event id, followed by the JSON-RPC response event. If the client disconnects after an event, it can resume by sending GET /mcp with Accept: text/event-stream, the same Mcp-Session-Id, and Last-Event-ID.

​

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 consume the Pro daily quota, except the metadata helper describe_tool.
• initialize, tools/list, prompts/list, prompts/get, resources/list, logging/setLevel, notifications/initialized, ping, and describe_tool do not count against the daily cap.
• 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

• 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).

​

Prompts and resources

​

Prompts

​

Resources

​

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