Verified Handles

Verified Handles MCP 服务

Verified Handles 列出了人物、组织和事物及其官方社交媒体账号和其他标识符。它的 MCP 服务无需密钥即可让 AI Agent 查找条目、搜索条目并查看其历史记录；使用你的密钥或账户，还可以执行你在网站上能执行的操作。

此仓库包含连接该服务所需的内容：服务本身运行在 https://verifiedhandles.org/mcp，其代码不在此处。完整指南（包含所有工具）位于 https://verifiedhandles.org/developers/mcp。

• 版本 1.59.1：变更内容见 CHANGELOG.md。
• 工具，按服务的列表所示：无需密钥和使用已注册账户的密钥，每个工具都附有输入和输出架构。
• Claude Desktop 扩展，可一键安装：mcpb/。
• MCP Registry 列表：server.json。
• 遇到问题或有疑问？提交问题。

以下指南与 https://verifiedhandles.org/developers/mcp 上的内容逐字相同，因此其中的“本网站”和“此处”均指 verifiedhandles.org。

此处的 MCP 是什么

MCP（Model Context Protocol）是一种协议，让 AI Agent（Claude、Cursor、Copilot 等）通过可调用的工具使用服务。Verified Handles 服务位于 https://verifiedhandles.org/mcp，使用 MCP 的 Streamable HTTP 传输方式。它是无状态的：每条消息都是一个 POST，以 JSON 格式响应，无需保持会话。

每个工具都会经过与网站及 API 其余部分相同的路由和检查：Agent 无法执行你自己无法执行的操作；使用密钥时，它会以你的身份执行操作。不会意外修改任何内容：每个会修改内容的工具都会先显示将要执行的操作，只有在明确要求后才会执行（参见试运行）。

该服务在 MCP Registry 中的条目为 org.verifiedhandles/verified-handles，其设置指南、变更日志和Claude Desktop 扩展位于 GitHub。

连接之前，客户端可以在 https://verifiedhandles.org/mcp/server-card 读取服务卡片，其中包含服务名称、版本和地址。Agent 发现工具可在 https://verifiedhandles.org/.well-known/ard.json 中找到该服务和读取 API。

无密钥、只读密钥或完整密钥

连接方式	列出的工具	操作身份
无密钥	无需其他条件的公开读取工具：get_entry、search_entries、find_by_handle、get_entry_history 和 get_entries。只需省略 Authorization 标头。	已退出登录的访客：只能访问公开记录。
只读密钥	你的角色可用的所有读取工具，不包含任何会修改内容的工具。	以你的身份读取。
密钥	你的角色可用的所有工具（参见各角色可用的工具）。	以你的身份操作，但权限不超过密钥角色上限和你当前角色中较低的一方。

如果发送了密钥但密钥错误、已撤销或已过期，请求将被拒绝并返回 401；它绝不会被当作未提供密钥处理。任何人的回答都不会被缓存。

获取密钥

任何账户都可以创建密钥：注册账户和可信编辑者默认可以创建，管理员则拥有所有权限。（管理员可以撤销某个账户的权限。）登录后，在菜单中依次选择 Console、Account，然后选择 Manage API keys。

• 密钥只会显示一次，创建时显示为 vhk_<prefix>_<secret>。请将它妥善保存；如果密钥泄露，请在同一页面撤销，它会立即失效。
• 角色上限不高于你自己的角色：密钥的权限永远不会超出此上限；如果你被降权，密钥的权限也会随之降低。
• 如果你只需读取，请设为只读：此时不会向 Agent 列出任何会更改内容的工具。
• 有效期为 1 至 90 天。你最多可以同时持有 5 个密钥。

使用账户连接（OAuth）

使用 OAuth 登录的客户端（Claude、Claude Code、ChatGPT、VS Code、Cursor）无需 API 密钥即可代表你操作。将它们连接到 https://verifiedhandles.org/mcp/account：它们会打开 Verified Handles 页面，你可以在此登录，并选择允许它们执行的操作：设置角色上限、只读权限以及有效期（7、30 或 90 天）。

