Skip to main content
Glama
realhandles

@realhandles/mcp

by realhandles
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

@realhandles/mcp

An MCP server that lets an AI agent look up a RealHandles identity and cryptographically verify its signed proof.

The signature check runs locally (via @realhandles/verify), so whether a manifest is authentic never depends on trusting realhandles.com. That decision is the math, done on your side.

Whether an account inside that manifest was ever actually checked is a different question, and it is not one a signature can answer: platform, handle and method are whatever the signer typed, so a flawless signature over {platform: "github", handle: "torvalds", method: "oauth"} is a flawless signature over a lie. Only the party that performed a verification holds a record of it, so the verified/claimed split comes from the RealHandles directory, which intersects the signed manifest against its own proof rows. Both halves are required and neither is enough alone. Anything the directory does not back is reported as claimed, including when an older deployment returns no split at all, in which case the result says so rather than promoting the accounts.

Tools

  • verify_identity(handle) - resolve a handle (aliases and renames included), verify its signed manifest, and return the accounts split into verified and claimed, the key fingerprint, the did:key, and the trust score (which counts verified accounts only).

  • check_link(url) - check whether a URL is a mutually confirmed account of a RealHandles identity (for rendering a "verified" badge).

Related MCP server: Agent Identity MCP Server

Use it

Hosted (no install)

The server runs as a stateless HTTP endpoint, so most clients just need the URL:

https://mcp.realhandles.com/mcp

Nothing to install, no account, no key. Under the 2026-07-28 spec there is no session to establish, so a client can call it directly:

curl -X POST https://mcp.realhandles.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Local (stdio)

Still supported and unchanged. For Claude Desktop, in claude_desktop_config.json:

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

Either way, ask things like "verify the RealHandles identity for david" or "is https://example.com a confirmed account of a RealHandles user?"

Both transports serve the same two tools from the same definitions in src/tools.ts, and the signature check is local to whoever runs it in both cases. The hosted endpoint reads the directory exactly like the local one does, so running it yourself does not put you in a weaker position than using ours.

To point it at a different deployment, set REALHANDLES_ORIGIN (defaults to https://realhandles.com).

Develop

pnpm install
pnpm build
pnpm test

Tests run on Node's own test runner and Node's own TypeScript stripping, so there is no test dependency to install. They need Node 22.18 or newer for that; the engines floor stays at 18 because it describes the published dist, which is plain JavaScript.

License

MIT

Why the @realhandles/verify range is not a caret

package.json asks for ">=0.10.0 <1.0.0" rather than ^0.10.0, and that is deliberate.

A caret on a 0.x version does NOT cross a minor: ^0.6.0 will never install 0.7.0. This package has been silently stranded by that twice, and the second time it went three minors behind before anybody noticed, because nothing breaks loudly. A manifest carrying a field the pinned verifier does not know still verifies, since verifySignedManifest checks the signature over the payload bytes and re-parses without rejecting unknown properties. So a stale pin does not fail; it just quietly stops being able to SURFACE things the product publishes.

While @realhandles/verify is pre-1.0 and is maintained in lockstep with the site (it is src/lib/manifest.ts, didkey.ts and handles.ts copied verbatim, guarded by pnpm check:verify-sync over there), tracking the newest 0.x is what we actually want. Revisit when it reaches 1.0.

Available Tools

2 tools
verify_identityA

Look up a RealHandles identity by handle and cryptographically verify its signed proof. The signature is checked locally, so the result does not require trusting realhandles.com. Returns the verified accounts (split into verified and claimed), the key fingerprint, the did:key, and the trust score.

ParametersJSON Schema
NameRequiredDescriptionDefault
handleYesA RealHandles handle, e.g. "david" or "davidvkimball".

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses key behavioral traits: the signature is checked locally, eliminating the need to trust realhandles.com, and it lists the return data (verified/claimed accounts, fingerprint, did:key, trust score). It does not mention error handling or side effects, but for a lookup tool this is reasonable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states the purpose, the second adds behavioral context and return information. Every sentence earns its place, with no redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, the description is self-contained: it states the purpose, the trust model, and the exact return values. This is sufficient for an agent to invoke and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a full description of the handle parameter with examples, so the tool description adds no additional parameter-level semantics. With 100% schema coverage, the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool looks up a RealHandles identity and cryptographically verifies its signed proof, naming the resource (RealHandles identity) and input (handle). It also distinguishes itself from sibling check_link by focusing on identity verification rather than link checking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when a trustless cryptographic verification is needed, mentioning local signature checks and the return of verified accounts. However, it does not explicitly state when not to use the tool or compare with the sibling check_link, so it lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.5.0
    • First observedcheck_link
    • First observedverify_identity
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 2 tools

Disambiguation5/5

verify_identity takes a handle, while check_link takes a URL. The descriptions clearly distinguish the two: one verifies the identity's signed proof, the other checks a specific link for mutual confirmation. No overlap in purpose or input.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (verify_identity, check_link). The verbs ('verify' and 'check') are synonymous in context, but the nouns clarify the object of each action. This is a uniform and predictable convention.

Tool Count3/5

With only two tools, the server feels minimal. The purpose is specialized (identity verification), but the count is at the lower boundary of what is reasonable for a dedicated server. It is not an extreme mismatch, but agents may need external workarounds for related tasks.

Completeness3/5

The domain appears to be read-only identity verification. verify_identity covers the core lookup and proof verification, while check_link handles a specific use case for badges. Missing operations like resolving a DID or looking up an identity by account might require agents to chain calls, but for the stated purpose the surface is not severely incomplete.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • aip-identity

    The-Nexus-Guard
    A
    license
    A
    quality
    D
    maintenance
    MCP server for AI agent identity — verify agents with Ed25519 signatures, check trust scores, sign and verify content, exchange encrypted messages. Built on the Agent Identity Protocol (AIP).
    8
    MIT

  • trust-mcp

    Schmoll86
    A
    license
    A
    quality
    D
    maintenance
    MCP server for AI agent trust verification, enabling agents to verify identities, check trust scores, and build reputation across multiple blockchain and web platforms.
    12
    5 npm
    1
    MIT

  • web3-agents-mcp

    hanjoonchoe
    A
    license
    A
    quality
    B
    maintenance
    An MCP server that bridges ERC-8004 agent identity, reputation, and validation registries into tool calls, enabling discovery, inspection, and verification of on-chain AI agents from any MCP client.
    8
    MIT