docs/agent-discovery.mdx
WorldMonitor is built to be agent-native. An autonomous agent — Claude, Cursor, an MCP client, or your own LangChain / LangGraph workflow — can start from a single root URL and discover everything it needs: REST schemas, MCP transport, OAuth flow, skill bundles, and human-readable briefings.
No prior knowledge required. Just GET https://worldmonitor.app/.
https://worldmonitor.app/
The HTTP response carries an RFC 8288 Link: header with rel values pointing at every machine-readable surface below. An agent that follows the links resolves the full picture without hardcoding a single path.
curl -sI https://worldmonitor.app/ | grep -i '^link:'
You'll see entries like:
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
</openapi.json>; rel="service-desc"; type="application/json",
</openapi.yaml>; rel="service-desc"; type="application/vnd.oai.openapi",
</docs/documentation>; rel="service-doc"; type="text/html",
</api/health>; rel="status"; type="application/json",
</.well-known/oauth-protected-resource>; rel="...oauth-protected-resource",
</.well-known/oauth-authorization-server>; rel="...oauth-authorization-server",
</.well-known/mcp/server-card.json>; rel="mcp-server-card"; anchor="/mcp",
</.well-known/agent-skills/index.json>; rel="agent-skills-index"; type="application/json"
| Endpoint | Standard | What it returns |
|---|---|---|
/.well-known/api-catalog | RFC 9727 | JSON linkset bundling every other discovery URL — start here if you want one fetch and a map |
/openapi.yaml | OpenAPI 3.1 | Single bundled spec covering every REST service (Conflict, Resilience, Market, Economic, Maritime, Aviation, Climate, …) — feed it to any code-generator |
/openapi.json | OpenAPI 3.1 | Byte-identical bundle as minified JSON — same spec as /openapi.yaml, for tooling and scanners that only parse JSON |
/docs/api-versioning | Policy | REST compatibility, deprecation notice, and sunset-header contract |
/.well-known/mcp/server-card.json | MCP | Transport (streamableHttp), endpoint, OAuth resource, scopes, streaming, capability flags |
/.well-known/oauth-authorization-server | RFC 8414 | OAuth 2.1 authorization-server metadata (PKCE, DCR, token endpoints) |
/.well-known/oauth-protected-resource | RFC 9728 | Resource metadata for https://worldmonitor.app/mcp |
/.well-known/agent-skills/index.json | (custom) | Index of pre-packaged agent skills (fetch-country-brief, fetch-resilience-score, …) — each skill is a self-contained recipe |
/llms.txt | llmstxt.org | LLM-friendly markdown briefing — overview, capabilities, links |
/llms-full.txt | (extension) | Long-form variant covering all data layers, panels, and data sources |
/api/health | (custom) | Per-key seed status, freshness, record counts — agents can gate fetches on this |
The header-discoverable static assets (.well-known/*, /openapi.yaml, /openapi.json) serve Access-Control-Allow-Origin: * and are cached public, max-age=3600 — safe to memoize. /api/health uses the normal API CORS allowlist and is not cached (private, no-store) because it reflects real-time seed freshness; agents should hit it fresh whenever they need to gate on data availability.
# 1. Discover the bundled OpenAPI URL (linkset[0] enumerates every API via
# RFC 9727 `item` links; select the REST API context object by anchor)
curl -s https://worldmonitor.app/.well-known/api-catalog \
| jq -r '.linkset[] | select(.anchor == "https://api.worldmonitor.app/")."service-desc"[0].href'
# → https://www.worldmonitor.app/openapi.yaml
# 2. Generate clients
curl -s https://www.worldmonitor.app/openapi.yaml -o worldmonitor.openapi.yaml
npx @openapitools/openapi-generator-cli generate \
-i worldmonitor.openapi.yaml -g typescript-fetch -o ./client
The bundled spec covers all 36 services in a single document, so one codegen pass produces typed clients for everything. Prefer a maintained package over codegen? Official SDKs exist for Python, Ruby, Go, and JavaScript.
<Note> One of the 36 — **CompanyMonitoringService** — is published as a contract only. Its operations are not routed yet, so a generated client for them will not receive a response. Every other service in the bundle is live. </Note># 1. Read the server card — this is the canonical descriptor for MCP
curl -s https://worldmonitor.app/.well-known/mcp/server-card.json
# → endpoint (https://worldmonitor.app/mcp), transport, OAuth scopes,
# streaming support, and authorization_servers: ["https://api.worldmonitor.app"]
# 2. Fetch authorization-server metadata from that host
curl -s https://api.worldmonitor.app/.well-known/oauth-authorization-server
# → token / authorize / registration endpoints, PKCE required, etc.
/.well-known/oauth-protected-resource is also available, but its authorization_servers field is derived from the request Host header so each origin (apex, www, api) reports itself — same-origin metadata that satisfies strict MCP scanners. Use the MCP server card for the cross-origin auth-server URL the actual MCP endpoint expects.
Or skip the manual flow entirely — most clients (Claude Desktop, claude.ai, Cursor, MCP Inspector, Claude Code) accept the MCP URL directly and run discovery + OAuth automatically:
https://worldmonitor.app/mcp
See MCP Server for client-specific config snippets.
If you don't want OAuth, REST endpoints and the MCP endpoint accept a user API key or operator-issued enterprise key in X-WorldMonitor-Key:
curl -s https://api.worldmonitor.app/api/resilience/v1/get-resilience-ranking \
-H "X-WorldMonitor-Key: $WM_KEY"
PRO subscribers get a key from worldmonitor.app/pro. See Authentication.
/.well-known/agent-skills/index.json lists pre-packaged skills — each is a self-contained recipe an agent can ingest without reading the OpenAPI. Useful for narrow tasks where you'd rather hand the agent "fetch a country brief" than "read 30 OpenAPI specs and figure it out." See the Agent Skills Catalog for a human-readable list of every recipe. Today's catalog spans 25 installable recipes across country briefs, risk and resilience, chokepoints, markets, cyber, sanctions, aviation, military flights, maritime traffic, energy shocks, trade flows, unrest, webcams, climate hazards, health alerts, and forecasts.
The point isn't novelty — RFCs 8414, 8288, 9727, 9728 are old. The point is that every WorldMonitor surface (REST, MCP, OAuth, skills, LLM briefings) is reachable from one root URL via well-known conventions, with no out-of-band setup. An agent can:
/openapi.yaml and the api-catalog reflect it on the next deploy. No version pinning, no waiting on an SDK release cycle (though official SDKs exist when a maintained package fits better).