DataCore A2A

DataCore A2A — MCP 服务

English · Tiếng Việt

让 MCP 客户端（Claude Code、Claude Desktop、VS Code、Cursor……）将 DataCore 的 数据技能用作原生工具：规范化越南地址、验证地址、查询公司、生成嵌入向量。

MCP client (stdio) ──► datacore-mcp ──HTTPS──► DataCore gateway

零依赖，支持 Python 3.9 及更高版本。

快速开始

此服务是客户端，而非服务端。它需要 DataCore 端点和用于调用该端点的 凭据。缺少其中任意一项时，它会启动、提示缺少哪个变量，然后退出。

你需要先拥有 datacore.vn 账户。

1. 安装

pip install datacore-a2a-mcp

如果你在该项目尚未发布时从 GitHub 安装，--upgrade 不会将你升级到 PyPI 版本——请先卸载，再重新安装。

2. 获取会话令牌

登录 datacore.vn，然后从对 gateway.datacore.vn 的任意一次调用中复制 token 请求 标头（开发者工具 → 网络）。共 64 个十六进制字符。

没有对应的 curl 命令：POST /auth/login 会对密码进行 RSA 解密，且没有端点公开公钥，因此只有 Web 应用才能完成登录。之后可通过凭据页面省去此步骤。

忽略同一次登录返回的 jwt——网关会以 409 拒绝客户端提供的 Authorization；它接受的标头是 token。

3. 创建凭据

curl -s -X POST https://gateway.datacore.vn/mcp/credentials \
  -H "token: <64-character token>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"claude-code"}' | jq .

返回 201，并附带凭据，其中包括 api_key、key_prefix、allowed_skills、 spend_cap_vnd 和 quota_period。

请立即复制 api_key——它只会返回一次。系统只存储哈希，因此无法再读取该值。若丢失，请创建新的凭据。

此处返回 409 表示你已持有最多 3 个有效凭据。请先撤销一个（参见 配额与限制）。

4. 在客户端中声明凭据

参见下方的 配置。

步骤 2–3 目前还没有 Web 界面；请使用 curl。管理页面上线后，这些命令仍然可用。

配额与限制

免费套餐	每个凭据每月可消费 500,000 VND
每次调用的价格	默认 500 VND，约可调用 1,000 次
重置时间	每月 1 日，Asia/Ho_Chi_Minh
凭据数量	每个账户最多 3 个有效凭据
凭据有效期	90 天
令牌签发频率	每个凭据每分钟最多 10 次交换

额度按凭据而非账户计算——三个凭据就为一个账户提供三份独立额度。服务以 VND 而非调用次数计量，以便日后引入按技能定价时，无需重写已存储的额度上限。

凭据不绑定机器或 IP，因此同一个密钥可以在另一台计算机上使用——两台设备共用同一份配额，撤销密钥则会同时使两台设备无法使用。

查看凭据的消费情况并撤销凭据：

curl -s https://gateway.datacore.vn/mcp/credentials/<id>/usage -H "token: <token>" | jq .
curl -s https://gateway.datacore.vn/mcp/credentials -H "token: <token>" | jq .
curl -X DELETE https://gateway.datacore.vn/mcp/credentials/<id> -H "token: <token>"

/usage 会报告 spent_vnd、spend_cap_vnd、quota_period 和 resets_at。 撤销成功时返回 204；若 ID 不属于你，则返回 404——这两种情况会刻意保持不可区分。

配置

变量	必填	含义
DATACORE_A2A_URL	是	DataCore 网关的基础 URL — https://gateway.datacore.vn，除非你获得了自己的端点
DATACORE_API_KEY	是¹	长期凭据，格式为 dck_<prefix>_<secret>。服务会用它换取短期授权，并自行刷新
DATACORE_MANDATE	是¹	手动签发的 AP2 授权。仅适用于按旧方式配置的调用方 — 见下文
DATACORE_SKILLS	否	用逗号分隔的技能 ID，用于缩小工具列表范围；也可以用 * 表示端点返回的所有内容。留空时使用默认的四项
DATACORE_TIMEOUT	否	每次请求的超时时间（秒），默认为 30

¹ 必须设置其中一个。如果两者都设置，则以 DATACORE_MANDATE 为准。