https://verifiedhandles.org/mcp 保持不变：不使用密钥时可读取公开内容；使用 API 密钥时则使用你的账户。已连接的应用会显示在 Console → Account → API keys 中，你可以在此断开连接；最多可同时连接 10 个应用。对于无法通过这种方式登录的客户端（例如脚本），仍可像以前一样使用 API 密钥。

Claude Code

在终端中

claude mcp add --transport http verified-handles https://verifiedhandles.org/mcp/account

然后在 Claude Code 中运行 /mcp，选择 verified-handles 和 Authenticate：浏览器会打开 Verified Handles 页面。

claude.ai 和 Claude 应用

使用地址 https://verifiedhandles.org/mcp/account 添加自定义连接器（Settings、Connectors、Add custom connector），高级设置留空，然后选择 Connect。

VS Code

.vscode/mcp.json

{
  "servers": {
    "verified-handles": {
      "type": "http",
      "url": "https://verifiedhandles.org/mcp/account"
    }
  }
}

VS Code 首次连接时会要求你登录。

ChatGPT

在开发者模式下，使用地址 https://verifiedhandles.org/mcp/account 创建连接器，并将 OAuth 设为其身份验证方式。也可以从 https://verifiedhandles.org/mcp 开始且不提供密钥：它会读取内容，之后 ChatGPT 会在征求你的许可时关联你的 Verified Handles 账户。

Cursor 及其他自行注册的应用

有些客户端（包括 Cursor）不会公布自己的详细信息：它们会在首次连接时向 Verified Handles 自行注册。这样虽然可行，但无人能核实此类应用的创建者，因此页面会将其标记为 Unverified app，API keys 页面也会将其标记为 Unverified。页面不会显示应用公布详细信息的位置，而是显示应用将你重定向到的位置：一个网址、你的计算机，或者对于设备上的应用，显示它打开的地址类型（例如 com.example.app:）。任何应用都可以自称为任何名称，因此只允许你刚刚亲自发起连接的应用。

Cursor：mcp.json

{
  "mcpServers": {
    "verified-handles": {
      "url": "https://verifiedhandles.org/mcp/account"
    }
  }
}

如果没有 headers，Cursor 会在连接时要求你登录。若要改用 API 密钥，请参阅设置客户端。

页面会提示什么

页面会显示应用自述的名称、其详细信息公布的网址，以及它将你重定向到的位置。只允许你刚刚亲自发起连接的应用。它可以执行你的账户能够执行的操作，但权限不会超出你选择的角色；如果你的角色发生变化，权限也不会超出你自己的角色。有效期结束后，应用会再次请求授权；你也可以提前断开连接。

面向客户端作者

• 向 https://verifiedhandles.org/mcp/account 发送不带令牌的请求，会收到 401，并附带 WWW-Authenticate: Bearer resource_metadata="https://verifiedhandles.org/.well-known/oauth-protected-resource/mcp/account", scope="mcp"。元数据位于 https://verifiedhandles.org/.well-known/oauth-protected-resource/mcp/account（RFC 9728）和 https://verifiedhandles.org/.well-known/oauth-authorization-server（RFC 8414）。
• 客户端使用 Client ID Metadata Document 注册：其 client_id 是该文档的 https 地址。没有此类文档时，可在 https://verifiedhandles.org/oauth/register 注册（Dynamic Client Registration，RFC 7591），用户会看到客户端被标记为未验证。无论哪种方式，都不需要客户端密钥。已注册客户端的重定向 URI 必须是 https:、环回 http:（任意端口均匹配），或带点号的私用方案（RFC 8252 §7.1，例如 com.example.app:/callback）；其他 URI 会被丢弃。每个地址每小时最多注册 10 次；从未使用的注册会在 24 小时后删除。
• 使用带 PKCE 的授权码流程，且仅支持 S256。发送 resource：你要连接的地址（https://verifiedhandles.org/mcp/account 或 https://verifiedhandles.org/mcp）；令牌仅在该地址有效。唯一的 scope 是 mcp，返回的授权码中会附带 iss。
• 授权码只能使用一次，有效期为 60 秒；访问令牌有效期为 1 小时。每次使用刷新令牌时都会换发新令牌，再次使用旧令牌会终止连接。通过 Authorization: Bearer 发送令牌，切勿将其放在查询字符串中；可在 https://verifiedhandles.org/oauth/revoke 撤销令牌。

