# MCP server
URL: /docs/x1id/mcp

> The x1id MCP server for AI agents — every tool it exposes, the agent-verification ladder, and how to run it yourself. Not yet publicly hosted; the code is real and tested against live X1 testnet.

# MCP server

<LlmActions />

The x1id MCP server exposes `@handle` resolution and records to AI agents over [MCP](https://modelcontextprotocol.io) — 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`](/docs/x1id/api) byte-for-byte, every other read goes straight to X1 through [`@x1id/resolve`](https://www.npmjs.com/package/@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.

<Callout type="warn">
  **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.
</Callout>

## Tools

Eight tools on one `McpServer`, adapted from [ArcNS's own MCP server](https://mcp.arcns.io) (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](#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.                                                           |

<Callout type="info">
  Two more tools exist for x402 payments (`prepare_x402_payment`, `verify_x402_payment`) — see [Getting paid](/docs/x1id/get-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.
</Callout>

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

```bash title="terminal"
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](/docs/x1id/contracts) page for the program ID and RPC endpoint to fill in above.