Proof Holdings

@proof-holdings/mcp-server

适用于 proof.holdings API 的 MCP（Model Context Protocol）服务。提供 167 个工具，供 AI Agent 创建验证、校验证明、管理资产等。

两种连接方式

托管版 — 无需安装。 同一组工具通过 HTTP 在 https://api.proof.holdings/mcp 提供服务。任何支持 HTTP 传输的 MCP 客户端或 Agent 框架都可以 连接 — 在设置中将 URL 添加为远程 MCP 服务（配置项名称因客户端而异）。 首次有工具需要使用账户时，会在浏览器中进行身份验证。配置片段如下：

{ "mcpServers": { "proof": { "type": "http", "url": "https://api.proof.holdings/mcp" } } }

⚠️ 1.1.0 之前的版本早于委托工具和无密钥公开模式，提供的功能范围比本 README 所述的旧且小。如果客户端固定使用 1.0.0，请升级它 或使用上述托管服务。GET /api/v1/mcp/connect 始终提供当前说明。

本地版 — 此软件包。 安装并以 stdio 服务运行：

npm install -g @proof-holdings/mcp-server

也可以直接用 npx 运行（无需安装）：

npx @proof-holdings/mcp-server

配置

变量	必填	默认值	说明
PROOF_API_KEY	否	—	API 密钥（pk_live_... 或 pk_test_...）。未设置时，服务仍会以公开模式启动：无密钥工具（账户初始化、登录、证明和委托验证）可用，其他所有工具都会返回 api_key_required。
PROOF_BASE_URL	否	https://api.proof.holdings	API 基础 URL

请从 proof.holdings 控制面板获取 API 密钥，或者让 服务通过 login 命令为你获取一个（见下文）。

在终端登录

npx @proof-holdings/mcp-server login

1. 选择登录方式 — Telegram、WhatsApp、SMS 或电子邮件（通过 --channel 指定，或按提示选择）。终端会显示链接和二维码，可用手机扫描；如果选择 SMS，则会显示要发送的短信内容和号码；如果选择电子邮件，则会提示输入邮件中的验证码。
2. 创建 API 密钥还需要一次确认，最好通过不同的渠道进行；确认也在终端中完成。
3. 新密钥会保存在 ~/.proof-holdings/credentials 中（只有你可读取），并关联到 PROOF_BASE_URL 指定的 API。服务下次启动时会使用该密钥，因此请重启 MCP 客户端的服务。
4. 终端使用的登录会话随后会退出登录。如果退出失败，login 会告知你；请在控制面板的 Settings → Security → Signed-in devices 中退出登录。

设置 PROOF_API_KEY 后，它始终优先于保存的密钥；为某个 API（例如预发布环境）保存的密钥绝不会发送到其他 API。接下来，从客户端配置中移除 env：

{ "mcpServers": { "proof-holdings": { "command": "npx", "args": ["-y", "@proof-holdings/mcp-server"] } } }

命令	功能
login	登录、确认、创建并保存密钥。--test 创建测试密钥（pk_test_）；--scopes a,b 限制密钥权限（默认：完全访问）；--email [email protected] 通过电子邮件登录。
status	显示服务启动时将使用哪个密钥及其来源。不进行网络调用。
logout	从此计算机中移除此 API 的已保存密钥。

密钥不会过期。再次登录会替换已保存的密钥，但不会撤销旧密钥；logout 只会在本地移除密钥：请在控制面板（API keys）中或使用 revoke_api_key 工具撤销不再使用的密钥。login 需要交互式终端，并且 API 必须使用 https://（仅 localhost 可以使用普通 http）。