设置客户端

以下每个配置示例都会使用密钥连接；不使用密钥时，省略 Authorization 请求头（或用于发送该请求头的设置）。将 vhk_<prefix>_<secret> 替换为你自己的密钥，并确保不要将其分享或提交到版本库：对于可从环境变量读取密钥的客户端，示例会这样设置。

Claude Code

在终端中

# No key: the public reads
claude mcp add --transport http verified-handles https://verifiedhandles.org/mcp

# With a key (add --scope user to have it in every project)
claude mcp add --transport http verified-handles https://verifiedhandles.org/mcp \
  --header "Authorization: Bearer vhk_<prefix>_<secret>"

也可以将其写入项目的 .mcp.json，并在 Claude Code 启动时从环境变量读取密钥：

.mcp.json

{
  "mcpServers": {
    "verified-handles": {
      "type": "http",
      "url": "https://verifiedhandles.org/mcp",
      "headers": {
        "Authorization": "Bearer ${VH_API_KEY}"
      }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json（适用于所有项目）或项目的 .cursor/mcp.json 中：

mcp.json

{
  "mcpServers": {
    "verified-handles": {
      "url": "https://verifiedhandles.org/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VH_API_KEY}"
      }
    }
  }
}

VS Code

在工作区的 .vscode/mcp.json 中。VS Code 会在首次使用时询问密钥并将其保存，因此密钥不会留在文件中：

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "vh-api-key",
      "description": "Verified Handles API key",
      "password": true
    }
  ],
  "servers": {
    "verified-handles": {
      "type": "http",
      "url": "https://verifiedhandles.org/mcp",
      "headers": {
        "Authorization": "Bearer ${input:vh-api-key}"
      }
    }
  }
}

Claude Desktop

将其添加为自定义连接器（Settings、Connectors、Add custom connector），方式与下文介绍的 claude.ai 相同。或者，通过 mcp-remote 桥接工具（需要 Node.js 18 或更高版本），将其添加到 claude_desktop_config.json。密钥应放在 env 中，因为有些客户端无法安全地将含空格的内容作为参数传递：

claude_desktop_config.json

{
  "mcpServers": {
    "verified-handles": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://verifiedhandles.org/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer vhk_<prefix>_<secret>"
      }
    }
  }
}

claude.ai 和其他自定义连接器

在 claude.ai（以及 Claude 的桌面和移动应用）中，添加地址为 https://verifiedhandles.org/mcp 的自定义连接器。选择 No sign in：不做其他设置时，它会在不使用密钥的情况下读取数据。若要使用密钥，请添加请求头 Authorization，值设为 Bearer vhk_<prefix>_<secret>。连接器的请求由 Anthropic 的服务器发出，而非你的电脑，因此会受到 Anthropic 服务器地址的速率限制；使用密钥才能将请求计入你自己的名下。若要登录而不是发送密钥，请使用地址 https://verifiedhandles.org/mcp/account：参阅使用账户连接（OAuth）。

测试连接

curl

curl -s https://verifiedhandles.org/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $VH_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Leave out the Authorization line to see what no key is listed.

试运行、确认和提案

默认情况下，任何会更改内容的工具都不会执行操作。 直接调用时，它会以 dry_run: true 运行：读取当前条目，并告知你它会更改什么、会发送的确切请求，以及你的账户是否有权限执行。要执行更改，请再次调用，并将 dry_run: false。

