
verifiedhandles-mcp
Connect an AI agent to Verified Handles: setup for each client, the MCP Registry listing, a Claude Desktop extension.
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up verifiedhandles-mcp (release-binary project) into my current project. Found on https://claudeers.com/verifiedhandles-mcp Repo: https://github.com/jameshaworthcs/verifiedhandles-mcp Homepage/docs: https://verifiedhandles.org/developers/mcp Detected install method: release-binary → inspect the README Category: mcp-servers. Platforms: cli, api, desktop, web, mobile. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
Grab the latest release asset from GitHub.
# download a build from https://github.com/jameshaworthcs/verifiedhandles-mcp/releases
git clone https://github.com/jameshaworthcs/verifiedhandles-mcp
// compatibility
| Platforms | cli, api, desktop, web, mobile |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | JavaScript |
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.6.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).
No key, a read-only key, or a full key
| Connected with | Tools listed | Acts as |
|---|---|---|
| No key | The public reads that need nothing else: get_entry, search_entries and get_entry_history. Just leave out the Authorization header. | A signed-out visitor: the public record only. |
| A read-only key | Every read tool your role is listed, and no tool that changes anything. | You, reading. |
| A key | Every tool your role is listed (see which tools each role is listed). | You, at the lower of the key’s role ceiling and your role today. |
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) 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 (Cursor, 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.
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/accountwith no token answers401withWWW-Authenticate: Bearer resource_metadata="https://verifiedhandles.org/.well-known/oauth-protected-resource/mcp/account", scope="mcp". The metadata is athttps://verifiedhandles.org/.well-known/oauth-protected-resource/mcp/account(RFC 9728) andhttps://verifiedhandles.org/.well-known/oauth-authorization-server(RFC 8414). - A client registers with a Client ID Metadata Document: its
client_idis thehttpsaddress of that document. There is no Dynamic Client Registration, and no client secret. - The authorization code flow with PKCE,
S256only. Sendresource: the address you connect to (https://verifiedhandles.org/mcp/account, orhttps://verifiedhandles.org/mcp); a token works there and nowhere else. The one scope ismcp, andisscomes 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 athttps://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
{
"mcpServers": {
"verified-handles": {
"url": "https://verifiedhandles.org/mcp",
"headers": {
"Authorization": "Bearer ${env:VH_API_KEY}"
}
}
}
}
VS Code
In a workspace’s .vscode/mcp.json. VS Code asks for the key the first time and keeps it, so it never sits in the file:
.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
Add it as a custom connector (Settings, Connectors, Add custom connector), as for claude.ai below. Or, through the mcp-remote bridge (it needs Node.js 18 or later), in claude_desktop_config.json. The key goes in env, because some clients do not pass a space inside an argument safely:
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 and other custom connectors
On claude.ai (and Claude’s desktop and mobile apps), add a custom connector with the address https://verifiedhandles.org/mcp. Choose No sign in: with nothing more, it reads with no key. To use your key, add a request header Authorization with the value Bearer vhk_<prefix>_<secret>. The connector calls from Anthropic’s servers, not your computer, so it shares their addresses’ rate limit; a key is the way to be counted as yourself. To sign in instead of sending a key, use the address https://verifiedhandles.org/mcp/account: see Connect with your account (OAuth).
Test the connection
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 runs, confirm and proposing
Every tool that changes something does nothing by default. Called as it is, it runs with dry_run: true: it reads the entry as it is now and answers with what it would change, the exact request it would send, and whether your account may make it. To make the change, call it again with dry_run: false.
A change that destroys something or affects the whole site also needs confirm, set to the exact target the dry run names (an entry’s VHID, say), so it is never made by accident.
To change an entry without it going live, propose it: the propose_* tools send it to a reviewer, as a suggestion on the site does, and nothing changes until a person approves it. Sending the same proposal again answers with the one already waiting. Each tool that edits live names the tool that proposes the same change instead.
Rate limits
Messages with no key are limited to 60 a minute from one IP address, shared by everyone calling from it, as everyone using an agent hosted on someone else’s servers is (a claude.ai connector calls from Anthropic’s). With a key, or connected with your account, the limit is 120 a minute for each key, wherever its messages come from. Each tool call is also counted by the request it makes, as any request to the site is: a read in the JSON reads’ limit (120 a minute), a change in the limits on changes, per address, per account and per key. Past a limit, the answer is 429 Too Many Requests with a Retry-After header: wait that many seconds, then go on.
The Claude Desktop extension
The mcpb/ folder is a Claude Desktop extension. Claude Desktop runs it with its own Node.js; it starts mcp-remote, which connects to the server for it. Its one setting is your API key, and it is optional: left empty, the extension reads with no key. Claude Desktop hides the key as you type it and stores it securely.
To build the .mcpb file from this folder (Node.js 18 or later):
cd mcpb
npm install --omit=dev
npx @anthropic-ai/mcpb pack
About this repository
Everything here is generated from the Verified Handles source each time the server changes, so a pull request to these files would be overwritten: please open an issue instead.
This repository is MIT-licensed: see LICENSE.
// faq
What is verifiedhandles-mcp?
Connect an AI agent to Verified Handles: setup for each client, the MCP Registry listing, a Claude Desktop extension.. It is open-source on GitHub.
Is verifiedhandles-mcp free to use?
verifiedhandles-mcp is open-source under the MIT license, so it is free to use.
What category does verifiedhandles-mcp belong to?
verifiedhandles-mcp is listed under mcp-servers in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/verifiedhandles-mcp)
// retro hit counter
[](https://claudeers.com/verifiedhandles-mcp)
// reviews
// guestbook
// related in MCP Servers
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete…
A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman
An open-source AI agent that brings the power of Gemini directly into your terminal.