WorldMonitor MCP server: connect Claude, Cursor, and agents

WorldMonitor exposes its intelligence stack as a Model Context Protocol server so any MCP-compatible client (Claude Desktop, Claude web, Cursor, MCP Inspector, custom agents) can pull live data directly into a model’s context. Its tools cover these domains: markets, commodities and macro; energy; conflicts, country risk, sanctions, cyber threats and chokepoints; maritime, aviation and supply chains; climate and natural disasters; health signals; displacement and humanitarian crises; AI briefs, forecasts and intel history; tariffs and trade policy. To compare data coverage and access options, see MCP servers for geopolitical data.

New here? The MCP Quickstart is the shortest path: paste one address into Claude, ChatGPT, Codex or Cursor and sign in, no API key needed. Come back to this page for auth modes, plans, OAuth setup, and the full tool catalog.

Looking for tools that operate the dashboard already open in a Chrome tab? See WebMCP. WebMCP is page-local, experimental, and human-in-the-loop; it does not replace this persistent hosted MCP server or its data tools.

Pro and API tiers can both connect via OAuth — no API key required. Pro subscribers click “Sign in with WorldMonitor Pro” on the consent page; API Starter / Business / Enterprise users may sign in the same way OR paste a wm_… key. A confirmed free account also completes the OAuth flow: its token is restricted to free-account tools and metered by the free allowance. A provider-confirmed lapse follows that same free-account path because the shared gate treats ended coverage as a confirmed free state. Retryable verification failures still return 503; an expired or disabled paid row without that provider-confirmed lapse, or another genuinely insufficient entitlement, is refused with the Pro-required page.OAuth is not needed for get_sources: it is the sole credential-free, daily-quota-free data tool. Anonymous calls use a separate fail-closed limit of 10 requests/minute/IP. Other data tools require a user-bound credential. Tools marked free-account (direct cache reads) can use the small confirmed-free allowance; tools marked subscription (everything with server-side execute logic — live fetches, plus a few local-compute tools) require Pro.

All paid tiers share the same MCP server and tool inventory, but they are metered two different ways. Pro and Pro Business have no REST allowance, so their MCP requests use a dedicated daily counter of 50 and 250 units per UTC day. A standalone data call costs one unit. A country brief, news dashboard, curated market panel, prediction panel, or Conflict Events panel costs one unit including its authorized internal reads. Curated market, prediction and Conflict Events filters and repeated opens reuse their respective admissions within five minutes. An explicit refresh with a new UUID costs one new unit; the same UUID retries that allocation. An authorized Conflict Events receipt read also queries current usage without another allocation, and unknown usage omits the numeric notice. See Paid embedded-panel requests. API Starter and API Business carry no separate MCP allowance. Their MCP calls draw on the same daily budget as their REST requests (1,000 and 10,000/day), charged at a per-tool weight of 1 for a cached read, 2 for a live downstream fetch, 3 for get_country_brief, and 5 for get_airspace (up to four downstream requests across the dateline). Both the OAuth and wm_… doors resolve the same budget, so the credential you use does not change the cap. Enterprise carries a fair-use ceiling of 25,000 units/day on both doors, and legacy operator keys explicitly allowlisted by the deployment reserve on their own per-key counter with a ceiling of 10,000 units/day. Every authenticated context also passes a per-minute burst limiter, set by plan: 60 requests/minute on Pro, Pro Business and API Starter, 300 on API Business, 1,000 on Enterprise. get_sources, describe_tool, and get_mcp_allowance are exempt from the daily quota. The protected allowance tool uses the shared 192/minute protocol bucket. Full weight table: MCP calls against an API plan. Pro subscribers can connect Claude Desktop / Cursor / claude.ai without ever pasting an API key — see Pro sign-in flow below. API Starter+ holders may continue to paste a wm_… key on the consent page (the original flow), or use the same OAuth path as Pro.

Endpoints

Endpoint	Purpose
`https://worldmonitor.app/mcp`	JSON-RPC server (Streamable HTTP transport; JSON responses by default, SSE responses when clients advertise `text/event-stream`; `initialize` negotiates protocol `2025-11-25` by default, `2025-06-18` or `2025-03-26` for older clients)
`https://worldmonitor.app/oauth/register`	Dynamic Client Registration (RFC 7591). Clients on the trusted list can skip it and use their Client ID Metadata Document URL as `client_id`
`https://worldmonitor.app/oauth/authorize`	OAuth 2.1 authorization endpoint (PKCE required)
`https://worldmonitor.app/oauth/token`	Token endpoint (authorization_code + refresh_token)
`https://worldmonitor.app/.well-known/oauth-authorization-server`	AS metadata (RFC 8414; the endpoints it advertises mirror the request host, so the `api.` subdomain works too)
`https://www.worldmonitor.app/docs/mcp`	Separate anonymous documentation MCP server (docs search + read-only docs filesystem) — card at `/.well-known/mcp/docs-server-card.json`; see Agent Discovery
`https://worldmonitor.app/.well-known/oauth-protected-resource/mcp`	Resource server metadata for the MCP endpoint (RFC 9728), naming `https://worldmonitor.app/mcp`. This is where the `401` challenge points
`https://worldmonitor.app/.well-known/oauth-protected-resource`	Resource server metadata for the origin (RFC 9728), kept for clients that discovered it before the path-scoped document existed

Server identifier: worldmonitor v1.32.0. Registry listings: the server is published in the official MCP registry as app.worldmonitor/mcp — a domain-verified namespace, so clients that resolve servers through the registry get the same endpoint and metadata as the server card above — and listed on Smithery and mcp.so.

Protocol negotiation

WorldMonitor’s static server card at /.well-known/mcp/server-card.json advertises protocol version 2025-11-25, and the live initialize handshake negotiates it by default — so the advertised floor and the negotiated version stay in lock-step:

By default, initialize supports 2025-03-26, 2025-06-18, and 2025-11-25.
Clients requesting one of those receive it unchanged; a client requesting any other version receives 2025-11-25.
On 2025-11-25, a tools/call whose arguments fail validation returns an isError tool result the model can read and correct, instead of the -32602 error earlier versions receive (see the error catalog).
Setting MCP_PROTOCOL_2025_11_25=off drops 2025-11-25 again, and MCP_PROTOCOL_FLOOR_2025_06_18=off pins the server back to the legacy 2025-03-26-only floor.
The handshake-free 2026-07-28 revision is off by default. While it is off, its clients fall back to initialize as above.
With MCP_PROTOCOL_2026_07_28=on, a request whose params._meta carries io.modelcontextprotocol/protocolVersion is served per request on the 2026-07-28 rules: server/discover, the required MCP-Protocol-Version, Mcp-Method and Mcp-Name headers, resultType and cache hints on results, and a minimal subscriptions/listen. On /mcp, an anonymous 2026-07-28 request gets the sign-in challenge except the free get_sources call and ui:// app reads; the machine-discovery aliases stay anonymous. Requests without that envelope keep the behavior above. The error catalog lists the error codes these requests can receive.

Tool outputSchema metadata is emitted on tools/list regardless of the negotiated protocol version. Older 2025-03-26 clients should ignore unknown fields, while newer clients can use the schema immediately. Every successful tools/call also returns the payload as structuredContent, which strict clients require once a schema is advertised; the tools reference describes how projections and soft envelopes are represented.

Streamable HTTP responses

WorldMonitor supports the Streamable HTTP POST flow with either JSON or SSE 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 GET /mcp with Accept: text/event-stream but no 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.
A plain browser-style GET /mcp — no SSE Accept, no Last-Event-ID — returns 200 with a human/agent-readable markdown server guide (the same document as /mcp-server.md), so pasting the endpoint URL into a browser or curl explains the server instead of erroring.

The replay buffer is in-memory and bounded per edge instance — 128 KB per response, 256 KB per session, 4 MB total, plus caps on concurrent sessions and on replayable responses per session. Treat Last-Event-ID resume as loss-tolerant transport recovery, not durable message storage — a missed cursor returns -32004 at HTTP 404; re-issue the POST.

Authentication