会销毁内容或影响整个网站的更改，还需要设置 confirm，其值必须与试运行中指出的确切目标一致（例如条目的 VHID），以免意外执行。

如果要更改条目但不让更改立即生效，请提交提案：propose_* 工具会将提案发送给审核者，就像在网站上提交建议一样；只有审核者批准后才会更改内容。再次提交相同提案时，会返回已在等待审核的那个提案。每个可编辑实时内容的工具都会注明用于提议相同更改的工具。

在浏览器中使用（WebMCP）

WebMCP 让运行在你自己浏览器中的 AI agent 可以在当前页面旁使用网站。无需连接地址，也无需密钥：网站页面会向 Agent 提供工具，每个工具都在页面中运行。

每个页面上都有五个工具可读取公开记录，且不会执行任何已登出访客无法执行的操作：

• search_entries、get_entry 和 get_entry_history：与无需密钥的同名工具相同。
• get_current_entry：在条目页面上，读取页面当前显示的条目。
• open_entry_page：仅在本网站上打开条目页面。

在条目页面上登录后，还会提供另外两个工具。它们都不会保存任何内容：

• start_entry_edit：将 Agent 提出的更改放入编辑器，作为你对条目的草稿。只有在你亲自按下「Save」或「Propose edit」后才会发送，并且不会替换你已有的草稿。
• propose_entry_change：向你展示更改并征求确认。只有你亲自点击「Send proposal」后，才会将其作为提案发送给审核者，就像在网站上提交建议一样；点击「Cancel」则不会发送任何内容。审核者会看到 AI agent 帮助你准备了这份提案。

按设计，控制台不会向 Agent 提供任何工具。

启用方法。 WebMCP 是一项新功能，目前并非所有浏览器都支持。本网站参与了 Chrome 和 Edge 为此开展的 Origin Trial，因此在其试用范围内的版本中，无需进行任何设置即可使用这些工具。否则，请在 Chrome 149 或更高版本中打开 chrome://flags/#enable-webmcp-testing，将其设为 Enabled，然后重启 Chrome（或者使用 --enable-features=WebMCP 启动 Chrome）。你的浏览器还需要一个会调用这些工具的 Agent，例如 Chrome 的 Model Context Tool Inspector 扩展程序。

速率限制

不带密钥的消息每分钟限制为 60 条，按 IP 地址计算，同一地址下的所有调用者共享此限制；凡是使用托管在他人服务器上的 Agent 的用户也共用此限制（例如，claude.ai 连接器的请求来自 Anthropic）。使用密钥或通过账户连接时，每个密钥每分钟限制为 120 条消息，无论消息来自何处。每次工具调用也会按其发出的请求计数，与任何发往网站的请求一样：读取操作计入 JSON 读取的限制（每分钟 120 次），更改操作则计入更改限制，限制按地址、账户和密钥分别计算。超过限制后，响应为 429 Too Many Requests，并带有 Retry-After 标头：等待指定秒数后再继续。

Claude Desktop 扩展

mcpb/ 文件夹是一个 Claude Desktop 扩展。Claude Desktop 使用自带的 Node.js 运行该扩展；扩展会启动 mcp-remote，由它连接到服务。扩展只有一个设置，即 API 密钥；该设置为可选项：留空时，扩展会在不使用密钥的情况下读取。输入密钥时，Claude Desktop 会将其隐藏，并安全存储。

构建好的文件 verified-handles.mcpb 位于发布页面：用 Claude Desktop 打开即可安装。若要从此文件夹自行构建（Node.js 18 或更高版本）：

cd mcpb
npm install --omit=dev
npx @anthropic-ai/mcpb pack

关于此仓库

此处的所有内容都会在服务发生更改时根据 Verified Handles 源码重新生成，因此针对这些文件的拉取请求会被覆盖：请改为提交问题。

此仓库采用 MIT 许可证：请参阅 LICENSE。