Verified Handles MCP server

Verified Handles lists people, organisations and things with their verified social handles and other identifiers. Its MCP server lets an AI agent look entries up, search them and read their history with no key, and, with your key or your account, do what you can do on the site.

This repository holds what you need to connect to it: the server itself runs at https://verifiedhandles.org/mcp, and its code is not here. The full guide, with every tool, is at https://verifiedhandles.org/developers/mcp.

• Version 1.33.0: what changed is in CHANGELOG.md.
• The tools, as the server lists them: with no key and with a registered account’s key, each with its input and output schemas.
• A Claude Desktop extension to install in one click: mcpb/.
• The MCP Registry listing: server.json.
• A problem or a question? Open an issue.

The guides below are the ones at https://verifiedhandles.org/developers/mcp, word for word, so “this site” and “here” in them mean verifiedhandles.org.

What MCP is here

MCP, the Model Context Protocol, is how an AI agent (Claude, Cursor, Copilot and others) uses a service through tools it can call. The Verified Handles server is at https://verifiedhandles.org/mcp, over MCP’s Streamable HTTP transport. It is stateless: each message is one POST, answered in JSON, with no session to keep.

Every tool goes through the same routes and checks as the site and the rest of the API: an agent can do nothing you could not do yourself, and with a key it acts as you. Nothing is changed by accident: every tool that changes something only shows what it would do until it is told otherwise (see dry runs).

The server is listed in the MCP Registry as org.verifiedhandles/verified-handles, and its setup guides, changelog and a Claude Desktop extension are on GitHub.

No key, a read-only key, or a full key

A key that is sent but wrong, revoked or expired is refused with 401; it is never treated as no key. Answers are never cached, by anyone.

Getting a key

Any account can make a key: registered accounts and trusted editors may by default, and administrators hold every permission. (An administrator can take the permission away from an account.) Sign in, choose Console in the menu, then Account, then Manage API keys.

• The key is shown once, when it is made, as vhk_<prefix>_<secret>. Keep it somewhere safe; if it leaks, revoke it on the same page and it stops working at once.
• A role ceiling at or below your own role: the key never acts as more, and a role taken from you is taken from your keys too.
• Read-only, if you only read: the agent is then listed no tool that changes anything.
• An expiry of 1 to 90 days. You can keep up to 5 keys at once.

Connect with your account (OAuth)

Clients that sign in with OAuth (Claude, Claude Code, ChatGPT, VS Code, Cursor) can act as you without an API key. Connect them to https://verifiedhandles.org/mcp/account: they open a Verified Handles page where you sign in and choose what they may do: a role ceiling, read only, and for how long (7, 30 or 90 days).

https://verifiedhandles.org/mcp stays as it is: with no key, the public reads; with an API key, your account. Your connected apps are on Console → Account → API keys, where you can disconnect one; you can have up to 10 at once. For clients that can’t sign in this way, such as scripts, use an API key as before.

Claude Code

In a terminal

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

Then run /mcp in Claude Code, choose verified-handles and Authenticate: your browser opens the Verified Handles page.

claude.ai and Claude’s apps

Add a custom connector (Settings, Connectors, Add custom connector) with the address https://verifiedhandles.org/mcp/account, leaving the advanced settings empty, then choose Connect.

VS Code

.vscode/mcp.json

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

VS Code asks you to sign in the first time it connects.

ChatGPT

In developer mode, create a connector with the address https://verifiedhandles.org/mcp/account and OAuth as its authentication. Or start with https://verifiedhandles.org/mcp and no key: it reads, and ChatGPT can link your Verified Handles account later, when it asks you to.

Cursor, and other apps that register themselves

Some clients, Cursor among them, publish no details of their own: they register themselves with Verified Handles the first time they connect. That works, but nobody can check who made an app like that, so the page marks it Unverified app, and your API keys page marks it Unverified too. Instead of where its details are published, it shows where the app sends you back to: a web address, your own computer, or for an app on your device, the kind of address it opens (such as com.example.app:). Any app can call itself anything, so allow one only if you started connecting it yourself, just now.

Cursor: mcp.json

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

With no headers, Cursor asks you to sign in when it connects. To use an API key instead, see Setting up your client.

What the page asks

The page names the app as it describes itself, the web address its details are published at, and where it sends you back to. Only allow an app you started connecting yourself, just now. It can do what your account can do, never more than the role you pick, and never more than your own role if that changes. When its days are up it asks again; you can disconnect it sooner.

For client authors

• A request to https://verifiedhandles.org/mcp/account with no token answers 401 with WWW-Authenticate: Bearer resource_metadata="https://verifiedhandles.org/.well-known/oauth-protected-resource/mcp/account", scope="mcp". The metadata is at https://verifiedhandles.org/.well-known/oauth-protected-resource/mcp/account (RFC 9728) and https://verifiedhandles.org/.well-known/oauth-authorization-server (RFC 8414).
• A client registers with a Client ID Metadata Document: its client_id is the https address of that document. Without one, it can register at https://verifiedhandles.org/oauth/register (Dynamic Client Registration, RFC 7591), and the person sees it marked unverified. Either way there is no client secret. A registered client’s redirect URIs are https:, loopback http: (any port then matches) or a private-use scheme with a dot (RFC 8252 §7.1, such as com.example.app:/callback); others are dropped. At most 10 registrations an hour from one address; one never used is deleted after 24 hours.
• The authorization code flow with PKCE, S256 only. Send resource: the address you connect to (https://verifiedhandles.org/mcp/account, or https://verifiedhandles.org/mcp); a token works there and nowhere else. The one scope is mcp, and iss comes back with the code.
• A code works once, for 60 seconds; an access token for 1 hour. A refresh token is replaced each time it is used, and using an old one again ends the connection. Send the token as Authorization: Bearer, never in a query string; revoke it at https://verifiedhandles.org/oauth/revoke.

Setting up your client

Each recipe below connects with a key; for no key, leave the Authorization header (or the setting that sends it) out. Put your own key where it says vhk_<prefix>_<secret>, and keep it out of anything you share or commit: where a client can read it from an environment variable, the recipe does.

Claude Code

In a terminal

# 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>"

Or in a project’s .mcp.json, with the key read from your environment when Claude Code starts:

.mcp.json

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

Cursor

In ~/.cursor/mcp.json (every project) or a project’s .cursor/mcp.json:

mcp.json