An MCP client signs in when it connects. The transport answers an unauthenticated initialize with 401, JSON-RPC -32001, and a WWW-Authenticate challenge naming the protected-resource document for that path, with the request id echoed. initialize is the handshake every interactive client opens with, and hosted connectors (Cursor Agents, Grok, ChatGPT) decide from its answer whether a server needs sign-in: answered with 200, they record “nothing to authenticate” and have no authorization server to send you to when a paid tool later refuses the call. A free account is enough to sign in. A full anonymous handshake remains available to agent-readiness scanners on the machine-discovery aliases /.well-known/mcp and /.well-known/mcp.json; point MCP clients at /mcp. Stateless catalog reads stay public. tools/list, prompts/list, prompts/get, skills/list, skills/get, resources/list, resources/templates/list, ping, logging/setLevel, and the notifications/initialized notification are servable without credentials, which is how the keyless worldmonitor CLI and the SDKs list tools without ever sending initialize. Any agent (or agent-readiness scanner) can reach https://worldmonitor.app/mcp, read the server identity, and enumerate the full tool, prompt, and resource catalogs before authenticating — the same metadata already published in the static server card. These methods return only public catalog metadata (names, descriptions, URIs / URI templates, static workflow-template prose — no data, no quota); every capability advertised by the anonymous initialize is anonymously exercisable, so a strict MCP client (Claude Desktop, mcp-remote, the reference SDKs) completes its full post-connect enumeration without stalling on an auth wall. resources/read of a public resource (a concrete, metadata-only freshness/health probe surfaced by resources/list, such as worldmonitor://seed-meta/freshness) is also public and quota-free — an anonymous agent can read it cleanly. Anonymous discovery is rate-limited to 60 requests/minute per client IP. get_sources is the sole credential-free, daily-quota-free data tool; its anonymous path has a separate fail-closed ceiling of 10 calls/minute/IP. Other data-bearing calls require credentials. Every tools/list and describe_tool entry carries _meta["worldmonitor/access"]: "free" means anonymous and quota-free, "free-account" means available to a signed-in free account (cache-backed data calls spend its allowance; describe_tool and get_mcp_allowance do not), and "subscription" means Pro-only. Resource templates carry the same marker as their backing tool. A credential presented on a discovery method is still validated (a bad key returns 401, never a silent anonymous downgrade). The MCP handler accepts two auth modes, in priority order:

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

OAuth bearer requests re-check the resolved MCP token, user binding, and entitlement before dispatch. A provider-confirmed lapse removes paid capability but retains the OAuth identity on the restricted, allowance-metered free-account path; an expired or disabled paid entitlement without that confirmed lapse, or another genuinely insufficient non-free state, is denied on the next request. Dashboard-issued X-WorldMonitor-Key: wm_… requests validate the key owner and active entitlement, then use the same per-user minute bucket and the same plan-resolved budget as the OAuth path. Legacy deployment-allowlisted operator keys use a per-key minute bucket and skip the daily reservation.

Redirect URI allowlist

Dynamic Client Registration is not open to arbitrary redirects. A redirect_uri must be http://localhost:<port>, http://127.0.0.1:<port>, or http://[::1]:<port> (any port, any path), or exactly match a hosted MCP client callback below, as the client sends it. Links point to the vendor’s own documentation where one exists.

Client	Callback
Claude	`https://claude.ai/api/mcp/auth_callback`, `https://claude.com/api/mcp/auth_callback`
Cursor Agents, Cursor Bot, Cursor web, Grok Bot	`https://www.cursor.com/agents/mcp/oauth/callback`, `https://www.cursor.com/bot/mcp/oauth/callback`, `cursor://anysphere.cursor-mcp/oauth/callback` (Cursor MCP docs, Cursor client metadata)
ChatGPT	`https://chatgpt.com/connector_platform_oauth_redirect` (OpenAI auth docs)
Grok	`https://grok.com/connectors-oauth-exchange-code/`, `https://console.x.ai/connectors-oauth-exchange-code/` (Grok client metadata)
VS Code for the Web	`https://vscode.dev/redirect`, `https://insiders.vscode.dev/redirect`
Perplexity	`https://www.perplexity.ai/rest/connections/oauth_callback`, `https://enterprise.perplexity.ai/rest/connections/oauth_callback` (Perplexity help)
Mistral Le Chat	`https://callback.mistral.ai/v1/integrations_auth/oauth2_callback`
Devin	`https://api.devin.ai/mcp/oauth/callback` (Devin MCP docs)
Google Antigravity	`https://antigravity.google/oauth-callback` (Antigravity MCP docs)
Vercel Connect	`https://connect.vercel.com/callback` (Vercel Connect provider docs)
Glama	`https://glama.ai/api/app/mcp/oauth/callback` (connectors and test profiles), `https://glama.ai/mcp/inspector/oauth/callback` (Glama MCP Inspector)
Make.com	`https://www.make.com/oauth/cb/mcp` (Make MCP client)
Microsoft 365 Copilot	`https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect` (Build MCP plugins)
Meta Muse	`https://agent.meta.ai/api/hatch/oauth/callback`
Notion	`https://www.notion.so/workflows/mcp/oauth/callback`, `https://app.notion.com/workflows/mcp/oauth/callback` (client metadata)
Linear	`https://linear.app/connect/mcp/callback` (client metadata)
Lovable	`https://api.lovable.dev/workspaces/connectors/mcp/oauth/callback` (client metadata)
Factory	`https://app.factory.ai/mcp/oauth/callback`, `https://app.eu.factory.ai/mcp/oauth/callback` (client metadata)
Conductor	`https://api.conductor.build/oauth/callback` (client metadata)
Skydive	`https://www.skydive.com/api/v1/external-oauth/callback` (client metadata)
MCPJam	`https://app.mcpjam.com/oauth/callback`, `https://score.mcpjam.com/oauth/callback` (client metadata)

Claude Code, Cursor desktop, VS Code desktop, Codex, Gemini CLI, goose, Zed, and MCP Inspector use the loopback form. Notion, Linear, Lovable, Factory, Conductor, Skydive, and MCPJam prefer Client ID Metadata Documents and now connect that way (see below); their callbacks stay listed for clients that still register. A registration may list up to 8 redirect_uris, and one unlisted entry rejects the whole request with 400 invalid_redirect_uri. Clients with per-user or per-tenant callbacks, such as Gemini custom apps and Microsoft Copilot Studio, cannot be exact-matched and are not supported.

Client ID Metadata Documents

A client can skip registration and send the HTTPS URL of its published Client ID Metadata Document as client_id. The AS metadata advertises client_id_metadata_document_supported: true next to registration_endpoint, and a client picks one method at discovery. Existing registrations and their refresh tokens keep working; a client that switches to CIMD signs in again as a new connection. WorldMonitor accepts only the document URLs below, matched exactly, and fetches no other URL. A request is accepted when:

the document’s client_id equals the URL it was fetched from;
the redirect_uri is one of the document’s redirect_uris, exactly, except that an http://localhost, http://127.0.0.1, or http://[::1] callback may use any port (RFC 8252 §7.3);
the redirect_uri is https: or http loopback, with no credentials or fragment;
the document offers token_endpoint_auth_method none (public client with PKCE S256), has no client_secret, and includes the authorization_code grant when it lists grants.

The document is fetched over HTTPS with redirects refused, a 3-second timeout, and a 16 KB cap. A valid document is cached for its Cache-Control lifetime, at most one hour (private and no-store are not cached), so a vendor’s change reaches WorldMonitor within that time. A failed fetch is never cached. A missing document (404 or 410) is an unknown client; any other failure, such as a timeout, a 5xx or 403, an HTML page, or a body that is not valid JSON, is retryable, and the token endpoint keeps the authorization code or refresh token for the retry. For an exact listed URL, a retryable failure falls back to a vetted copy of the document captured when it was listed; chatgpt.com answers every fetch from WorldMonitor’s servers with a 403 page, so ChatGPT and Codex connect this way. The copy is never cached, so the live document is tried on every request, and a missing or invalid live document still rejects the client. A per-connector document such as Vercel Connect’s has no copy. The consent page shows the client name from the document, the host that published it, and the redirect host, and warns when the authorization goes to a localhost callback.

Client	`client_id` (metadata document)
Claude	`https://claude.ai/oauth/mcp-oauth-client-metadata`
Claude Code	`https://claude.ai/oauth/claude-code-client-metadata`
ChatGPT	`https://chatgpt.com/oauth/client.json` (OpenAI auth docs)
Codex	`https://chatgpt.com/oauth/codex/client.json`
Cursor	`https://cursor.com/oauth/mcp-client.json`
Grok	`https://grok.com/oauth/mcp-client.json`
VS Code	`https://vscode.dev/oauth/client-metadata.json`
goose	`https://goose-docs.ai/oauth/client-metadata.json`
Notion	`https://www.notion.so/oauth/mcp-client-metadata.json`, `https://app.notion.com/oauth/mcp-client-metadata.json`
Linear	`https://linear.app/.well-known/oauth-client-metadata/mcp.json`
Lovable	`https://api.lovable.dev/.well-known/oauth-client`
Factory	`https://api.factory.ai/mcp/oauth-client`
Conductor	`https://api.conductor.build/oauth/client-metadata.json`
Skydive	`https://www.skydive.com/api/v1/external-oauth/client-metadata`
MCPJam	`https://www.mcpjam.com/.well-known/oauth/client-metadata.json`
Vercel Connect	`https://connect.vercel.com/connectors/<connector id>`, one document per connector, with the callback pinned to `https://connect.vercel.com/callback` (Vercel Connect provider docs)

