MCP Quickstart

​

1. Pick a tier and grab credentials

• Pro — sign in with your WorldMonitor account, no key to manage. 50 quota-consuming calls per UTC day.
• API Starter / Business / Enterprise — paste a user-issued wm_… key in your client, or use the same OAuth flow as Pro. wm_… MCP calls are throttled at 60 requests/minute/key in this handler; REST/API plan allowances are separate from the Pro/OAuth MCP daily counter.

​

2. Add the server to Claude Desktop

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

​

Alternative: the mcp-remote bridge

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

• Attach your credential explicitly. The server completes the connection and all discovery (tools/prompts/resources listings) anonymously by design, so mcp-remote never sees a 401 challenge at connect time and does not start its OAuth flow on its own. Without the header, the connection looks healthy but every tools/call fails with 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: your first tool call returns the 401 challenge that triggers mcp-remote’s browser consent flow (dynamic client registration works on both worldmonitor.app and www.worldmonitor.app). Older mcp-remote versions handle this mid-session flow less reliably than the connect-time one, so if the consent window never appears, the explicit key header above is the deterministic path.

​

3. Ask your first question

What’s the current US equity market sentiment and which sectors are leading or lagging today?

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_market_data", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"cached_at\":\"2026-05-17T10:34:00.852Z\",\"stale\":false,\"data\":{\"stocks-bootstrap\":{...},\"sectors\":{...},\"fear-greed\":{...}}}" }
    ],
    "isError": false
  }
}

• cached_at — ISO timestamp of the oldest contributing data point. Use this to reason about how fresh the answer is.
• stale — true when any contributing seed exceeded its freshness budget. Tells the model when to caveat its answer.

​

4. Trim the response (when it matters)

{
  "name": "get_market_data",
  "arguments": {
    "jmespath": "data.\"stocks-bootstrap\".quotes[?symbol=='AAPL' || symbol=='MSFT'].{s:symbol,p:price,chg:change}"
  }
}

​

5. Browse the full tool catalog

• Geopolitical & security — get_conflict_events, get_country_risk, get_military_posture, get_cyber_threats, get_sanctions_data, get_news_intelligence.
• Movement & infrastructure — get_chokepoint_status, get_maritime_activity, get_airspace, get_aviation_status, search_flights.
• Energy & macro — get_energy_intelligence, get_economic_data, get_country_macro, get_tariff_trends, get_eu_housing_cycle, get_eu_quarterly_gov_debt, get_eu_industrial_production.
• Environment & health — get_climate_data, get_natural_disasters, get_radiation_data, get_health_signals.
• AI synthesis (live LLM, slower — 1–4 s) — get_world_brief, get_country_brief, analyze_situation, generate_forecasts.

​

Troubleshooting and expectations

• Call tools/list for the current tool names and compressed descriptions.
• Call describe_tool with tool_name when a tools/list entry is too short to choose confidently.
• Use the API coverage table when you are starting from a REST method/path and want to know whether an exact MCP _apiPaths mapping exists.

​

What just happened

1. Claude Desktop reads claude_desktop_config.json, sees the WorldMonitor server, and on first use POSTs initialize to https://worldmonitor.app/mcp. The server responds with its capabilities, the negotiated protocol version (default 2025-06-18, matching the static server card; clients pinned to 2025-03-26 still get 2025-03-26), and a session-level instructions string that tells the model about the universal jmespath argument. Clients that advertise text/event-stream may receive this response as SSE with a resumable Mcp-Session-Id / Last-Event-ID cursor; clients that do not advertise SSE receive JSON. See protocol negotiation and Streamable HTTP responses for the rollout details.
2. Claude Desktop calls tools/list and receives 40 compressed tool descriptions (≤120 bytes per tool). The compressed form keeps tools/list cheap; describe_tool returns the full definition on demand.
3. When you ask a question that needs live data, Claude picks a tool, calls tools/call, and inlines the response into its reply. Cache tools return in under a second; LLM-backed tools (get_world_brief, analyze_situation, etc.) take 1–4 s.

​

Server-side curl

export WM_KEY="wm_0123456789abcdef0123456789abcdef01234567"  # API Starter+ key from worldmonitor.app/settings

# 1. List tools (compressed descriptions)
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_market_data","arguments":{}}
  }'

# 3. Same call with a JMESPath projection (much smaller response).
# Heredoc keeps the single-quoted JMESPath string literals readable —
# wrapping the JSON in -d '...' would collide with the inner quotes.
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "jsonrpc":"2.0","id":3,
  "method":"tools/call",
  "params":{
    "name":"get_market_data",
    "arguments":{
      "jmespath":"data.\"stocks-bootstrap\".quotes[?symbol=='AAPL' || symbol=='MSFT'].{s:symbol,p:price}"
    }
  }
}
EOF

​

Where to go next

• JMESPath guide — projection grammar with 12 worked examples against real response shapes. Read this before your second day of MCP use; it will pay for itself in saved tokens within an hour.
• MCP Tools Reference — per-tool parameters, freshness budgets, API endpoint mapping, and curl examples for every tool.
• MCP Server reference — auth modes, OAuth setup, plans & quotas, error codes, and freshness model.
• Command-line client — prefer a shell? npx worldmonitor tools drives the same tools from your terminal or a script, no integration to write.
• Official SDKs — prefer a library? Zero-dependency clients for Python (pip install worldmonitor-sdk), Ruby (gem install worldmonitor), and Go (go get github.com/koala73/worldmonitor/sdk/go) call the same tools with language-native helpers.
• Authentication overview — when to use an API key in X-WorldMonitor-Key vs. OAuth vs. browser session.

​

Operational note (for ops, not callers)