客户端设置

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "proof-holdings": {
      "command": "npx",
      "args": ["-y", "@proof-holdings/mcp-server"],
      "env": {
        "PROOF_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

各客户端的配置文件位置：

客户端	配置文件
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Cursor	项目根目录中的 .cursor/mcp.json
Claude Code	运行 claude mcp add proof-holdings -- npx -y @proof-holdings/mcp-server
Windsurf	~/.codeium/windsurf/mcp_config.json

即使全局安装后，也请保留带作用域的 npx -y @proof-holdings/mcp-server 命令。单独的命令名称会通过 PATH 查找，或由 npx 在 npm 注册表中查找，而该名称可能属于他人的软件包。

工具（167 个工具）

各组的工具总数准确无误。下表列出了你最可能用到的工具，而非全部工具；MCP 客户端自己的 tools/list 才是完整且最新的列表，服务也会以此为准。

验证与请求（28 个工具）

工具	说明
create_verification	创建验证挑战
get_verification	获取验证状态
submit_verification_code	提交验证码
trigger_verification	触发验证检查
wait_for_verification	轮询，直到验证完成
create_multi_channel_verification	一个电话号码，最多使用三个渠道，以最先完成的渠道为准
create_verification_request	创建多资产请求
get_request_by_reference	根据引用 ID 查找请求

域名与 DNS（23 个工具）

工具	说明
add_domain	添加要验证的域名
verify_domain	检查挑战记录并生成证明
connect_cloudflare	连接 Cloudflare，由系统代为写入记录
verify_domain_with_credentials	使用已存储的凭据证明控制权
setup_domain_email	设置从该域名发送邮件

账户、设置与账单（37 个工具）

工具	说明
get_platform_summary	一次调用即可获取账户概况
get_usage	获取当前周期的配额和用量
search	搜索整个账户
create_account	初始化新账户（无需密钥）
create_api_key	创建有作用域限制的 API 密钥
list_assets	列出已验证的资产及其证明句柄

HITL 审批与同意（22 个工具）

工具	说明
create_hitl	创建人工审批配置
create_confirmation	向某人发送审批请求
wait_for_confirmation	轮询，直到某人批准或拒绝
create_authorization	请求某人同意接受联系
revoke_authorization	撤回同意

圈子与 Proof of Me（15 个工具）

工具	说明
create_circle	创建可信联系人圈子
add_circle_member	添加联系人
invite_circle_member	发送一次性注册链接
create_identity_challenge	执行跨渠道身份验证

公开个人资料（12 个工具）

工具	说明
create_profile	创建公开个人资料
claim_username	认领公开用户名
update_public_proofs	选择个人资料要展示的证明

模板与 Webhook（11 个工具）

工具	说明
list_templates	列出项目的消息模板
render_template	使用变量渲染模板
list_webhook_deliveries	列出 Webhook 投递记录
retry_webhook_delivery	重试失败的投递

委托与证明（10 个工具）

工具	说明
create_delegation	授权来自你已证明其所有权的域名的制品
revoke_delegation	撤销委托
verify_delegation	检查某个制品是否经其声称所属的域名授权
validate_proof	验证已签名的证明令牌（无需密钥）
get_proof_status	通过证明的公开句柄读取其状态
list_revoked_proofs	读取撤销列表（无需密钥）

登录与会话（9 个工具）

工具	说明
start_login	开始登录（无需密钥）
wait_for_login	轮询，直到登录完成
get_current_user	查看当前会话所属用户
render_auth_link	生成供用户打开的登录链接

测试模式

使用测试模式 API 密钥（pk_test_*）与 API 交互，而不会创建真实的验证。可在你的控制面板中获取测试模式密钥。

传输方式

此包提供两种传输方式：

• stdio（默认，即运行 npx -y @proof-holdings/mcp-server 时启动的方式）——服务通过 stdin/stdout 通信。每个进程对应一个用户；这是客户端在本地启动的方式。
• Streamable HTTP（node dist/remote.js）——一种远程服务，许多用户可通过 URL 在网络上连接，无需安装。连接开始时处于匿名状态——无需任何凭据即可使用无密钥功能（账户初始化、登录、证明和委托验证）；需要账户的工具会返回 401，并附带一个 WWW-Authenticate 挑战，指出授权服务，符合标准的客户端会据此进行登录。401 会出现在工具调用上，而不会出现在匿名连接的纯 initialize 或 tools/list 请求上：根据真实客户端的测试结果，拒绝匿名握手对用户来说会像连接超时，而不是登录提示。只有以下三种情况会在握手时遭到拒绝：提供的令牌无法解析（此时 401 会促使客户端刷新令牌）、请求所带凭据与其指定的会话不匹配，以及初始批处理中夹带了带密钥的工具调用和 initialize。已登录的客户端会在 Authorization 标头中发送获发的 API 密钥——凭据只会从此处读取，绝不会从查询参数读取——且每个连接都有独立的服务和 HTTP 客户端，因此一个用户的密钥或会话绝不会泄露给其他用户。/mcp 支持 POST（每条 JSON-RPC 消息）和 DELETE（结束会话）；其他所有方法——包括可选的独立 GET 事件流——无论请求携带何种会话或凭据，都会返回 405 和 Allow: POST, DELETE。此服务不会推送通知，因此不使用事件流对客户端没有任何影响；这也使使用 Node 26 内置 fetch 的客户端能够正常工作：通过 HTTP/2 连接到边缘节点时，如果事件流保持打开，它就不会发送下一个请求。PORT（默认值为 3100）、MCP_MAX_SESSIONS（默认值为 100）、MCP_SESSION_TTL_MS（默认值为 30 min，从服务接受的最后一次 POST 开始计时——即响应状态码低于 400 的请求。服务在开始处理前拒绝的 POST 不会延长 TTL，无论拒绝原因是服务自身的限制（请求正文超过 4MB），还是传输层的问题（正文无法解析或为空、不支持的 mcp-protocol-version、第二次 initialize）；遭拒绝的方法也不会延长 TTL。官方客户端不会自行从会话清理中恢复：根据对 SDK 1.27.1 的测试——测试时仍提供事件流，因此之后未重新测试——下一次工具调用会失败并返回 unknown_session，直到宿主重新连接服务。设置 TTL 时请考虑这一点——它是以重新连接为代价换取的内存限制，并非透明机制）； /healthz 会报告当前会话数。

委派（_meta）

服务卡片（server.json）可以在命名空间键 holdings.proof/delegation 下的 _meta 中附带一份 委派证明：

{
  "_meta": {
    "holdings.proof/delegation": { "token": "<delegation JWT>" }
  }
}

该令牌是由 proof.holdings 签发的 ES256 JWT，只证明一件事：principal 域的控制者授权 delegate 工件用于所列范围。 它并不表示服务安全、经过审计或获得认可。验证方会根据签发者 JWKS 检查签名，然后将 principal 和 delegate 与其自行解析得到的事实进行比对——复制到另一个包中的令牌无法通过该比对，因为其中的 delegate 指向真正的工件。详情请参阅：委派 — API 参考。

通过官方 MCP 注册表发布卡片时，同一条目会嵌套在 _meta["io.modelcontextprotocol.registry/publisher-provided"] 下——读者应检查这两个位置。

维护者：该条目由 fail-closed 发布工具写入，切勿手动编辑——从仓库根目录执行，且需先为 pkg:npm/@proof-holdings/mcp-server 签发委派：

npm run delegation:publish -- --target mcp --token <jwt>
# or mint + publish in one step (needs PROOF_API_KEY):
npm run delegation:publish -- --target mcp --mint \
  --control-proof ph_ctl_<32hex> --scope proof-verification

如果令牌中的声明没有将此确切包指定为 principal: proof.holdings，该工具就会拒绝令牌（与 --target a2a 在重新生成 /.well-known/agent-card.json 前对照 A2A Agent 卡片自身的 url 所执行的检查相同）。除 server.json 外，--target mcp 还会写入网站卡片的源文件（web/src/lib/geo/mcp-delegation-publication.json），并重新生成 /.well-known/mcp/server-card.json 和 /.well-known/mcp.json，因此需要安装 web/node_modules。对于任一目标，如果写入源文件后卡片重新生成步骤失败，只需重新运行命令——令牌已通过验证，重新生成操作具有幂等性。网站卡片要等到下次部署网站后才会呈现给读者。

验证他人的委派（verify_delegation）

此服务不仅会发布委派，也会检查委派。verify_delegation 工具会通过参考验证器（@proof-holdings/delegation-verifier）检查其他服务的卡片，且不需要 API 密钥——验证仅针对公开信息进行。

{
  "card": { /* the MCP server.json or A2A agent card you fetched */ },
  "delegate": { "type": "purl", "value": "pkg:npm/postmark-mcp" },
  "expected_principal": "postmarkapp.com"
}

两项固定值都不可或缺，且分别用于防范不同的攻击：

• delegate 必须是你解析得到的工件标识——即你即将安装的包或即将调用的端点。切勿从正在检查的卡片中复制该值：已发布的令牌是持有者凭证，因此若将它与同一张卡片中的字段进行比对，就可能认可从其他地方粘贴来的令牌。
• expected_principal 是你期望为该工件背书的域名。签发者不会将工件绑定到任何特定对象，因此任何域名所有者都能签发真实且签名有效、却指向他人包的委派。没有这一固定值，验证结果只能说明“某个域名声称如此”。

重新检查所有已信任的内容（verify_delegations）

verify_delegation 会回答“你现在询问的这个对象是否有效”。如果一个 Agent 已经解析并验证了 35 个工件，逐个调用重新验证就无法扩展——verify_delegations 可在一次调用中批量检查最多 50 个工件，而且无需 API 密钥。

{
  "items": [
    { "card": { /* ... */ }, "delegate": { "type": "purl", "value": "pkg:npm/postmark-mcp" }, "expected_principal": "postmarkapp.com" },
    { "token": "<jwt>", "delegate": { "type": "url", "value": "https://example.com/mcp" }, "expected_principal": "example.com" }
  ]
}

每个条目必须严格采用 verify_delegation 要求的格式（card 与 token 二选一、delegate、expected_principal，以及可选的 required_scopes），并且独立验证——条目之间不共享状态，不会持久化，某个条目验证失败也绝不会影响其他条目的结果。始终会检查撤销状态（此工具没有 check_status: false 选项——批量重新检查的全部目的就是查看发生了什么变化）。

此工具有意不做两件事：

• 它不会发现你安装了什么。 你必须已经持有每个工件的 card 或 token。它不解析 DNS 指针，也不会获取调用者提供的 URL——这与 verify_delegation 已经划定的信任边界相同，并且有意保持狭窄（参见主仓库中 src/services/delegationPointer/resolve.ts 文档列出的缺口；此工具不涉及这些缺口）。
• 它不会持续运行。 每次调用都是一次单独的时点检查。没有检查频率、调度器或推送通知——想获取最新结果时，再次调用即可。

results[] 中的每个结果都包含一个 outcome，分为以下四类：

Outcome	含义
confirmed_valid	委托已通过验证——含义与 verify_delegation 的 verified: true 相同。
confirmed_invalid	确切的否定结果：已撤销、已暂停、已过期、主体或委托方不匹配、未授予所需范围，或令牌格式错误、不受信任或签名错误。
no_claim_found	工件未发布任何委托。这表示不存在，而非指控。
unconfirmed	我们目前无法联系签发方，或以其他方式获得明确结果（例如其 JWKS 或状态端点无法访问）。绝不能将此视为否定结果——它的意思是“稍后再询问”，而不是“已撤销”。

结果还包含 checked_at——该条目自身检查完成时的 ISO 时间戳，而非整个调用共用的时间戳——因此，“在本地已确认”绝不会被说成“此刻通过联系本服务确认”，却不说明具体指哪个。

⚠️ 发布顺序（维护者）

package.json 将 @proof-holdings/delegation-verifier 声明为运行时依赖项，因此在上传此软件包之前，注册表必须能够解析其中指定的版本范围：

每次调整版本范围的发布中，都必须先发布 @proof-holdings/delegation-verifier，再发布 @proof-holdings/mcp-server。 所有文档所述客户端都会通过 npx 启动此服务，因此，如果注册表无法解析某次发布所依赖的版本，在 verifier 发布之前，所有人运行 npx @proof-holdings/mcp-server 都会遇到 E404。.github/workflows/publish-packages.yml 中以 target: all 运行的工作流会通过步骤顺序确保这一顺序；在终端中手动发布时，则没有任何机制强制执行这一顺序，只有 docs/runbooks/npm-release.md 作出说明。

同时开发 verifier 和服务无需发布。改为链接同级软件包：

npm run verifier:link   # cd mcp && npm install ../packages/delegation-verifier --no-save

在此仓库中，测试套件完全无需链接：它通过 vitest 别名而非 node_modules 加载 verifier 的源代码，因此全新克隆后测试即可通过，也能在不构建的情况下使用未提交的 verifier 更改。该别名以同级 verifier 软件包存在为前提；在只包含此软件包的公共镜像中，测试套件会使用 npm ci 安装的 verifier。

要求

• Node.js >= 18.0.0
• 需要用于带密钥工具的 proof.holdings API 密钥。没有密钥，服务也能启动并响应无需密钥的工具——请参阅上文“配置”。

链接

• proof.holdings — 产品网站
• API 文档 — REST API 参考
• 控制台 — 管理您的账户和 API 密钥

许可证

MIT