ChatGPT’s document prefers private_key_jwt but also lists none; WorldMonitor advertises only none, so ChatGPT uses PKCE without a client assertion. Make.com’s published client URL redirects instead of serving a document, so it is not on the list. A client whose document is not listed gets an “Unknown Client” error; ask for it to be added. The authorization response carries iss (RFC 9207), set to the issuer of the host where the flow started. ChatGPT requires it to use its stable callback.

Token lifetimes

Artifact	TTL
Authorization code	10 min
Access token	1 hour
Refresh token	30 days (sliding: each refresh issues a new token with the full window)
Registered client record	90 days (sliding)
Cached client metadata document	Its `Cache-Control` lifetime, at most 1 hour

Pro subscribers (and API Starter+ users who’d rather not paste a key) can authorize MCP clients via their existing WorldMonitor account — no API key needed.

Add the server URL in your MCP client. The canonical entrypoint is:
https://worldmonitor.app/mcp
This is the only product MCP transport endpoint. Listed production aliases (www, api, and the dashboard variants) are not additional servers. Ordinary GET/HEAD /mcp and /api/mcp on those hosts redirect (308) to https://worldmonitor.app/mcp; ordinary GET/HEAD /.well-known/mcp and /.well-known/mcp.json redirect (308) to https://worldmonitor.app/.well-known/mcp and https://worldmonitor.app/.well-known/mcp.json. Query is not forwarded. A transport POST/SSE/replay receives HTTP 410 with JSON-RPC -32000 telling the client to use https://worldmonitor.app/mcp.
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.
Done. No wm_… key is created or stored on your machine. The client receives a standard OAuth 2.1 access token (1 h TTL, refresh token valid for 30 days after the last refresh).

If the sign-in step reports that your subscription could not be verified — a 503 page, or 503 TIER_VERIFICATION_UNAVAILABLE from the grant endpoints — that is transient and says nothing about your subscription. Wait the advertised Retry-After and start the connection again from your client; the authorization session is single-use, so restart it rather than reloading the page. A confirmed account with an expired or disabled paid entitlement without a provider-confirmed lapse gets 403 INSUFFICIENT_TIER instead. A confirmed free account, including a provider-confirmed lapse reclassified by the shared gate, completes the flow with a restricted, allowance-metered token. See Error handling.

If you’d rather paste an API key (Starter+ / scripted clients), expand “Use API key instead” on the consent page and submit your wm_ user key or operator-issued enterprise key — that path is unchanged.

Daily limit (Pro tier)

50 quota-consuming calls per UTC day on Pro and 250 on Pro Business, reset at 00:00 UTC. Both plans meter on a dedicated MCP counter and every call costs one unit, whatever the tool does.
Data-bearing tools/call and resources/read of a data-bearing URI-template instantiation consume the Pro daily quota, except get_sources and the metadata helper describe_tool.
initialize, tools/list, prompts/list, prompts/get, skills/list, skills/get, resources/list, resources/templates/list, logging/setLevel, notifications/initialized, ping, describe_tool, get_mcp_allowance, and get_sources 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) and the authenticated account status resource worldmonitor://account/mcp-allowance are likewise exempt.
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 the limit rejects.

Need higher-volume scripted access? API Starter and API Business add a wm_… key option plus a much larger daily budget (1,000 and 10,000 units/day) that their MCP calls and REST requests share, at 60 and 300 requests/minute/user. A cached MCP read costs 1 unit and a live downstream fetch costs 2, get_country_brief costs 3, and get_airspace costs 5, so batch workloads still go further over REST. Enterprise lifts the daily cap entirely. See Plans & limits.

Connected MCP clients

Each authorization mints a separate row, so revoking Claude Desktop does not affect Cursor.

Sign in to the dashboard. Select Settings → MCP Clients to manage connected 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. Authorizing beyond the cap silently revokes the oldest-created existing token (creation order, not recency of use; enforcement is eventually consistent under concurrent authorizations).

Plans & limits

Plan	MCP access	Auth modes	MCP daily reservation	Per-minute burst	Notes
Free	Anonymous `get_sources`; `free-account` (cache-read) tools with a user-bound credential	OAuth (confirmed free accounts complete the flow) or an existing user-bound credential	5 calls and 3 idle-gap request windows / UTC day	Anonymous ceilings only: 10/minute/IP on `get_sources`, 60/minute/IP on discovery	The token is restricted to `free-account` tools; `subscription` tools return the upgrade denial. Anonymous `get_sources` fails closed above 10/minute/IP.
Pro	✅ Yes	OAuth only	50 quota-consuming calls / UTC day, one unit per call	60 / minute / user	Bounce-via-apex Clerk sign-in. No `wm_…` key needed or stored.
Pro Business	✅ Yes	OAuth only	250 quota-consuming calls / UTC day, one unit per call	60 / minute / user	Same dedicated MCP counter as Pro, five times the allowance. No REST budget, so no `wm_…` key.
API Starter	✅ Yes	OAuth or `wm_…` key	1,000 units / UTC day, shared with REST and charged at the per-tool weight	60 / minute / user	Standard developer-tier REST/API access.
API Business	✅ Yes	OAuth or `wm_…` key	10,000 units / UTC day, shared with REST and charged at the per-tool weight	300 / minute / user	Higher REST/API throughput.
Enterprise	✅ Yes	OAuth or `wm_…` key	25,000/day fair-use ceiling on both doors	1,000 / minute	Custom SLA available.

Per-minute throttling protects against burst storms across paid tiers. Ordinary data calls use the account’s plan burst from the table above. Recognized data-free protocol methods, including initialize, notifications/initialized, ping, catalog methods and public resource reads, use a separate 192 requests/minute/user bucket. Both OAuth and dashboard keys share that bucket across sessions. It supports 64 panel-read connections with three setup calls each. A validated paid MCP panel receipt has separate 64 uncached reads/minute/panel and 64 cached replays/minute/panel buckets, one daily allocation per opening and at most 64 uncached executions per admission. Unsupported methods, account status reads and data-bearing resource reads retain the ordinary account burst. Legacy operator keys and anonymous discovery retain their combined 60/minute limits. Anonymous get_sources retains its fail-closed 10/minute/IP ceiling. The daily-quota cap applies to subscription data reservations. See Daily limit (Pro tier) and the Error Catalog. The OAuth and dashboard-key burst is per-USER, so a user with 3 Claude installations or multiple wm_… keys shares one pool at their plan’s rate. Legacy operator-key limiting is per-KEY. Hitting the MCP daily quota returns JSON-RPC error -32029 plus HTTP 429 with a Retry-After header pointing at the next UTC midnight. Hitting the per-minute limit returns the same error code with a short Retry-After. WorldMonitor also surfaces current MCP plan-limit notices in Settings and sends a bounded-cadence email when a paid user approaches or exceeds their plan allowance. Notices are informational and action-oriented: they offer retry/reset guidance, checkout when the next tier is self-serve, or support contact when it is not. They do not automatically upgrade the account or create overage charges.

Other rate limits

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

Exceeding any limit returns HTTP 429 with a Retry-After header.

Client setup

Step-by-step setup with screenshots for Claude, ChatGPT, Codex, Claude Code and Cursor is in the MCP Quickstart.

Claude (desktop app, claude.ai, mobile)

Add via Customize → Connectors → + Add → Add custom connector:

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

Keep the detected sign-in settings and click Add, then sign in. Connectors belong to your Claude account, so Claude web, Claude Desktop and the mobile apps use the same one. On Team and Enterprise, an owner adds it first under Organization settings → Connectors. Claude Desktop’s claude_desktop_config.json launches local (stdio) servers only, so a remote url entry there is not a supported way to connect; use the connector, or the mcp-remote bridge below.

The `mcp-remote` bridge (stdio-only clients)

