WorldMonitor MCP 服务器：接入 Claude 与 Cursor

​

端点

​

协议协商

• 默认情况下，initialize 同时支持 2025-03-26 和 2025-06-18。
• 请求 2025-06-18 的客户端会得到 2025-06-18；固定使用 2025-03-26 的客户端继续得到 2025-03-26。
• 设置 MCP_PROTOCOL_FLOOR_2025_06_18=off 会将服务器固定回仅支持 2025-03-26 的旧版底线；此后请求 2025-06-18 的客户端会收到安全默认值 2025-03-26。

​

Streamable HTTP 响应

• 在 Accept 中省略 text/event-stream 的客户端会收到标准的 JSON-RPC JSON 响应体。
• 发送 Accept: application/json, text/event-stream 的客户端在 JSON-RPC POST 成功时可收到 text/event-stream 响应。
• initialize 的 SSE 响应包含 Mcp-Session-Id；后续的 POST 应发送相同的 Mcp-Session-Id 头。
• 每个 SSE 响应以带有事件 id 的单个 message 事件承载 JSON-RPC 结果。不存在开头的空预热事件 —— 根据 WHATWG SSE 规范，空的 data: 字段仍会派发一个 message（其 data === ""），这会导致严格的握手扫描器在 JSON.parse("") 上失败。
• 如果客户端在唯一的那个事件之后断开连接，可以通过发送带有 Accept: text/event-stream、相同 Mcp-Session-Id 和 Last-Event-ID 的 GET /mcp 来重新连接；在已投递的事件之后恢复会返回一个空流。在收到该事件之前就断开的客户端没有已确认的 Last-Event-ID，因此会改为重新发起该 POST。
• **带有 Accept: text/event-stream 但不带 Last-Event-ID 的 GET /mcp**表示客户端尝试打开可选的服务器→客户端独立 SSE 流。这条无状态 edge 路由不提供服务器发起的流，因此返回 405 Method Not Allowed（并声明 Allow）；MCP SDK 会将其作为“无独立流”的正常信号处理。
• 浏览器式的普通 GET /mcp —— 既无 SSE Accept，也无 Last-Event-ID —— 返回 200 和人类/agent 可读的 markdown 服务器指南（与 /mcp-server.md 相同）。普通 HEAD /mcp 采用同一路由，只省略响应体。

​

认证

1. OAuth 2.1 bearer —— Authorization: Bearer <token>，其中 <token> 由 /api/oauth/token 颁发。这是 Claude Desktop、claude.ai、Cursor 和 MCP Inspector 自动使用的方式。任何从浏览器源访问 MCP 的客户端都必须使用此方式。
2. 直接 API key —— 对于用户颁发的 key 使用 X-WorldMonitor-Key: wm_0123456789abcdef0123456789abcdef01234567，或使用由运营方颁发的不透明企业 key。适用于服务端脚本、curl 和自定义集成。不要把 API key 当作 Bearer token 发送 —— 它会通过 OAuth 解析失败并返回 401 invalid_token。

​

Redirect URI 允许列表

• https://claude.ai/api/mcp/auth_callback
• https://claude.com/api/mcp/auth_callback
• http://localhost:<port> / http://127.0.0.1:<port>（任意端口） —— 适用于 Claude Code、MCP Inspector、本地开发

​

Token 生命周期

​

Pro 登录流程

1. 在 MCP 客户端中添加服务器 URL。规范入口为：
   https://api.worldmonitor.app/mcp
   
   （https://worldmonitor.app/mcp 也可用 —— 它代理同一个 handler。）
2. 在授权页点击 “Sign in with WorldMonitor Pro”。这是默认 CTA。你会跳转到 worldmonitor.app/mcp-grant（受 Clerk 保护 —— 如需登录请先登录），然后回到 api.worldmonitor.app/oauth/authorize-pro，最后跳转到你客户端的 redirect。
3. 完成。 你的机器上不会创建或存储任何 wm_… key。客户端会收到一个标准 OAuth 2.1 access token（1 小时 TTL，7 天 refresh）。

​

每日额度（Pro 套餐）

