MCP
查询入口：https://mcp.vesselmcp.com/mcp。无状态 Streamable HTTP。每次请求新建 server，不发 session。
GET https://mcp.vesselmcp.com/ 是简介页，不鉴权、不查船。/health 也公开可访问；这两个路径均支持 GET 和 HEAD。health 响应只证明该入口可响应，不证明带鉴权的工具查询会成功。对 /mcp 带 Origin 的请求在鉴权前返回 HTTP 403，响应不含 CORS header。不要从浏览器里调工具。
工具
按固定顺序注册两个只读、幂等工具，都只接受 imo：
| 工具 | 作用 |
|---|---|
vesselmcp_get_vessel | 身份 |
vesselmcp_get_recent_ports | 最近靠港，最多 10 条 |
没有搜索、resources、prompts、session 或写操作。字段规则见 约定。
成功时 structuredContent 与 REST 的 data 同形（没有 {data:...} 外包）。另有两段 text：一段摘要，一段同一对象的 JSON。
身份未找到：isError，文本 Vessel not found.。身份其他失败与全部靠港失败：通用 isError 文本，不返回不合格内容。
POST /mcp
Authorization: Bearer vmcp_mcp_v1_<key-id>_<secret>
MCP-Protocol-Version: 2025-11-25
Content-Type: application/json
Accept: application/json, text/event-stream{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "vesselmcp_get_vessel",
"arguments": { "imo": "9331919" }
}
}只接受 vmcp_mcp_v1_... key。API key 不能调用本服务。
协议
支持 2025-06-18 与 2025-11-25，最新为 2025-11-25。initialize 可省略 MCP-Protocol-Version；其后所有非 initialize 的 JSON-RPC 请求、通知和响应必须带受支持版本 header。不支持的版本 header 返回 HTTP 400。initialize 的 protocolVersion 若不是上述二者，协商为 2025-11-25。notifications/initialized 返回 202 空正文，不创建 session。每个 POST /mcp 都必须在 Accept 中同时列出 application/json 与 text/event-stream；否则 transport 返回 HTTP 406。Content-Type 必须是 application/json，否则 transport 返回 HTTP 415。Worker 先鉴权、限流并准备 JSON-RPC 正文，因此解析或协议版本失败会先返回 HTTP 400，即使 Accept 同时也缺。
每个请求必须是单个 JSON-RPC 对象，正文最大 16 KiB。拒绝 batch。JSON／UTF-8 解析失败返回 -32700；结构不合法返回 -32600。
限流
先按请求方 IP，鉴权成功后再按非敏感 key ID。限额按 Cloudflare location 计。initialize、tools/list、tools/call 各计一次。
| 阶段 | 限额 |
|---|---|
| 鉴权前，按 IP | 每 60 秒 30 次 |
| 鉴权后，按 key ID | 每 60 秒 20 次 |
超限返回 HTTP 429、JSON-RPC -32002 与 Retry-After: 60。
错误
除公开的 GET/HEAD /、/health 外，校验顺序为：拒绝 /mcp 上的 Origin、IP 限流、鉴权、key ID 限流、精确路径且无 query 参数、HTTP 方法，最后进行协议和正文校验。下表中的路由错误以已通过前置阶段为前提；未鉴权请求访问未知路径通常先返回 401，不是 404。Accept 与 Content-Type 在正文准备之后由 transport 检查。
| HTTP | JSON-RPC error.code | 何时 |
|---|---|---|
| 403 | -32003 | 存在 Origin |
| 401 | -32001 | 缺少或无效 MCP key |
| 429 | -32002 | 超限 |
| 503 | -32000 | 服务暂时不可用 |
| 404 | -32601 | 未知路径，或 /mcp 带 query 参数 |
| 405 | -32600 | 精确的 /mcp 路径且无 query 参数，但方法不是 POST |
| 406 | -32000 | Accept 未同时接受 application/json 与 text/event-stream |
| 415 | -32000 | Content-Type 不是 application/json |
| 400 | -32700 | JSON／UTF-8 解析失败或空正文 |
| 400 | -32600 | 非法 JSON-RPC、batch、不支持的协议版本、超长正文 |
| 500 | -32603 | 未归类内部错误 |