Stdio-only MCP clients connect through the mcp-remote bridge:

{
  "mcpServers": {
    "worldmonitor": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://worldmonitor.app/mcp", "--header", "X-WorldMonitor-Key:wm_YOUR_KEY"]
    }
  }
}

With an API key, pass it as a header. A request that carries a valid key is not challenged; an invalid, expired or revoked key gets 401. Use the single-argument form X-WorldMonitor-Key:wm_… with no space after the colon — it sidesteps client/npx argument-escaping bugs with spaces inside args (documented by mcp-remote for Cursor and Claude Desktop on Windows).
Prefer OAuth? Omit --header. The server answers mcp-remote’s opening initialize with the 401 challenge, which opens its browser consent flow at connect time (dynamic client registration works on both worldmonitor.app and www.worldmonitor.app). A free account can complete it; subscription tools then depend on your plan.

Codex

codex mcp add worldmonitor --url https://worldmonitor.app/mcp
codex mcp login worldmonitor

The CLI, the IDE extension and the Codex app read the same ~/.codex/config.toml.

Claude Code

claude mcp add --transport http worldmonitor https://worldmonitor.app/mcp

Then run /mcp inside Claude Code and choose Authenticate.

Cursor

~/.cursor/mcp.json:

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

Cursor Agents, Cursor web, and Grok Bot take the same URL and sign in through Cursor’s hosted callback.

Other hosted clients

ChatGPT, Grok, Perplexity, Mistral Le Chat, Devin, Google Antigravity, and VS Code: add https://worldmonitor.app/mcp as a custom connector or remote MCP server. Registration accepts the callbacks listed in Redirect URI allowlist.

MCP Inspector (debugging)

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

Tool catalog

The server exposes a registry of tools. Most are cache-reads over pre-seeded Redis keys (sub-second). The slower, non-cache paths are the five live LLM/external-API tools (get_country_brief, analyze_situation, search_flights, search_flight_prices_by_date, classify_event) plus the live geo RPC tools (get_airspace, get_maritime_activity), the bounded canonical procurement proxy (get_procurement_opportunities), the corporate-intelligence proxy (get_company_intelligence), the canonical China decision-signal RPC (get_china_decision_signals), and the three durable-history RPCs (search_intel_history, get_intel_timeline, get_similar_events). get_world_brief reads the dashboard’s precomputed, citation-grounded news:insights:v1 snapshot and does not make a request-time LLM call. The on-demand NLP utilities (classify_event, extract_entities, get_news_clusters, get_keyword_spikes, verify_claim) accept bounded caller text or compute over live seeded data; all but classify_event are fully deterministic. One (describe_tool, added v1.5.0) returns the complete definition of any other tool by name — the same entry tools/list ships, for re-reading one tool without re-listing the catalog; exempt from the Pro daily quota.

For per-tool parameters, freshness budgets, timeouts, and concrete curl examples, see the MCP Tools Reference. For payload projection — every tool accepts an optional jmespath argument that typically cuts response size by 80-95% — see the JMESPath guide.

Markets & economy

Tool	Description
`get_market_data`	Equity quotes, commodity prices (incl. gold GC=F), crypto, FX, sector performance and valuation coverage, ETF flows, Gulf markets. Sector coverage separates write age from completeness and exposes bounded unavailable/last-good/direct-proxy diagnostics.
`get_economic_data`	Fed Funds, economic calendar, fuel prices, ECB FX, EU yield curve, earnings, COT, energy storage, BIS DSR + property prices.
`get_country_macro`	IMF WEO bundle per country: inflation, current account, GDP/capita, unemployment, savings-investment gap (~210 countries).
`get_eu_housing_cycle`	Eurostat annual house price index (prc_hpi_a), 10-yr sparkline per EU member + EA20/EU27.
`get_eu_quarterly_gov_debt`	Eurostat quarterly gross government debt (%GDP), 8-quarter sparkline.
`get_eu_industrial_production`	Eurostat monthly industrial production index, 12-month sparkline.
`get_prediction_markets`	Prediction markets with current probabilities: geopolitical/elections, tagged tech (AI/crypto/science), finance/economics or untagged fallback.
`get_supply_chain_data`	Dry bulk shipping stress index, customs flows, COMTRADE bilateral trade.
`get_price_and_debt_indicators`	Price and debt indicators: Big Mac index, FAO Food Price Index, and per-country national debt levels.
`get_wto_trade_flows`	WTO merchandise trade flows for one reporting country versus the World (reporter 3-digit UN M49, window 1–30 years). Distinguishes `not_covered` from faults.
`get_tariff_averages`	Average tariff a country applies by year: schedule rates through 2023, no Section 301/232 duties. The WTO MFN average, or with a partner and/or WITS product group the effectively applied simple and import-weighted averages (UNCTAD TRAINS).
`get_bilateral_tariff`	Tariff on one HS6 product between two countries: schedule rate through 2023, no Section 301/232 duties. Applied, MFN and preferential rates for one year (UNCTAD TRAINS via WITS).
`get_us_import_duty`	Current US duty on one HTS product from one country: live HTS base rates plus the Section 301 and 232 duties in force, each with a status.
`get_chokepoint_status`	Live maritime chokepoint status: per-chokepoint vessel transit counts (10-min cadence), rolling transit summaries, per-port activity, plus static reference data and flow aggregates. Covers Suez, Hormuz, Malacca, Bab-el-Mandeb, Panama, etc.
`get_consumer_prices`	Per-country consumer-prices intelligence: 30-day overview, category-level inflation, retailer spread (essentials basket), top movers, and source freshness. Requires `country_code` (currently only `ae` is seeded).
`get_procurement_opportunities`	Pro-gated canonical global procurement search; compact output defaults to 10 records and caps at 25. Keyword relevance is never bidding eligibility.
`get_company_intelligence`	Verified per-company SEC intelligence: enrichment, timestamped signals, filing search, and market-wide material 8-K events.
`get_commodity_geo`	71 major mining sites worldwide (gold, silver, copper, lithium, cobalt, rare earths, nickel, platinum, palladium, iron ore, uranium).
`get_mineral_production`	Who mines / refines a commodity (USGS MCS shares + HHI; BGS fill).
`get_food_stocks`	USDA PSD cereal stocks-to-use per country (or `WORLD`) by marketing year, optional per-commodity filter.
`get_demographics_capability`	Country age structure, education capacity, and industrial-workforce observations (UN WPP, UNESCO UIS, ILOSTAT).
`get_five_factor_scorecard`	Frozen v1 food, energy, demographics, technology, and defense scorecard for one country, official bloc preset, or validated custom bloc. Preserves input availability and source provenance.
`list_five_factor_scorecards`	Compact country-by-country five-factor pillar scores, bands, coverage, and insufficient-data reasons. Read `hasScore` before numeric scores; false means zero is an insufficient-data placeholder. Use the single-scorecard tool for the full evidence ledger.

Energy

Tool	Description
`get_energy_intelligence`	Energy supply, prices, storage, disruptions, and policy: EIA petroleum stocks, electricity prices (Ember), gas storage (GIE), fuel shortages, fossil & renewable shares, active energy disruptions, government crisis policies.

Geopolitical & security

Tool	Description
`get_conflict_events`	Active UCDP/Iran conflicts, unrest w/ geo-coords, country risk scores.
`get_country_risk`	CII score 0-100, component breakdown, travel advisory and OFAC exposure. Paid reads share the country’s panel allocation and replay accepted originals. No LLM.
`get_military_posture`	Theater posture + military risk scores.
`get_cyber_threats`	URLhaus/Feodotracker malware IOCs, CISA KEV catalog, active C2 infra.
`get_sanctions_data`	OFAC SDN entities + sanctions pressure scores by country.
`get_news_intelligence`	AI-classified threat news, GDELT signals, cross-source intel.
`get_positive_events`	Diplomatic agreements, humanitarian aid, peace initiatives.
`get_social_velocity`	Reddit r/worldnews + r/geopolitics top 30 posts ranked by velocity score.
`get_china_decision_signals`	Bounded six-domain China summary with canonical provenance and explicit per-domain degradation; no detailed bilateral trade rows or operator health.
`get_defense_industrial_base`	Per-country World Bank military expenditure, armed-forces size, and arms-trade indicators.
`get_military_surge`	Per-theater aircraft postures, foreign-presence detections, and the flights seeder’s own surge alerts.
`get_alert_digest`	Cross-domain alert digest: every threshold trip across the monitored domains, in each producer’s own severity vocabulary.
`get_hotspot_escalation`	The 29 curated intelligence hotspots ranked on a 1-5 composite escalation scale.
`get_focal_points`	Entities where news coverage and live map signals converge, ranked by multi-signal score.
`get_signal_convergence`	One-degree grid cells where protests, military flights, naval movements, and earthquakes co-occur within 24 h.
`get_temporal_anomalies`	Current event counts vs day-of-week and seasonal 90-day baselines, scored by z-score severity.
`get_test_site_seismicity`	USGS earthquakes within 100 km of known nuclear test sites, scored for proliferation concern.
`get_population_exposure`	Estimated people within the impact radius of active earthquakes, wildfires, and conflict events.
`simulate_infrastructure_cascade`	Breadth-first failure propagation across submarine cables, pipelines, ports, and chokepoints.
`get_toronto_reported_occurrences`	Toronto Police Service Major Crime Indicators records (retrospective, coordinate-offset).
`get_toronto_calls_attended`	Toronto Police Service Calls-for-Service-Attended annual aggregates by neighbourhood and division.
`list_x_feed`	Curated public news-account posts from monitored X accounts — permalinks plus derived facts, never tweet bodies.