• 每个 UTC 日 50 次消耗配额的调用，在 UTC 00:00 重置。
• 承载数据的 tools/call 以及对承载数据的 URI 模板实例化的 resources/read 会消耗 Pro 每日配额，get_sources 和元数据辅助工具 describe_tool 除外。
• initialize、tools/list、prompts/list、prompts/get、resources/list、resources/templates/list、logging/setLevel、notifications/initialized、ping、describe_tool 和 get_sources 不计入每日上限。对公开资源的 resources/read（仅含元数据的新鲜度/健康探针，例如 worldmonitor://seed-meta/freshness）同样豁免 —— 它不承载任何可计费的数据。
• 达到上限会返回 JSON-RPC 错误 -32029 以及 HTTP 429，并附带指向下一个 UTC 午夜的 Retry-After 头。
• 该上限是硬性限制：接近边界时的并发 tools/call 或 resources/read 请求使用原子 Redis 预留，因此恰好跨越 50 的那次调用会被拒绝。

​

已连接的 MCP 客户端

• 在 Settings → Connected MCP clients 管理已连接的客户端。
• 可查看每个 token 的实时 clientName（例如 “Claude”、“Cursor”）、lastUsedAt 和 createdAt。
• 撤销会在下一次 MCP 请求时生效（无正向缓存）。
• 每个用户最多 5 个活跃 token。超出上限的授权会静默撤销创建时间最早的现有 token（按创建顺序，而非最近使用时间；并发授权下的执行是最终一致的）。

​

套餐与限制

​

其他速率限制

• OAuth authorize：10 次请求 / 分钟 / IP
• OAuth token：10 次请求 / 分钟 / IP
• 动态注册：5 次注册 / 分钟 / IP

​

客户端配置

​

Claude Desktop

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

​

Claude web (claude.ai)

• 名称：WorldMonitor
• URL：https://worldmonitor.app/mcp

​

Cursor

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

​

MCP Inspector（调试）

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

​

工具目录

​

市场与经济

​

能源

​

地缘与安全

​

NLP 实用工具（按需）

​

历史情报

​

移动与基础设施

​

环境与科学

​

健康

​

人道主义与流离失所

​

AI 情报

​

API 覆盖

./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs

1. 从 OpenAPI 页面复制确切的方法和路径，例如 GET /api/research/v1/list-tech-events。
2. 搜索此表。如果该路由出现，则调用所列的 MCP 工具。
3. 如果它未出现，则该 REST 路由未作为 API 等价路径通过 MCP 暴露。仅缓存的 MCP 工具可能仍返回相关领域数据，但它并不声称覆盖该 REST 路由。
4. 如需代码级验证，请在 api/mcp/registry/cache-tools.ts 和 api/mcp/registry/rpc-tools.ts 中搜索 _apiPaths；parity 测试会解释有意的仅限 REST 排除项。

• 缓存支撑的 bootstrap 聚合 —— 读取由 Railway cron 直接填充的 Redis key（例如 get_aviation_status、get_cyber_threats、get_country_macro，以及三个 EU Eurostat 工具）。
• 种子合成快照 —— get_world_brief 通过仪表板 bootstrap 路径读取已接受的 news:insights:v1 payload；没有直接 REST 等价操作，也不会在请求时调用 LLM。
• 静态内存注册表 —— 过滤随 MCP 服务器 edge 二进制文件一起打包的一个常量，完全无需上游调用（例如 get_commodity_geo）。
• 没有公共 OpenAPI 行的实时工具 —— 运行时代理一次 HTTP 调用，其方法偏离公共规范，由一个同类工具覆盖规范声明的方法（例如 generate_forecasts 以 POST 方式请求 /api/forecast/v1/get-forecasts，而 get_forecast_predictions 拥有该 GET）。

