MCP 接入

MCP 端点

传输为 MCP Streamable HTTP（单端点 JSON-RPC 2.0）。鉴权与 REST 共用：在 HTTP 头携带 X-API-Key，配额/限流/计费完全一致。

https://api.sports.csap.ai/mcp (HTTP · X-API-Key)

Claude Code（CLI）接入

一条命令把本平台加为 HTTP MCP 服务，把 YOUR_KEY 换成你的 API Key：

claude mcp add --transport http football-data https://api.sports.csap.ai/mcp \--header "X-API-Key: YOUR_KEY"

Claude Desktop / Cursor 等客户端接入

在客户端的 MCP 配置文件（如 mcp.json）中加入下面这段，把 YOUR_KEY 换成你的 API Key：

{ "mcpServers": { "football-data": { "type": "http", "url": "https://api.sports.csap.ai/mcp", "headers": { "X-API-Key": "YOUR_KEY" } } } }

提供的工具

默认「紧凑模式」用 4 个通用工具覆盖全部接口（AI 自动三步取数）；服务端设 MCP_EXPOSE_ALL_TOOLS=1 可额外为每个接口生成一等命名工具。

• list_interfaces — 列出/搜索全部数据接口目录（短名、摘要、标签、字段数）
• describe_interface — 返回某接口的请求参数与层级字段树
• query_interface — 查询某接口真实数据，支持 id 游标翻页 / time 增量，**并可按 team_id/player_id/match_id/competition/season_id/date/live 等实体维度任意组合过滤**（filters 支持任意真实列）
• live_now — 一步返回此刻进行中的比赛比分板（服务端已按状态过滤，可按联赛筛选）
• platform_info — 平台总览、计费、翻页与实时接入说明

资源与提示

每个接口的字段文档同时暴露为 MCP 资源（interface://短名，可浏览不进上下文）；另提供 explore_catalog / incremental_sync 两个引导提示（prompts）。

调用示例（JSON-RPC）

MCP 客户端会自动收发下面这种 JSON-RPC，你通常无需手写；了解底层协议时可参考。下例用 live_now 查当前进行中的比赛：

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "live_now", "arguments": { "competition": "Premier" } } }

{ "jsonrpc": "2.0", "id": 1, "result": { "content": [{ "type": "text", "text": "{ \"count\": 1, \"matches\": [{ \"league\": \"Premier League\", \"home_team\": \"Arsenal\", \"home_score\": 2, \"away_score\": 1, \"minute\": \"67'\" } ] }\" }] } }

AI 取数三步

接入后无需记接口，直接对 AI 说需求即可，它会自动：list_interfaces 找接口 → describe_interface 看字段 → query_interface 取数据。问「现在哪些比赛在踢」时它直接用 live_now 一步拿到当前比分板。

实时数据：拉 + 推，配合使用

MCP 适合 AI 在一次对话里「拉」:用 live_now 一步拿到当前进行中比赛的比分板(服务端已过滤,只回正在踢的)。需要持续「推」(App、大屏、常驻服务)时,用同一个 API Key 换一次性票据连接 WebSocket /ws,按频道、比赛或联赛订阅,即可持续收到比分、事件和赔率的变动。两者互补、同一把 key。

// 在你的服务端:用 key 换一次性票据(60 秒内有效,只能用一次)const r = await fetch("https://api.sports.csap.ai/api/v1/realtime/ticket", { method: "POST", headers: { "X-API-Key": "YOUR_KEY" } }) const { data } = await r.json() // 初始订阅写在地址上;之后可以发 set / subscribe 改订阅const ws = new WebSocket("wss://api.sports.csap.ai" + data.ws_url + "&channels=match,incident") ws.onmessage = (ev) => console.log("realtime:", JSON.parse(ev.data))

说明:MCP 工具覆盖 REST 快照与历史数据,含 live_now 当前比分板;逐场比分、事件和赔率的持续推送走 WebSocket /ws(先换票据,key 不出现在地址里)。 实时推送:WebSocket / SSE / MQTT 接入与试连 →