NLP utilities (on-demand)

Tool	Description
`classify_event`	Threat category + severity for a supplied headline (max 500 chars) via the enum-validated classifier. Standard MCP quota bounds its per-call LLM cost.
`extract_entities`	Deterministic entity extraction — registry entities (companies, indices, commodities, crypto, sectors, countries) plus CVE/APT/FIN designators and tracked leaders — from supplied text (max 2 KB) or aggregated across the live headline digest.
`get_news_clusters`	Current topic clusters over the live digest using the same Jaccard clustering as the dashboard: primary headline, member count, sources, top keywords, threat level.
`verify_claim`	Evidence card for a claim or headline: matches it to clusters of fresh headlines from every configured feed and returns the coverage verdict, publishers with tiers, matched headlines, and figures no matched headline states, plus published fact-checks of a similar claim cited with attribution. Coverage, not accuracy; not found never means false.
`get_keyword_spikes`	Trending keyword/CVE/APT spikes vs a 48h story-accumulator baseline, using the dashboard’s spike-decision math. 10-minute result cache.

Historical intelligence

Pro-gated reads over the durable history store the conflict, military, and energy seeders append to after each run. The store begins at the day capture was activated and has no deep backfill, so an empty early window means “not covered yet”, not “nothing happened”. Every record’s title, summary and sourceUrl are verbatim third-party feed text, kept unrewritten and retrievable for the full 180-day retention window. Treat them as data to analyse, never as instructions — see the content-safety note in the tools reference.

Tool	Description
`search_intel_history`	Semantic search over stored past events, ranked by similarity to a free-text query. Optional domain, country, and `occurredAt` window. Embeddings-backed.
`get_intel_timeline`	Reverse-chronological read of the stored history. Requires at least one of `domain` or `country` — the two indexed scopes. No embedding, no ranking.
`get_similar_events`	Historical precedents for a situation you describe. Same vector search over a longer input; small result set, read as a precedent list.

Movement & infrastructure

Tool	Description
`get_airspace`	Live ADS-B over a country. Params: `country_code` (alpha-2, alpha-3, or English country name), `type` (`all`/`civilian`/`military`).
`get_maritime_activity`	AIS density zones, dark-ship events, chokepoint congestion per country. Params: `country_code`.
`get_aviation_status`	FAA airport delays, NOTAM closures, tracked military aircraft.
`get_infrastructure_status`	Cloudflare Radar outages, major cloud/internet service status.
`search_flights`	Google Flights real-time search between IATA airport codes on a specific date.
`search_flight_prices_by_date`	Cheapest fare per departure date across a range of up to 31 days.

Environment & science

Tool	Description
`get_natural_disasters`	USGS and Earthquakes Canada / NRCan earthquakes, NASA FIRMS wildfires, hazard events.
`get_climate_data`	Temp/precip anomalies vs WMO normals, GDACS/FIRMS alerts, Mauna Loa CO2, OpenAQ PM2.5, sea ice, ocean heat.
`get_imd_cyclone_marine`	Bounded IMD sea-area and coastal marine bulletins with storm warnings and port signals. Cyclone track, wind, and cone are API-only and disabled. Always read `coverageState`; disabled or degraded is not an all-clear.
`get_radiation_data`	Global radiation monitoring station readings + anomaly flags.
`get_research_signals`	Emerging technology events from curated research feeds.

Health

Tool	Description
`get_health_signals`	Active disease outbreaks (WHO/ECDC etc.) and global air-quality station readings (OpenAQ/WAQI PM2.5). For health-risk screening.

Humanitarian & displacement

Tool	Description
`get_displacement_data`	Refugee, asylum-seeker, IDP and stateless counts by country and top flows (UNHCR annual data); `view: "events"` returns IDMC internal displacement from the last 180 days with surge flags; `view: "regions"` returns IOM DTM internal displacement by region.

AI intelligence

Tool	Description	Cost
`get_world_brief`	Precomputed citation-grounded world intel brief from the same `news:insights:v1` snapshot used by the dashboard. `geo_context` is retained for compatibility and does not refocus the seeded snapshot.	Cache
`get_country_brief`	Per-country assessment with source links and analytical frameworks. Paid variants share the country’s panel allocation; incomplete grounding remains retryable.	LLM
`analyze_situation`	Ad-hoc geopolitical deduction from a query + context. Returns confidence + supporting signals.	LLM
`get_forecast_predictions`	Cached forecasts; paid interactive openings return a compact list and signed case admission.	Cache
`get_forecast_case`	One original case for an exact ID and list generation, under the forecast admission on dedicated MCP plans or per call on API plans.	Cache
`get_forecast_theaters`	Latest original simulation theaters, under the same forecast admission on dedicated MCP plans or per call on API plans; source run/time and partial coverage remain explicit.	RPC
`get_forecast_scorecard`	Cached forecast-resolution calibration and scorecard.	Cache

Tool	Description
`get_sources`	Live source inventory (providers + outlets) with tiers and provenance. The sole credential-free, quota-free data tool.
`describe_tool`	Complete definition of any other tool, identical to its `tools/list` entry. Quota-exempt metadata lookup.

API coverage

An API endpoint is MCP-exposed only when the exact METHOD /api/... path is declared in a tool’s registry _apiPaths entry. The table below is the human-facing rendering of those declarations from api/mcp/registry/cache-tools.ts and api/mcp/registry/rpc-tools.ts; it is narrower than the public OpenAPI catalog. A REST route can exist in OpenAPI and still be REST-only. The parity test keeps that distinction explicit: every public OpenAPI operation must either appear in _apiPaths or be listed in tests/mcp-api-parity.test.mjs with a categorized exclusion reason. The canonical current split is whatever this command prints:

./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs

That output includes covered, excluded, and total operation counts. Treat the counts as moving inventory, not product copy; the test and registry are the source of truth. Reverse lookup workflow:

Copy the exact method and path from the OpenAPI page, for example GET /api/research/v1/list-tech-events.
Search this table. If the route appears, call the listed MCP tool.
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.
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.