请使用 DataCore 提供给你的 URL。其他端点无法识别你的凭据，并会返回 401。

为什么应该使用 DATACORE_API_KEY

授权有效期为 15 分钟。使用 DATACORE_API_KEY 时，服务会在当前授权过期前一分钟请求新的授权，因此你永远不必因为令牌过期而编辑配置文件。授权会保留在进程内存中，不会写入任何位置。如果调用仍返回 401，服务会强制刷新一次，并恰好重试一次，然后才报告失败。

DATACORE_MANDATE 仍然可用，但不会刷新 — 它是为凭据推出前已完成配置的用户保留的。授权过期后，你需要手动替换它并重启 MCP 服务。

Claude Code

claude mcp add datacore-a2a -s user \
  -e DATACORE_A2A_URL=https://gateway.datacore.vn \
  -e DATACORE_API_KEY=<YOUR_API_KEY> \
  -- datacore-mcp

将 <YOUR_API_KEY> 替换为第 3 步中的 api_key — 格式类似 dck_<8 hex chars>_<secret>。

-s user 会为每个项目注册它。建议使用此方式，而不是项目范围的 .mcp.json：该文件往往会被提交，而密钥是有效期为 90 天的持有者凭据。

Claude Desktop

将下面的代码块合并到配置中 — 不要替换整个文件，因为其中保存了你的应用偏好设置。