• mutating —— 写入、队列、webhook、缓存刷新或持久化副作用。示例：GET /api/aviation/v1/list-airport-delays 有意仅限 REST，因为其 GET handler 会刷新/持久化机场延误缓存状态；get_aviation_status 转而暴露已填充的缓存支撑快照。
• llm-passthrough —— 每次调用直接进行的 LLM 工作，在通过 MCP 暴露之前需要专门设计的成本/威胁模型。
• fetch-on-miss —— 在缓存为冷时可能调用付费或受限流的上游，或接受不适合缓存打包的高基数标识符。排除原因必须包含一个强制的次要信号：high-cardinality-input、paid-upstream 或 llm-cost。示例：GET /api/conflict/v1/list-acled-events、GET /api/infrastructure/v1/list-service-statuses、GET /api/supply-chain/v1/get-critical-minerals 以及 GET /api/aviation/v1/get-flight-status。
• admin —— 位于明确管理员边界之后的仅限内部操作，例如管理员 key、仅限内部的中间件或仅限 cron 的路径。
• manual-mapping —— 参数化的缓存 key 或内联的 Redis/Convex handler 需要人工分诊。示例：GET /api/research/v1/list-arxiv-papers、GET /api/research/v1/list-trending-repos 以及 GET /api/research/v1/list-hackernews-items；get_research_signals 仅声明 GET /api/research/v1/list-tech-events。
• deferred-to-future-tool —— 其缓存 key 尚未被某个 MCP bundle 暴露的纯读取。示例：GET /api/cyber/v1/list-cyber-threats 计划用于未来的扩展领域工具，而非由如今缓存支撑的 get_cyber_threats 认领。

• #4525 —— 延后的纯读取 MCP 覆盖候选项。
• #4526 —— 手动映射和 fetch-on-miss 分诊。

​

Prompt 与资源

​

Prompt

​

资源

​

MCP Apps（交互式 UI）

• initialize 在握手中声明支持。响应的 capabilities.extensions 会命名该扩展：{"io.modelcontextprotocol/ui": {}}。这是宿主（或 agent 就绪性扫描器）读取以将该端点归类为 MCP App 界面的协商信号 —— 下方的 tools/list 和 resources/list 条目就是它随后渲染的内容。
• tools/list 在工具上声明这种关联。每个关联了 UI 的工具都携带指向其 UI 资源的 _meta.ui.resourceUri（以及已弃用的扁平别名 ui/resourceUri）。
• resources/list 暴露 UI 资源本身，以及具体的数据资源（参数化的数据模板位于 resources/templates/list）：

​

JSON-RPC 示例

WM_KEY="wm_0123456789abcdef0123456789abcdef01234567"

# 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":{"country_code":"IR"}}
  }'

​

响应结构

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{...json payload...}" }
    ],
    "isError": false
  }
}

​

数据新鲜度

​

错误

• 401 + -32001 携带一个 WWW-Authenticate 头，其 resource_metadata 指向 /.well-known/oauth-protected-resource。支持 RFC 9728 的客户端会在此头上自动重新运行 OAuth 流程。
• 403 + -32002 是已经发出的终止性权益拒绝。lapsed-subscription 只会在罕见竞态中出现：服务方确认的失效在 Pro 调用预检查通过后、执行中途才落地；若预检查时已经确认覆盖期结束，OAuth 身份会改走受限、按额度计量的 free_account 路径。upgrade-required 表示免费账户调用了订阅工具，或不具备免费账户资格的非免费权益不足。该错误不携带 WWW-Authenticate，重新运行 OAuth 无法修复这一次已经发出的拒绝。
• 429 + -32029 是 Pro 每日上限（Retry-After: <距离 UTC 午夜的秒数>）。每分钟速率限制在 HTTP 200 内返回 -32029，而不是 429 —— 区别请见错误目录。
• Soft envelope 返回 HTTP 200 且没有 JSON-RPC error 字段 —— 仅检查 JSON-RPC 层的客户端会静默地将它们视为成功。务必解析 result.content[0].text 并在将 payload 当作数据消费前检查带前导下划线的判别 key（_budget_exceeded、_jmespath_error）。

​

相关

• WebMCP —— 操作可见 WorldMonitor 网站的实验性、标签页绑定工具
• MCP 快速入门 —— 五分钟从零到首次调用的演练
• JMESPath 指南 —— 投影语法 + 12 个实例
• MCP 工具参考 —— 各工具参数和 curl 示例
• MCP 错误目录 —— 服务器发出的每个 JSON-RPC 错误码、HTTP 状态和 soft envelope
• 认证概览 —— 浏览器 vs bearer vs OAuth
• API 参考 —— 通过 REST 获取同样的数据
• Pro 功能