MCP tool	API endpoints served
`get_market_data`	`GET /api/market/v1/get-fear-greed-index` `GET /api/market/v1/get-physical-divergence-index` `GET /api/market/v1/get-physical-premiums` `GET /api/market/v1/get-sector-summary` `GET /api/market/v1/list-commodity-quotes` `GET /api/market/v1/list-crypto-quotes` `GET /api/market/v1/list-etf-flows` `GET /api/market/v1/list-gulf-quotes` `GET /api/market/v1/list-market-quotes`
`get_economic_data`	`GET /api/economic/v1/get-ecb-fx-rates` `GET /api/economic/v1/get-economic-calendar` `GET /api/economic/v1/get-eu-yield-curve` `GET /api/economic/v1/list-fuel-prices` `GET /api/market/v1/get-cot-positioning` `GET /api/market/v1/list-earnings-calendar`
`get_price_and_debt_indicators`	`GET /api/economic/v1/get-fao-food-price-index` `GET /api/economic/v1/get-national-debt` `GET /api/economic/v1/list-bigmac-prices`
`get_wto_trade_flows`	`GET /api/trade/v1/get-trade-flows`
`get_tariff_averages`	`GET /api/trade/v1/get-tariff-trends`
`get_bilateral_tariff`	`GET /api/trade/v1/get-bilateral-tariff`
`get_us_import_duty`	`GET /api/trade/v1/get-us-import-duty`
`get_energy_intelligence`	`GET /api/economic/v1/get-energy-crisis-policies` `GET /api/supply-chain/v1/get-fuel-shortage-detail` `GET /api/supply-chain/v1/list-energy-disruptions` `GET /api/supply-chain/v1/list-fuel-shortages`
`get_consumer_prices`	`GET /api/consumer-prices/v1/get-consumer-price-freshness` `GET /api/consumer-prices/v1/get-consumer-price-overview` `GET /api/consumer-prices/v1/list-consumer-price-categories` `GET /api/consumer-prices/v1/list-consumer-price-movers` `GET /api/consumer-prices/v1/list-retailer-price-spreads`
`get_supply_chain_data`	`GET /api/supply-chain/v1/get-shipping-stress` `GET /api/trade/v1/get-customs-revenue`
`get_chokepoint_status`	`GET /api/intelligence/v1/get-country-port-activity` `GET /api/supply-chain/v1/get-chokepoint-status`
`get_five_factor_scorecard`	`GET /api/scorecard/v1/get-five-factor-scorecard` `GET /api/scorecard/v1/get-bloc-scorecard`
`list_five_factor_scorecards`	`GET /api/scorecard/v1/list-five-factor-scorecards`
`get_climate_data`	`GET /api/climate/v1/get-co2-monitoring` `GET /api/climate/v1/get-ocean-ice-data` `GET /api/climate/v1/list-air-quality-data` `GET /api/climate/v1/list-climate-anomalies` `GET /api/climate/v1/list-climate-disasters` `GET /api/climate/v1/list-climate-news`
`get_health_signals`	`GET /api/health/v1/list-air-quality-alerts` `GET /api/health/v1/list-disease-outbreaks`
`get_conflict_events`	`GET /api/conflict/v1/list-iran-events` `GET /api/conflict/v1/list-ucdp-events` `GET /api/unrest/v1/list-unrest-events`
`get_news_intelligence`	`GET /api/intelligence/v1/list-cross-source-signals` `GET /api/intelligence/v1/search-gdelt-documents`
`get_country_risk`	`GET /api/intelligence/v1/get-country-risk`
`get_country_brief`	`GET /api/intelligence/v1/get-country-intel-brief`
`get_social_velocity`	`GET /api/intelligence/v1/get-social-velocity`
`get_china_decision_signals`	`GET /api/intelligence/v1/get-china-decision-signals`
`get_company_intelligence`	`GET /api/intelligence/v1/get-company-enrichment` `GET /api/intelligence/v1/list-company-signals` `GET /api/intelligence/v1/search-sec-filings` `GET /api/intelligence/v1/list-material-events`
`search_intel_history`	`POST /api/intelligence/v1/search-intel-history`
`get_intel_timeline`	`GET /api/intelligence/v1/get-intel-timeline`
`get_similar_events`	`POST /api/intelligence/v1/get-similar-events`
`get_natural_disasters`	`GET /api/natural/v1/list-natural-events` `GET /api/seismology/v1/list-earthquakes` `GET /api/wildfire/v1/list-fire-detections`
`get_radiation_data`	`GET /api/radiation/v1/list-radiation-observations`
`get_infrastructure_status`	`GET /api/infrastructure/v1/list-internet-outages`
`get_airspace`	`GET /api/aviation/v1/track-aircraft` `GET /api/military/v1/list-military-flights`
`get_maritime_activity`	`GET /api/maritime/v1/get-vessel-snapshot`
`get_military_posture`	`GET /api/military/v1/get-theater-posture`
`get_displacement_data`	`GET /api/displacement/v1/get-displacement-summary`
`get_positive_events`	`GET /api/positive-events/v1/list-positive-geo-events`
`get_sanctions_data`	`GET /api/sanctions/v1/list-sanctions-pressure` `GET /api/sanctions/v1/lookup-sanction-entity`
`get_research_signals`	`GET /api/research/v1/list-tech-events`
`get_prediction_markets`	`GET /api/prediction/v1/list-prediction-markets`
`get_forecast_predictions`	`GET /api/forecast/v1/get-forecasts`
`get_forecast_case`	`GET /api/forecast/v1/get-forecasts`
`get_forecast_theaters`	`GET /api/forecast/v1/get-simulation-outcome`
`get_forecast_scorecard`	`GET /api/forecast/v1/get-forecast-scorecard`
`classify_event`	`GET /api/intelligence/v1/classify-event`
`extract_entities`	`GET /api/news/v1/list-feed-digest`
`get_news_clusters`	`GET /api/news/v1/list-feed-digest`
`verify_claim`	`GET /api/news/v1/list-feed-digest`, `GET /api/news/v1/search-fact-checks`, `GET /api/news/v1/search-claim-headlines`
`analyze_situation`	`POST /api/intelligence/v1/deduct-situation`
`search_flights`	`GET /api/aviation/v1/search-google-flights`
`search_flight_prices_by_date`	`GET /api/aviation/v1/search-google-dates`

Tools with no declared API paths still return data via tools/call, but they should not be read as REST equivalents:

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).
Seeded synthesis snapshots — get_world_brief reads the dashboard’s accepted news:insights:v1 payload through the bootstrap path; it has no direct REST-equivalent operation or request-time LLM call.
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).

In this table, covered means a tool declares the exact operation in _apiPaths. Common REST-only exclusions in tests/mcp-api-parity.test.mjs:

mutating — 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.
llm-passthrough — direct per-call LLM work that needs a purpose-built cost/threat model before MCP exposure.
fetch-on-miss — may call paid or rate-limited upstreams when cache is cold, or accepts high-cardinality identifiers that are not cache-bundle friendly. Exclusion reasons must include one enforced secondary signal: high-cardinality-input, paid-upstream, or llm-cost. Examples: GET /api/conflict/v1/list-acled-events, GET /api/infrastructure/v1/list-service-statuses, GET /api/supply-chain/v1/get-critical-minerals, and GET /api/aviation/v1/get-flight-status.
admin — internal-only operations behind an explicit admin boundary, such as an admin key, internal-only middleware, or cron-only path.
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.
deferred-to-future-tool — 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.

Current follow-up trackers:

#4525 — pure-read deferred MCP coverage candidates.
#4526 — manual mapping and fetch-on-miss triage.

See the Tool catalog above for the complete live tool registry, or the MCP Tools Reference for per-tool details.

Prompts and resources

In addition to the live tool registry, WorldMonitor exposes MCP prompts and resources so clients can discover common workflows and address stable data slices without inventing tool plans from scratch.

Prompts

prompts/list returns the workflow templates below. prompts/get renders the selected template into a user message with the right tools/call sequence and pre-baked JMESPath projections.

Prompt	Purpose
`country-view`	Open the embedded country panel with progressive, authenticated section reads.
`country-briefing`	Country risk, AI intelligence brief, and macro indicators for one ISO 3166-1 alpha-2 country.
`energy-shock-watch`	Active energy disruptions, fuel shortages, and government crisis policies; optional country focus.
`market-open-prep`	Lightweight equity, commodity, and crypto mover briefing for a market-open scan.
`conflict-pulse`	Active UCDP conflict events plus alert-flagged top news, globally or for one country.
`route-risk-check`	Maritime chokepoint transit summary and risk posture for one chokepoint.
`freshness-audit`	Cache freshness check across market, energy, and chokepoint bootstrap envelopes.
`trade-exposure-check`	US import exposure for one HS6 product from one partner: the duty in force today, including Section 301 and 232 duties when loaded, then the schedule rate and applied-average trend through 2023.

prompts/list and prompts/get are metadata/workflow discovery methods. They are exempt from the Pro daily quota, though they still count toward your plan’s per-minute burst.

Resources

Resources have three access classes. Public concrete resources are surfaced by anonymous resources/list and read anonymously and quota-free. The account allowance resource appears in resources/list only for a user-bound authenticated client and is also quota-free. URI templates (parameterised, data-bearing) are surfaced by resources/templates/list; their _meta["worldmonitor/access"] marker states whether a signed-in free account or a Pro subscription can read each concrete instantiation. resources/list — concrete, anonymously readable, quota-free:

Resource URI	Backing data
`worldmonitor://seed-meta/freshness`	Stock market-data bootstrap write-age only: `cached_at` and `stale` for `seed-meta:market:stocks`. Does not certify sector valuation completeness — use `get_market_data` `valuationCoverage` (`sourceStatus`, unavailable/last-good/diagnostics). Cheap seeder health probe — no auth, no quota.

