Skip to main content
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 conflict, market, aviation, maritime, economic, and forecasting data directly into a model’s context.
The MCP server is gated behind PRO. Free-tier users see a 401 at the OAuth step.

​
Endpoints

EndpointPurpose
https://worldmonitor.app/mcpJSON-RPC server (Streamable HTTP transport, protocol 2025-03-26)
https://api.worldmonitor.app/api/oauth/registerDynamic Client Registration (RFC 7591)
https://api.worldmonitor.app/api/oauth/authorizeOAuth 2.1 authorization endpoint (PKCE required)
https://api.worldmonitor.app/api/oauth/tokenToken endpoint (authorization_code + refresh_token)
https://api.worldmonitor.app/.well-known/oauth-authorization-serverAS metadata (RFC 8414)
https://worldmonitor.app/.well-known/oauth-protected-resourceResource server metadata (RFC 9728)
Protocol version: 2025-03-26. Server identifier: worldmonitor v1.0.

​
Authentication

The MCP handler accepts two auth modes, in priority order:
  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_live_.... Intended for server-side scripts, curl, and custom integrations. Do not send a wm_live_... key as a Bearer token — it will fail OAuth resolution and return 401 invalid_token.
Both modes check the same PRO entitlement before every tool call, so a subscription downgrade revokes access on the next request.

​
Redirect URI allowlist

Dynamic Client Registration is not open to arbitrary HTTPS redirects. Only these prefixes are accepted:
  • 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
Other clients must proxy via one of these redirects or run locally.

​
Token lifetimes

ArtifactTTL
Authorization code10 min
Access token1 hour
Refresh token7 days
Registered client record90 days (sliding)

​
Rate limits

  • MCP calls: 60 requests / minute / API key (sliding window)
  • OAuth authorize: 10 requests / minute / IP
  • OAuth token: 10 requests / minute / IP
  • Dynamic registration: 5 registrations / minute / IP
Exceeding returns 429 with a Retry-After header.

​
Client setup

​
Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) — use the remote MCP entry: 
{
  "mcpServers": {
    "worldmonitor": {
      "url": "https://worldmonitor.app/mcp"
    }
  }
}
Claude Desktop handles the OAuth flow automatically on first connection.

​
Claude web (claude.ai)

Add via Settings → Connectors → Add custom connector:
  • Name: WorldMonitor
  • URL: https://worldmonitor.app/mcp

​
Cursor

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

​
MCP Inspector (debugging)

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

​
Tool catalog

The server exposes 32 tools. Most are cache-reads over pre-seeded Redis keys (sub-second). Six (get_world_brief, get_country_brief, analyze_situation, generate_forecasts, search_flights, search_flight_prices_by_date) call live LLMs or external APIs and are slower.

​
Markets & economy

ToolDescription
get_market_dataEquity quotes, commodity prices (incl. gold GC=F), crypto, FX, sector performance, ETF flows, Gulf markets.
get_economic_dataFed Funds, economic calendar, fuel prices, ECB FX, EU yield curve, earnings, COT, energy storage, BIS DSR + property prices.
get_country_macroIMF WEO bundle per country: inflation, current account, GDP/capita, unemployment, savings-investment gap (~210 countries).
get_eu_housing_cycleEurostat annual house price index (prc_hpi_a), 10-yr sparkline per EU member + EA20/EU27.
get_eu_quarterly_gov_debtEurostat quarterly gross government debt (%GDP), 8-quarter sparkline.
get_eu_industrial_productionEurostat monthly industrial production index, 12-month sparkline.
get_prediction_marketsActive Polymarket event contracts with live probabilities.
get_supply_chain_dataDry bulk shipping stress index, customs flows, COMTRADE bilateral trade.
get_commodity_geo71 major mining sites worldwide (gold, silver, copper, lithium, uranium, coal).

​
Geopolitical & security

ToolDescription
get_conflict_eventsActive UCDP/Iran conflicts, unrest w/ geo-coords, country risk scores.
get_country_riskCII score 0-100, component breakdown, travel advisory, OFAC exposure per country. Fast, no LLM.
get_military_postureTheater posture + military risk scores.
get_cyber_threatsURLhaus/Feodotracker malware IOCs, CISA KEV catalog, active C2 infra.
get_sanctions_dataOFAC SDN entities + sanctions pressure scores by country.
get_news_intelligenceAI-classified threat news, GDELT signals, cross-source intel.
get_positive_eventsDiplomatic agreements, humanitarian aid, peace initiatives.
get_social_velocityReddit r/worldnews + r/geopolitics top posts, engagement scores.

​
Movement & infrastructure

ToolDescription
get_airspaceLive ADS-B over a country. Params: iso2 (2-letter code), filter (all/civilian/military).
get_maritime_activityAIS density zones, dark-ship events, chokepoint congestion per country. Params: iso2.
get_aviation_statusFAA airport delays, NOTAM closures, tracked military aircraft.
get_infrastructure_statusCloudflare Radar outages, major cloud/internet service status.
search_flightsGoogle Flights real-time search between IATA airport codes on a specific date.
search_flight_prices_by_dateDate-grid cheapest-day pricing across a range.

​
Environment & science

ToolDescription
get_natural_disastersUSGS earthquakes, NASA FIRMS wildfires, hazard events.
get_climate_dataTemp/precip anomalies vs WMO normals, GDACS/FIRMS alerts, Mauna Loa CO2, OpenAQ PM2.5, sea ice, ocean heat.
get_radiation_dataGlobal radiation monitoring station readings + anomaly flags.
get_research_signalsEmerging technology events from curated research feeds.

​
AI intelligence (live LLM)

ToolDescriptionCost
get_world_briefAI-summarized world intel brief. Optional geo_context param.LLM
get_country_briefPer-country geopolitical + economic assessment. Supports analytical frameworks.LLM
analyze_situationAd-hoc geopolitical deduction from a query + context. Returns confidence + supporting signals.LLM
generate_forecastsFresh probability estimates (bypasses cache).LLM
get_forecast_predictionsPre-computed cached forecasts. Fast.Cache

​
JSON-RPC example

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

# 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":{"iso2":"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...}" }
    ],
    "isError": false
  }
}
For cache tools, the JSON payload includes _meta with fetchedAt and staleness so the model can reason about freshness.

​
Data freshness

All cache tools read from Redis keys written by Railway cron seeders. Typical freshness:
DomainTypical freshness
Markets (intraday)1–5 min
Flights (ADS-B)1–3 min
Maritime (AIS)5–15 min
Conflicts / unrest15–60 min
Macro / BIS / Eurostatdaily–weekly
IMF WEOmonthly
Seed-level health per key: status.worldmonitor.app.

​
Errors

CodeMeaning
401Invalid / missing token
403Token valid but account not PRO
404Unknown tool name
429Rate limited (60 req/min/key)
503Upstream cache unavailable
Tool-level errors return isError: true with a text explanation in content.