操作系统	配置路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "datacore-a2a": {
      "command": "<PATH_TO_DATACORE_MCP>",
      "env": {
        "DATACORE_A2A_URL": "https://gateway.datacore.vn",
        "DATACORE_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

两个 <...> 值都需要你自行填写 — JSON 不支持注释，因此文件中不会有任何提示：

占位符	来源
<PATH_TO_DATACORE_MCP>	which datacore-mcp（macOS/Linux）或 where datacore-mcp（Windows）的输出。类似 /home/you/.local/bin/datacore-mcp 或 C:\Users\you\AppData\Roaming\Python\Scripts\datacore-mcp.exe
<YOUR_API_KEY>	第 3 步中的 api_key，格式为 dck_<8 hex chars>_<secret>

必须使用绝对路径：桌面应用不会继承你的 shell PATH，因此通常无法通过裸命令名启动。也可以使用 python -m datacore_mcp.server。然后彻底退出应用 — 仅关闭窗口是不够的。

日志会写入 stderr，应用会将其保存在该配置文件旁边的 logs/ 目录中。

工具

工具列表由端点生成，而不是在此处硬编码。因此，DataCore 添加技能后，只需重启服务即可看到新工具。

默认情况下会公开五项技能，即已连接到真实后端的技能：

工具	技能 ID	功能
address_normalize	address.normalize	将越南地址标准化为省／县／坊
address_validate	address.validate	根据行政区划数据检查地址
company_search	company.search	按名称或税号查询公司
company_graph	company.graph	返回公司的关系信息，包括代表、省份、行业以及图谱中包含的其他信息
company_embeddings	company.embeddings	为一段文本生成嵌入向量

每项工具都接受一个必需参数 text，其值为自由文本字符串；不接受其他属性。所有工具均为只读（readOnlyHint: true）：不会写入、删除或创建任何内容，且相同输入会得到相同结果。

DataCore 的另外两项技能（company.financial-sankey、company.news）有意不予公开：它们目前返回的是模拟／确定性数据。将 DATACORE_SKILLS="*" 设置为工具后，虽然会列出这些技能，但免费套餐凭据无法调用它们——其允许列表仅包含上述五项技能，因此每次调用都会返回 403。创建凭据时请求额外技能也不会报错；请求会被静默缩减为这五项技能。

company.graph 以前就在该列表中。现在它会读取真实关系，因此在此版本发布前创建的凭据不包含它——签发凭据时会将允许的技能写入其中。请创建新凭据以使用该技能。

示例

以下三个提示词分别调用三种不同的工具：

1. 标准化地址——“将此地址标准化为省／县／坊：So 1 Ly Thai To, Hoan Kiem, Ha Noi”
2. 公司查询——“查找税号为 0100109106 的公司，并告诉我它是否仍在运营”
3. 嵌入向量——“为此业务范围生成嵌入向量，并告诉我该向量有多少个维度：电子设备批发”

安全模型

此服务会在 X-AP2-Mandate 标头中原样传递授权委托，供 DataCore 验证，并且不声明自己的授权标头。客户端无权自行授权——它只会转发收到的内容，所有允许或拒绝的决定都由 DataCore 作出。

用于兑换授权委托的 API 密钥通过 X-Datacore-Credential 传递，而不是通过 Authorization 传递。DataCore 的网关会保留 Authorization 供自己使用——它会在对调用方进行身份验证后签署并注入该标头，因此任何携带此标头的请求都会被拒绝，并返回 409 和空响应体。如果你手动调用 /mandate/issue，并收到没有消息的 409，原因就在这里。

API 密钥是一种持有者凭据：任何持有它的人都可以用它兑换授权委托，并在额度用尽前调用授权委托允许的技能。请像对待密码一样处理它——不要提交已填入密钥的 .mcp.json；如果客户端支持，请从密钥管理器读取密钥，而不是直接写入配置。如果密钥泄露，请立即通过 DELETE /mcp/credentials/<id> 撤销它（参见配额和限制）；由此签发的授权委托仍会继续生效 15 分钟，因为没有即时撤销列表。

授权委托则恰恰相反：有效期为 15 分钟，仅存于进程内存中。它不会写入磁盘，也不会被记录到日志中，你也不应该需要查看它。

每个凭据每分钟最多可兑换 10 次，以此限制签发频率，防止利用该端点遍历密钥空间。所有拒绝请求的情况——未知密钥、已撤销密钥、过期密钥、密钥错误——都会返回相同原因的 401 消息。

此软件包绝不会记录令牌，哪怕是部分内容；也绝不会记录你发送的 text。这项承诺仅适用于在你机器上运行的进程——服务端是另一回事，PRIVACY.md 会明确说明它存储了什么。

故障排除

日志输出到 stderr，并以 [datacore-mcp] 为前缀。stdout 是 JSON-RPC 通道。

症状	常见原因
立即退出，显示 MISSING required environment variable	未设置 DATACORE_A2A_URL
立即退出，显示 MISSING authentication	未设置 DATACORE_API_KEY 或 DATACORE_MANDATE
DATACORE_API_KEY 看起来被忽略	你使用的是 0.1.0，该版本早于凭据功能，且只读取 DATACORE_MANDATE。请升级：pip install -U datacore-a2a-mcp
所有请求都返回 401	凭据已撤销、已超过 90 天，或 DATACORE_A2A_URL 不是签发该凭据的端点。若使用 DATACORE_MANDATE：授权委托已过期，且不会刷新。这些情况故意使用同一条消息，以免有人利用该端点探测有效密钥。若要区分，请调用 GET /mcp/credentials，查看你的凭据是否仍为 ACTIVE
手动调用 /mandate/issue 时返回 409	你把密钥放进了 Authorization。密钥应放在 X-Datacore-Credential 中。软件包会正确处理；只有手动调用时才会遇到此问题
创建凭据时返回 409	你已经持有 3 个有效凭据。请先撤销一个
429	单个凭据每分钟兑换授权委托超过 10 次。软件包每小时大约刷新 4 次，因此这表示某处陷入了循环
402	该凭据本月的额度已用尽。额度会在每月 1 日重置
403	此技能不在凭据的允许列表中——免费层仅涵盖上述 4 项技能，且无法扩大此范围
400	请求格式错误，或该技能 ID 未在端点注册
404	路由不存在——请检查 DATACORE_A2A_URL
502 / 503	此技能后端没有响应
完全没有工具	DATACORE_SKILLS 过滤掉了所有工具，或该端点没有注册任何技能

报告安全问题

[email protected]。请勿为安全漏洞创建公开问题。

如果你认为凭据已泄露，请立即报告——不要等到它过期。我们需要了解情况，以便在服务端采取行动。

隐私

请参阅 PRIVACY.md。 简而言之：此软件包在你的计算机上运行，不存储任何内容，不会向任何地方发送数据（你配置的 DataCore 端点除外），并且绝不会将 mandate 令牌写入日志。

许可证

MIT——请参阅 LICENSE。