Authenticated resources/list additionally exposes worldmonitor://account/mcp-allowance. Its read returns the current account’s used, limit, remaining, resetsAt, and sharedWithRestApi fields. sharedWithRestApi is true when the budget being reported is the account’s REST allowance, which means used counts REST requests as well as tool calls — read it before treating that number as your own call history. Free accounts also receive request-window usage, remaining windows, the idle-gap duration, and the active-window expiry. The read uses the enforcement counters directly and never reserves an allowance slot. Hosts that expose tools without resources/read can call get_mcp_allowance({}) for the same snapshot. It requires verified user-bound OAuth or wm_… credentials, accepts only optional jmespath, and rejects account selectors and panel_request before admission. It remains available at the daily cap, spends no daily allowance, and uses the shared 192/minute protocol bucket. Unreadable counters return an error instead of a zero snapshot. Account totals do not identify individual callers. resources/templates/list — parameterised URI templates. Substitute the placeholder, then resources/read the concrete URI. Follow the template’s _meta["worldmonitor/access"] marker: free-account templates use the authenticated free-account allowance, while subscription templates require Pro. Each read consumes the same caller-applicable allowance or quota slot as the equivalent tools/call:

Resource URI template	Backing data
`worldmonitor://countries/{iso2}/risk`	Country risk score, component breakdown, travel advisory, and sanctions exposure. `{iso2}` is lowercase alpha-2, for example `de` or `us`.
`worldmonitor://chokepoints/{slug}/status`	Chokepoint transit summary and risk narrative. `{slug}` is one of the published kebab-case chokepoint slugs, such as `suez`, `strait-of-hormuz`, or `bab-el-mandeb`.
`worldmonitor://markets/{symbol}/quote`	Single-symbol market quote slice. `{symbol}` is uppercase, for example `AAPL`, `GC=F`, or `BTC-USD`.

resources/list and resources/templates/list are metadata and do not consume the daily allowance. resources/read of a template instantiation consumes the same caller-applicable slot as the equivalent tools/call; it routes through the same dispatcher so a data-bearing resource cannot bypass the free-account or subscription limit. Reads of the public freshness resource and authenticated account allowance resource are quota-free. As with every MCP method, all of these still count toward your plan’s per-minute burst. For the exact -32029 status/header differences between per-minute throttling and daily quota exhaustion, see the MCP Error Catalog.

MCP Apps (interactive UI)

The server supports MCP Apps (extension io.modelcontextprotocol/ui, spec 2026-01-26) — interactive views a host renders in a sandboxed iframe when a linked tool is called. Three wire signals drive it:

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. Each UI-linked tool carries _meta.ui.resourceUri (and the deprecated flat ui/resourceUri alias) pointing at its UI resource.
resources/list surfaces the UI resources themselves, alongside the concrete data resource (the parameterised data templates live in resources/templates/list):

UI resource URI	Linked tool	Renders
`ui://worldmonitor/country-risk-v3.html`	`get_country_risk`	CII score, unrest/conflict/security/news component breakdown, travel-advisory level, and OFAC sanctions exposure.
`ui://worldmonitor/world-brief-v2.html`	`get_world_brief`	The precomputed, citation-grounded global intelligence brief as readable paragraphs, plus grounding headlines and source articles.
`ui://worldmonitor/country-brief-v3.html`	`get_country_brief`	The AI-synthesised per-country brief as paragraphs, with the analytical framework lens and grounding sources.
`ui://worldmonitor/market-radar-v3.html`	`get_market_data`	Fear & Greed plus all loaded equity, commodity, crypto, Gulf and sector quotes, asset names and expandable intraday charts.
`ui://worldmonitor/chokepoint-monitor-v2.html`	`get_chokepoint_status`	Per-chokepoint rolling transit summaries (today’s count, week-over-week change, tanker split) with a risk-level badge.
`ui://worldmonitor/news-intelligence-v3.html`	`get_news_intelligence`	AI-classified top stories with category, alert flag, country, and source.
`ui://worldmonitor/conflict-events-v2.html`	`get_conflict_events`	Active armed-conflict events (belligerents, violence type, country, fatalities, date) from the UCDP feed.
`ui://worldmonitor/natural-disasters-v3.html`	`get_natural_disasters`	Recent M4.5+ earthquakes (USGS and Earthquakes Canada / NRCan: magnitude, place, time, source) and active wildfires (NASA FIRMS), grouped.
`ui://worldmonitor/prediction-markets-v3.html`	`get_prediction_markets`	Active event-contract odds grouped by category (geopolitical, tech, finance) with a probability bar per market. Full-envelope projections and summary samples preserve loaded contracts and snapshot metadata. Missing or malformed categories and unknown freshness remain explicit.
`ui://worldmonitor/forecasts-v4.html`	`get_forecast_predictions`	Loaded forecast cards and local filters, with original case evidence read under the same signed opening allocation.
`ui://worldmonitor/news-dashboard-v3.html`	`open_news_dashboard`	Dashboard news panels and interactive map.
`ui://worldmonitor/country-view-v3.html`	`open_country_brief`	Shared country sections, topics, evidence and exports.

Country Risk v2 preserves supplied original and projected objects, including nested CII components and upstream availability. Missing or malformed advisory values remain unknown; an explicit empty native string still means no advisory. Result replacement clears prior risk details. The original ui://worldmonitor/country-risk.html remains a private read alias for installed metadata and can be removed when that metadata is retired. All UI resources share mimeType: text/html;profile=mcp-app. resources/read on a ui:// URI returns an HTML view. Unlike the data resources, a ui:// read is public and quota-exempt — the template carries no data and spends no upstream data call, so a host can preload it (and an agent-readiness scanner can fetch it) without credentials and without touching the Pro daily cap. Statically bundled widgets are self-contained. The news, country and market views load their current JavaScript and CSS from https://www.worldmonitor.app, as permitted by their resource metadata. All views communicate with the host over the standard MCP Apps postMessage bridge (ui/initialize → ui/notifications/tool-result → ui/notifications/size-changed). The compact Country Brief view accepts the original response and supported object projections. Retained news digest coverage shows a neutral notice without claiming that the assessment used retained grounding. Reported snapshot age and a valid UTC refresh-attempt time appear only when supplied. Missing or malformed coverage makes no freshness claim. Replacing a result clears prior paragraphs, evidence, source links, generation time and retained notice. Hosts advertise country-brief-v3.html; country-brief-v2.html and the original country-brief.html remain private read aliases until older installed metadata is retired. Ordinary country asks still open the full country view. For the full MCP Apps contract — host flow, security posture, per-widget inventory, source files, and docs-stat drift checks — see MCP Apps.

JSON-RPC example

Server-side with a direct API key — send it as X-WorldMonitor-Key, not as a bearer token.

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"}}
  }'

If instead you’ve completed the OAuth flow and hold an access token from /api/oauth/token, pass it as Authorization: Bearer $TOKEN.

Response shape

Tool responses use the standard MCP content block format:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{...json payload...}" }
    ],
    "structuredContent": { "...": "the same payload, as an object" }
  }
}

For cache tools, the JSON payload includes cached_at (ISO timestamp of the oldest contributing data point) and stale (boolean — true when any contributing seed exceeded its per-key freshness budget) so the model can reason about freshness. A few more fields appear only when relevant:

activationUnknown: true when a content-freshness activation marker could not be read, so stale was computed without knowing whether the producer has ever published.
freshnessUnknown: true when a freshness record could not be read, so stale is true because freshness is unknown, not because the data is known to be old.
unreadable (a list of data labels) when some cache reads failed. Those sections are null because they could not be read, not because the dataset is empty, and retrying shortly usually fills them.
contentFreshnessPendingUntil (ISO timestamp) when a never-published seed is inside its deployment grace window. Content-age checks start counting against stale after that deadline.

Cache tools cap list and map fields at 30 items when limit is omitted; pass limit: 0 only when you need the full payload, and project it with jmespath to keep the response small.

Telemetry (for operators)

Every tools/call emits a structured telemetry line tagged mcp.toolcall with latency, payload bytes (pre and post JMESPath), jmespath_used, and budget_exceeded. initialize emits mcp.tools_list_emitted with tool-count and tools-list byte metrics. Caller-facing behaviour is unaffected.

Data freshness

All cache tools read from Redis keys written by Railway cron seeders. Typical freshness:

Domain	Typical freshness
Markets (intraday)	1–5 min
Flights (ADS-B)	1–3 min
Maritime (AIS)	5–15 min
Conflicts / unrest	15–60 min
Macro / BIS / Eurostat	daily–weekly
IMF WEO	monthly

