Agent Discovery

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 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?compact=1>; 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/mcp/docs-server-card.json>; rel="mcp-server-card"; anchor="/docs/mcp",
      </.well-known/agent-skills/index.json>; rel="agent-skills-index"; type="application/json"

Discovery endpoints

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	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`	Policy	Static markdown REST compatibility, deprecation, and sunset contract (RFC 9745 `Link rel="deprecation"`)
`/docs/api-versioning`	Policy	HTML twin of the same 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/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`	A2A	Agent card for the `/a2a` JSON-RPC concierge (see below) — transport, protocol version, skills, no auth required
`/.well-known/http-message-signatures-directory`	RFC 9421 / 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`	(custom)	Index of pre-packaged agent skills (`fetch-country-brief`, `fetch-resilience-score`, …) — each skill is a self-contained recipe
`/plugin.json`	Agent Plugins 1.0.0	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`	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, /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-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).

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 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 — `<any-page>.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: <sibling>; 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

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

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

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:

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.

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 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 exist when a maintained package fits better).

MCP Server — full client setup (Claude Desktop, Cursor, claude.ai, MCP Inspector, Claude Code)
WebMCP — experimental tools discovered from the current browser page, not through the MCP server card
Agent Skills Catalog — human-readable catalog of the public agent recipes
API Reference — human-readable service catalog and MCP→REST tool mapping
API versioning and deprecation — compatibility guarantees and retirement signals (static markdown)
Authentication — browser, API key, and OAuth modes
Quickstart — first call in under a minute

Getting Started

Usage

Platform & Features

Intelligence & Analysis

Workflows

Map Layers

Finance

Panels — AI & PRO

Panels — Data & Tracking

Panels — Catalogues

Desktop Application

MCP & Integrations

HTTP API

Developer Guide

Company

Legal

The one URL to remember

Discovery endpoints

Agent front doors

`GET|POST /ask` — natural-language routing (NLWeb)

`POST /a2a` — A2A JSON-RPC concierge

`GET /agent/auth` — authentication challenge

`/docs/mcp` — documentation MCP server

Markdown twins — `<any-page>.md`

Agent walkthroughs

Codegen a REST client for every service

Connect an MCP client to live data

Server-side with a direct API key

Drop-in agent skills

Why this matters

​The one URL to remember

​Discovery endpoints

​Agent front doors

​GET|POST /ask — natural-language routing (NLWeb)

​POST /a2a — A2A JSON-RPC concierge

​GET /agent/auth — authentication challenge

​/docs/mcp — documentation MCP server

​Markdown twins — <any-page>.md

​Agent walkthroughs

​Codegen a REST client for every service

​Connect an MCP client to live data

​Server-side with a direct API key

​Drop-in agent skills

​Why this matters

​Related

The one URL to remember

Discovery endpoints

Agent front doors

`GET|POST /ask` — natural-language routing (NLWeb)

`POST /a2a` — A2A JSON-RPC concierge

`GET /agent/auth` — authentication challenge

`/docs/mcp` — documentation MCP server

Markdown twins — `<any-page>.md`

Agent walkthroughs

Codegen a REST client for every service

Connect an MCP client to live data

Server-side with a direct API key

Drop-in agent skills

Why this matters

Related