MCP server
The x1id MCP server exposes @handle resolution and records to AI agents over MCP — Streamable HTTP transport, stateless, no auth for read tools, no wallet or signer key material at all. It's a convenience surface, not a source of truth: the two resolution tools relay api.x1id.io byte-for-byte, every other read goes straight to X1 through @x1id/resolve, and the two prepare_* tools return an unsigned instruction for your own wallet to sign — this server never holds a key and never signs or broadcasts anything.
Not yet publicly hosted. mcp.x1id.io is pre-staged but not deployed — there's no public endpoint to point an agent at today. The server itself is real, complete, and smoke-tested against live X1 testnet (every read tool and both prepare_* builders verified against real on-chain state). Run it yourself with the steps below until the public endpoint ships.
Tools
Eight tools on one McpServer, adapted from ArcNS's own MCP server (the EVM/ENS sibling) to x1id's real API surface:
| Tool | Reads | Notes |
|---|---|---|
resolve_name | api.x1id.io | Byte-for-byte relay of GET /resolve/:name. |
reverse_lookup | api.x1id.io | Byte-for-byte relay of GET /reverse/:address. |
check_availability | X1 RPC | Whether the handle's PDA exists yet. |
get_records | X1 RPC | A handle's live (non-stale) cross-chain address records, with per-record verification status. |
get_agent_manifest | X1 RPC + the manifest URL + a live HTTP probe | Whether a handle is an AI agent, its manifest, and how far that's verified — see Agent verification below. |
search_agent_handles | an optional query API + X1 RPC | Prefix/substring search filtered to agent handles. Reports not-available if no query API is configured. |
prepare_register | X1 RPC | Builds an unsigned register instruction. Price is computed on-chain at the landing slot — simulate before showing one. |
prepare_set_record | X1 RPC | Builds an unsigned instruction to create or update one text record. |
Two more tools exist for x402 payments (prepare_x402_payment, verify_x402_payment) — see Getting paid for the payment flow they support. Every prepare_* tool is read-only from this server's own perspective: it builds a transaction, but never signs or sends one.
Agent verification
get_agent_manifest reports one of three levels, and only the level it actually checked — never one it assumed:
| Level | Meaning |
|---|---|
| L0 — declared | Self-asserted: the handle carries an agent.manifest record. |
| L1 — attested | Backed by a live on-chain Attestation the manifest actually references. |
| L2 — pay-to confirmed | A live HTTP 402 probe against the agent's own payment endpoint matched a chain-verified payment address on the handle's records. |
L2 is the one thing the SDK's own agent helpers deliberately don't do — forcing a network request to an arbitrary third-party host from a library call — so it lives here, server-side, instead.
Run it yourself
git clone https://forgejo.selfhsted.com/fortiblox/x1-handles
cd x1-handles/mcp
cp .env.example .env # fill in X1_RPC_URL, X1ID_PROGRAM_ID
npm install
npm run build
npm start| Variable | Required | Default |
|---|---|---|
X1_RPC_URL | yes | — |
X1ID_PROGRAM_ID | yes | — |
X1ID_API_URL | no | https://api.x1id.io |
X1ID_QUERY_API_URL | no | unset — search_agent_handles reports not-available |
MCP_BIND | no | 0.0.0.0:8696 |
See the Contracts page for the program ID and RPC endpoint to fill in above.