Seed-level health per key: status.worldmonitor.app.

Errors

The MCP handler signals failure on three independent layers — HTTP status, JSON-RPC error.code, and soft-behavior envelopes inside result.content[0].text — and a single failure can touch any combination.

Layer	Common shapes	Where to look
HTTP status	`200` (default for JSON-RPC), `401`, `429`, `503`	`WWW-Authenticate` / `Retry-After` headers
JSON-RPC	`-32001` auth · `-32029` rate-limited · `-32602` bad params · `-32603` internal	`error.code` + `error.message`
Soft envelope	`_budget_exceeded` (response too big), `_jmespath_error` (projection failed)	`result.content[0].text` parsed as JSON

Triage from the outside in: HTTP status → JSON-RPC code → soft envelope. The full per-shape reference (trigger, paired status, recovery, example payload) lives in the MCP Error Catalog. A few high-frequency callouts:

401 + -32001 carries a WWW-Authenticate header with resource_metadata pointing at the document for the path you called — /.well-known/oauth-protected-resource/mcp, or /api/mcp under the deployed route. RFC 9728-aware clients re-run the OAuth flow on this header automatically.
429 + -32029 is the plan-resolved daily cap (Retry-After: <seconds-until-UTC-midnight>), so the number in the message is whichever budget rejected, not always 50. 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.

WebMCP — experimental, tab-bound tools that operate the visible WorldMonitor website
MCP Quickstart — connect Claude, ChatGPT, Codex or Cursor in about a minute
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

Natural Disasters Panel Requests

On Pro and Pro Business, get_natural_disasters opens one Natural Disasters allocation. Repeated opens and dataset, magnitude, activity and limit filters reuse that admission within five minutes. Use its returned panelRequest.token as panel_request for bounded reads. Explicit refresh needs refresh: true, a UUID request_id, and no reader token; the same UUID retries the refresh allocation. API and free-account callers keep ordinary per-tool charging and existing filter coercions, and reject the paid refresh controls. Each uncached execution reads three fixed data keys and the existing seismology metadata key as one logical read within the 64-read admission. Exact successful filtered originals replay before summary or JMESPath only until the earliest observable source or EONET retention deadline. A new filter or unavailable, malformed, known degraded or unknown-clock observation can reread under the same allocation. Blocked regional source decisions remain readable but uncached, including zero-request preflight decisions. This does not establish complete provider coverage. The existing news token still permits only its exact hazard dataset list and limits 100, 20 or 1; it cannot use standalone magnitude or activity filters. Source data and internal deadlines do not add public metadata fields. Confirmed current usage accompanies authorized reads; an unknown counter omits the numeric notice.

News Intelligence panel admission

On Pro and Pro Business, get_news_intelligence opens one News Intelligence allocation. Repeated opens, filters, summary and JMESPath views reuse the same complete original within the admission window. The returned panelRequest.token is a closed panel_request for this tool only; news and country receipts cannot authorize it. Explicit refresh uses refresh: true, a UUID request_id, and no reader token. The same UUID retries that allocation. Authorized receipt reads query current usage without a new allocation; unknown usage omits the numeric notice. API and free-account calls retain ordinary per-tool charging and reject these paid controls. Reuse uses the existing four dataset GETs and three metadata GETs. It expires at the earliest of the 30/45/60-minute metadata deadlines, the shared 60-minute Insights generation limit, the assessed GDELT content-age deadline, and admission expiry. Advisory publication time is validated, but this source graph has no independent advisory freshness assessment. Missing, degraded, malformed, old, future or unassessed sources remain retryable. Paid reads expose proven stale generation through stale and unassessed clocks through freshnessUnknown; source values remain intact. The cross-source producer permits an observed empty signal list; empty Insights and advisory bootstrap lists are not reusable. The 64-read limit counts uncached tool executions, not individual Redis GETs. This does not prove complete provider coverage.

Chokepoint panel admission

On Pro and Pro Business, get_chokepoint_status opens one signed chokepoints allocation. Repeated filters, summary and JMESPath views share that allocation. Complete effective requested source subsets reuse their uncapped originals; changing the normalized dataset subset or chokepoint selector can reacquire sources under the same allocation. Unknown-only dataset selectors use the full bundle. A keyed filter with no match retains the original map, so it cannot manufacture complete empty coverage. Sparse AIS, unavailable today counts and partial modeled flows remain visible and retryable. Use the returned panelRequest.token as panel_request only for this tool. Explicit refresh: true requires a UUID request_id and no reader token; the same UUID retries that allocation. Authorized receipt reads report current usage without reserving another allocation; unknown usage omits the numeric notice. API and free-account calls retain per-tool accounting and reject these paid controls. An uncached execution uses the existing six dataset GETs, six metadata GETs and one activation EXISTS command. The 64-read admission bound counts tool executions, not those 13 Redis commands. Reuse checks selected source shapes, availability, publication clocks and CN/HK critical content age, both after lookup and before cache storage. Partial, malformed, unassessed or expired originals are not cached as complete. Reference-year baselines and modeled flow publication dates do not prove current metered oil or fresh underlying history. The private wrapped cache remains 512 KiB; tool output remains 128 KiB. This admission change does not add website details, histories, warnings or provider reads.

World Brief panel admission

On Pro and Pro Business, get_world_brief opens one signed world-brief allocation. Repeated questions, compatibility geo_context changes and JMESPath views share that allocation. The RPC ignores summary; it does not summarize the brief. Reuse retains the accepted original prose, evidence and citation order before presentation. It ends at the earlier of admission expiry and generatedAt plus 60 minutes; replay recomputes the content age. This is a retained accepted generation, not an attestation that the latest producer attempt succeeded. Use panelRequest.token as panel_request only for this tool. Explicit refresh: true requires a UUID request_id and no reader token; the same UUID retries that allocation. Authorized receipt reads query current usage without reserving another allocation. Unknown usage omits the numeric notice. API allowances retain per-tool billing, and free accounts retain the existing subscription denial. Valid content aged 60 minutes to less than three hours remains available with stale: true but is not retained for fresh replay. Failed, missing, malformed and expired originals can retry under the same allocation. The 64-read bound counts uncached tool executions. Acquisition uses the existing authenticated bootstrap gateway path; it adds no provider call or producer-health transport. The private wrapped cache remains 512 KiB and tool output remains 64 KiB.

​Endpoints

​Protocol negotiation

​Streamable HTTP responses

​Authentication

​Redirect URI allowlist

​Client ID Metadata Documents

​Token lifetimes

​Pro sign-in flow

​Daily limit (Pro tier)

​Connected MCP clients

​Plans & limits

​Other rate limits

​Client setup

​Claude (desktop app, claude.ai, mobile)

​The mcp-remote bridge (stdio-only clients)

​Codex

​Claude Code

​Cursor

​Other hosted clients

​MCP Inspector (debugging)

​Tool catalog

​Markets & economy

​Energy

​Geopolitical & security

​NLP utilities (on-demand)

​Historical intelligence

​Movement & infrastructure

​Environment & science

​Health

​Humanitarian & displacement

​AI intelligence

​Meta

​API coverage

​Prompts and resources

​Prompts

​Resources

​MCP Apps (interactive UI)

​JSON-RPC example

​Response shape

​Telemetry (for operators)

​Data freshness

​Errors

​Related

​Natural Disasters Panel Requests

​News Intelligence panel admission

​Chokepoint panel admission

​World Brief panel admission

Endpoints

Protocol negotiation

Streamable HTTP responses

Authentication

Redirect URI allowlist

Client ID Metadata Documents

Token lifetimes

Pro sign-in flow

Daily limit (Pro tier)

Connected MCP clients

Plans & limits

Other rate limits

Client setup

Claude (desktop app, claude.ai, mobile)

The `mcp-remote` bridge (stdio-only clients)

Codex

Claude Code

Cursor

Other hosted clients

MCP Inspector (debugging)

Tool catalog

Markets & economy

Energy

Geopolitical & security

NLP utilities (on-demand)

Historical intelligence

Movement & infrastructure

Environment & science

Health

Humanitarian & displacement

AI intelligence

Meta

API coverage

Prompts and resources

Prompts

Resources

MCP Apps (interactive UI)

JSON-RPC example

Response shape

Telemetry (for operators)

Data freshness

Errors

Related

Natural Disasters Panel Requests

News Intelligence panel admission

Chokepoint panel admission

World Brief panel admission