> ## Documentation Index > Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Agent Discovery > Point any AI agent, codegen tool, or MCP client at worldmonitor.app and discover every API, OpenAPI spec, MCP server, and OAuth endpoint from a single root URL. 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/`. ## The one URL to remember ``` https://worldmonitor.app/ ``` The HTTP response carries an [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288) `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. ```bash theme={null} curl -sI https://worldmonitor.app/ | grep -i '^link:' ``` You'll see entries like: ``` Link: ; rel="api-catalog"; type="application/linkset+json", ; rel="service-desc"; type="application/json", ; rel="service-desc"; type="application/vnd.oai.openapi", ; rel="service-doc"; type="text/html", ; rel="status"; type="application/json", ; rel="...oauth-protected-resource", ; rel="...oauth-authorization-server", ; rel="mcp-server-card"; anchor="/mcp", ; rel="mcp-server-card"; anchor="/docs/mcp", ; rel="agent-skills-index"; type="application/json" ``` ## Discovery endpoints | Endpoint | Standard | What it returns | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`/.well-known/api-catalog`](https://worldmonitor.app/.well-known/api-catalog) | [RFC 9727](https://datatracker.ietf.org/doc/html/rfc9727) | JSON linkset bundling every other discovery URL — start here if you want one fetch and a map | | [`/openapi.yaml`](https://www.worldmonitor.app/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`](https://www.worldmonitor.app/openapi.json) | OpenAPI 3.1 | Minified JSON bundle for tooling and scanners that only parse JSON. Same operations, parameters, request bodies and responses as `/openapi.yaml`; shared structures are `$ref`-collapsed and component schemas no operation can reach are omitted, to stay under scanner body caps | | [`/api-versioning.md`](https://www.worldmonitor.app/api-versioning.md) | Policy | Static markdown REST compatibility, deprecation, and sunset contract (RFC 9745 `Link rel="deprecation"`) | | [`/docs/api-versioning`](https://www.worldmonitor.app/docs/api-versioning) | Policy | HTML twin of the same REST compatibility, deprecation notice, and sunset-header contract | | [`/.well-known/mcp/server-card.json`](https://worldmonitor.app/.well-known/mcp/server-card.json) | MCP | Transport (`streamableHttp`), endpoint, OAuth resource, scopes, streaming, capability flags | | [`/.well-known/oauth-authorization-server`](https://api.worldmonitor.app/.well-known/oauth-authorization-server) | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) | OAuth 2.1 authorization-server metadata (PKCE, DCR, token endpoints) | | [`/.well-known/oauth-protected-resource`](https://worldmonitor.app/.well-known/oauth-protected-resource) | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) | Resource metadata for `https://worldmonitor.app/mcp` | | [`/.well-known/mcp/docs-server-card.json`](https://worldmonitor.app/.well-known/mcp/docs-server-card.json) | MCP | Server card for the **documentation** MCP server at `/docs/mcp` (see below) — separate from the data server card above | | [`/.well-known/agent-card.json`](https://worldmonitor.app/.well-known/agent-card.json) | [A2A](https://a2a-protocol.org) | Agent card for the `/a2a` JSON-RPC concierge (see below) — transport, protocol version, skills, no auth required | | [`/.well-known/http-message-signatures-directory`](https://worldmonitor.app/.well-known/http-message-signatures-directory) | [RFC 9421](https://datatracker.ietf.org/doc/html/rfc9421) / Web Bot Auth | Ed25519 public-key directory (`application/http-message-signatures-directory+json`) so third parties can verify WorldMonitor-originated signed automated requests. Keys advertise a rolling 24 h `nbf`/`exp` window; cached `public, max-age=3600` | | [`/.well-known/agent-skills/index.json`](https://worldmonitor.app/.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 | | [`/plugin.json`](https://worldmonitor.app/plugin.json) | [Agent Plugins 1.0.0](https://agent-plugins.org/specification) | Manifest for the World Monitor agent plugin (`name: worldmonitor`). The GitHub repository is the plugin package: root `plugin.json`, `mcp.json`, and regular `skills/*/SKILL.md` files (not git symlinks — Windows checkouts and zip extracts still get YAML frontmatter). Plugin recipes match the well-known catalog except REST examples use the public site origin `https://worldmonitor.app` | | [`/llms.txt`](https://worldmonitor.app/llms.txt) | [llmstxt.org](https://llmstxt.org) | LLM-friendly markdown briefing — overview, capabilities, links | | [`/llms-full.txt`](https://worldmonitor.app/llms-full.txt) | (extension) | Long-form variant covering all data layers, panels, and data sources | | [`/api/health`](https://api.worldmonitor.app/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`, `/plugin.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. ## Agent front doors Beyond static discovery documents, several live endpoints exist specifically for agents. All of them are anonymous and quota-free. `/ask`, `/a2a`, and `/docs/mcp` each enforce their documented 60/min/IP policy; `/agent/auth` and the markdown twins do not claim an endpoint-specific per-IP limit. ### `GET|POST /ask` — natural-language routing (NLWeb) An [NLWeb](https://github.com/microsoft/NLWeb)-style front door: send a question, get back the MCP tools that answer it. Accepts `query` (max 2048 chars) as JSON body, form body, or `?query=`; optional `mode` (default `"list"`), `query_id`, and `streaming` (also triggered by `Accept: text/event-stream`). ```bash theme={null} curl -s https://worldmonitor.app/ask -H 'Content-Type: application/json' \ -d '{"query": "is there unusual military air activity near Taiwan?"}' ``` Returns `{ _meta, query_id, query, results[] }` where each result carries `{url, name, site, score, description, schema_object}` pointing at the matching MCP tool. Streaming mode emits `start` → `result` → `complete` SSE frames. A query-less probe returns `200` with usage guidance rather than an error; when nothing matches, a single `llms.txt` pointer result is returned with `score: 0`. Rate limit: 60/min/IP (`429` + `Retry-After`). Responses are `no-store`. ### `POST /a2a` — A2A JSON-RPC concierge An [A2A protocol](https://a2a-protocol.org) agent (card at `/.well-known/agent-card.json`, protocol `0.3.0`, transport JSONRPC, no auth). Supports `message/send` with text parts (max 2048 chars); replies with an agent message containing a text part plus a data part `{suggestedTools, howToCall, freshness?}` — the freshness envelope attaches when the message asks about staleness or seed health. Streaming, push notifications, and task history are declared unsupported and return `-32004`; rate limiting surfaces as JSON-RPC `-32029` with `Retry-After` (60/min/IP). ### `GET /agent/auth` — authentication challenge Always answers `401` with a `WWW-Authenticate: Bearer realm="worldmonitor", resource_metadata="…"` header and a JSON body linking the RFC 9728 resource metadata, the RFC 8414 authorization-server metadata, and the `/auth.md` skill. It exists because a scanner probing `GET /mcp` for the OAuth challenge can't get one there (that verb is reserved for the SSE handshake) — probe this URL instead to bootstrap the OAuth flow. ### `/docs/mcp` — documentation MCP server A second, separate MCP server for the documentation itself (card at `/.well-known/mcp/docs-server-card.json`, protocol `2025-06-18`, streamable HTTP, no auth). It serves `search_world_monitor` (docs knowledge-base search returning snippets and links) and `query_docs_filesystem_world_monitor` (read-only `rg`/`ls`/`tree`/`cat`/`head` over a virtualized docs + OpenAPI filesystem). POST bodies are capped at 256 KiB (`413` beyond); rate limit 60/min/IP as JSON-RPC `-32029`. It is a conformance-fixing facade over the upstream docs provider: `tools/call` results carrying `-32601`/`-32602` inside `isError` payloads are lifted into real top-level JSON-RPC errors. ### Markdown twins — `.md` Every page on the site has an agent-readable markdown twin: append `.md` to the path (`/pricing.md`, `/countries/tw.md`, `/home.md` for the front page). Curated twins are static and cached `public, max-age=3600` with `Access-Control-Allow-Origin: *`; everything else is rendered on demand by the twin service (HTML becomes heading-led markdown, JSON becomes a fenced block, output capped at 80 KB) with a `Link: ; rel="canonical"` header. `GET`/`HEAD` on `.md` twins bypasses the API bot gate, so plain `curl` works without a browser User-Agent. ## Agent walkthroughs ### Codegen a REST client for every service ```bash theme={null} # 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 the service contracts in a single document, so one codegen pass produces typed clients for everything. Prefer a maintained package over codegen? [Official SDKs](/docs/sdks) exist for Python, Ruby, Go, and JavaScript. 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. ### Connect an MCP client to live data ```bash theme={null} # 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](/docs/mcp-overview) for client-specific config snippets. ### Server-side with a direct API key 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`: ```bash theme={null} 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](https://www.worldmonitor.app/pro). See [Authentication](/docs/usage-auth). ### Drop-in agent skills `/.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 the OpenAPI specs and figure it out." See the [Agent Skills Catalog](/docs/agent-skills) for a human-readable list of every recipe. The catalog spans 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. ## Why this matters 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: * Discover the API without reading our docs. * Authenticate without us telling it which OAuth flow we use. * Pick the right transport (REST vs MCP) based on its own preferences. * Stay current — when we ship a new service, the bundled `/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](/docs/sdks) exist when a maintained package fits better). ## Related * [MCP Server](/docs/mcp-overview) — full client setup (Claude Desktop, Cursor, claude.ai, MCP Inspector, Claude Code) * [WebMCP](/docs/webmcp) — experimental tools discovered from the current browser page, not through the MCP server card * [Agent Skills Catalog](/docs/agent-skills) — human-readable catalog of the public agent recipes * [API Reference](/docs/api-reference) — human-readable service catalog and MCP→REST tool mapping * [API versioning and deprecation](/docs/api-versioning) — compatibility guarantees and retirement signals ([static markdown](https://www.worldmonitor.app/api-versioning.md)) * [Authentication](/docs/usage-auth) — browser, API key, and OAuth modes * [Quickstart](/docs/usage-quickstart) — first call in under a minute