Using the MCP server

# Using the MCP server Self Agent ID hosts a [Model Context Protocol](https://modelcontextprotocol.io/) server at **`https://agent-api.self.xyz/api/mcp`** (Streamable HTTP, stateless). Any MCP client (Claude Code, Cursor, Windsurf, Codex and others) can use it to register, look up and verify agents. There is nothing to install, and the public tools need no API key. To sign as your own agent, run the [local server](#local-server) instead. ## Configuration ::::tabs :::tab{label="Claude Code"} ```bash claude mcp add --transport http self-agent-id https://agent-api.self.xyz/api/mcp ``` Or add it to `.mcp.json` in your project: ```json { "mcpServers": { "self-agent-id": { "type": "http", "url": "https://agent-api.self.xyz/api/mcp" } } } ``` ::: :::tab{label="Cursor / Windsurf / other clients"} ```json { "mcpServers": { "self-agent-id": { "url": "https://agent-api.self.xyz/api/mcp" } } } ``` ::: :::: Tools take a `network` argument (`mainnet` or `testnet`) that defaults to **`mainnet`**. Ask for `testnet` while developing. Registrations on `testnet` use a [mock passport](/docs/self-enterprise/guides/using-mock-passports/) in the Self app. ## Public tools These tools are available to everyone on the hosted server: | Tool | Arguments | Does | | ---------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `self_register_agent` | `human_address?`, `minimum_age?`, `ofac?`, `network` | Starts a registration: `linked` with `human_address`, otherwise `wallet-free`. Returns the QR code, `scan_url` and a `session_token` | | `self_check_registration` | `session_token`, `reveal_private_key?` | Polls the registration (pass the latest rotated `session_token`). With `reveal_private_key: true` once completed, it exports the agent key into the conversation | | `self_lookup_agent` | `agent_id` or `agent_address`, `network` | Registration, verification, provider and disclosed credentials | | `self_list_agents_for_human` | `human_address`, `network` | Agents a wallet owns, plus the agent whose key it is | | `self_verify_agent` | `agent_address`, policy | Passes only with a fresh human proof that meets the policy | | `self_verify_request` | `agent_address`, `agent_signature`, `agent_timestamp`, `method`, `path`, `body?`, policy | Verifies ECDSA-signed `x-self-agent-*` headers (timestamp, replay, on-chain status, policy). For Ed25519-signed requests, use the SDK's `SelfAgentVerifier` | Policy arguments: `require_age` (`0`, `18` or `21`, default `0`), `require_ofac` (default `false`), `require_self_provider` (default `true`), `max_agents_per_human` (default `1`, `0` = no limit) and `network`. The server also offers the resource `self://networks` (chain IDs, registries, RPC URLs) and the prompt `self_integrate_verification`, which takes a `framework` (e.g. `Express`) and generates verification middleware. ## Privileged tools These tools act as the **server's own agent**, so they need a server-side agent key. The hosted server doesn't offer them to callers. To use them, run your own deployment of the [API](https://github.com/selfxyz/self-agent-id/tree/main/app) with `SELF_AGENT_PRIVATE_KEY` and `MCP_PRIVILEGED_API_KEY` set, and call it with that key: | Tool | Does | | -------------------------- | ---------------------------------------------------------------------------- | | `self_get_identity` | On-chain identity, verification and credentials of the server's agent | | `self_deregister_agent` | Starts deregistering the server's agent (the human confirms in the Self app) | | `self_sign_request` | `x-self-agent-*` headers signed as the server's agent | | `self_authenticated_fetch` | A signed HTTP request as the server's agent (public hosts only) | The resource `self://identity` (the server agent's identity) is privileged in the same way. ```json { "mcpServers": { "self-agent-id": { "type": "http", "url": "https://your-deployment.example.com/api/mcp", "headers": { "Authorization": "Bearer ${SELF_MCP_API_KEY}" } } } } ``` To sign as your own agent, use the [local server](#local-server) or the SDK (`SelfAgent` or `Ed25519Agent`). ## Local server [`@selfxyz/mcp-server`](https://www.npmjs.com/package/@selfxyz/mcp-server) runs the same 10 tools on your machine over stdio. With `SELF_AGENT_PRIVATE_KEY` set, the 4 privileged tools sign as **your** agent, and the key never leaves the process. Requires Node.js 18 or later. ::::tabs :::tab{label="Claude Code"} ```bash claude mcp add self-agent-id -e SELF_AGENT_NETWORK=testnet -- npx -y @selfxyz/mcp-server ``` ::: :::tab{label="Cursor / Windsurf / other clients"} ```json { "mcpServers": { "self-agent-id": { "command": "npx", "args": ["-y", "@selfxyz/mcp-server"], "env": { "SELF_AGENT_NETWORK": "testnet", "SELF_AGENT_PRIVATE_KEY": "0x..." } } } } ``` ::: :::: | Variable | Default | Sets | | --------------------------------------- | ---------------------------- | -------------------------------------------------------------------------- | | `SELF_AGENT_PRIVATE_KEY` | unset | Your agent key. Turns on the 4 privileged tools | | `SELF_AGENT_NETWORK` | `mainnet` | `mainnet` or `testnet` | | `SELF_RPC_URL` | network default | RPC endpoint | | `SELF_AGENT_API_BASE` | `https://agent-api.self.xyz` | REST API to call | | `MCP_AUTH_FETCH_ALLOWED_HOSTS` | unset | Hosts `self_authenticated_fetch` may reach (`*.example.com` for subdomains) | | `MCP_AUTH_FETCH_ALLOW_PRIVATE_NETWORKS` | `false` | `true` lets `self_authenticated_fetch` reach private addresses | An invalid key, network or API base stops the server at startup. To get a key, leave `SELF_AGENT_PRIVATE_KEY` unset, call `self_register_agent`, scan the QR code, then call `self_check_registration` with `reveal_private_key: true` once it reports `completed`. Set that key as `SELF_AGENT_PRIVATE_KEY` and restart the server. The key appears in the conversation, so keep that transcript private. ## Limits Each MCP request is limited to 120/min per IP, and each tool call also counts against the limit of the REST endpoint it uses (for example, 10 registrations per minute). See [Rate limits](/docs/agent-id/rest-api/#rate-limits). ## Example prompts ``` Register a new Self agent on testnet, linked to 0xYourWallet, with age 18+. Show me the QR. ``` ``` Check my registration status. When it's completed, reveal the private key. ``` ``` Look up Self Agent ID #5 on testnet. Is it verified, and when does its proof expire? ``` ``` Verify that agent 0x83fa4380903fecb801F4e123835664973001ff00 is backed by a human over 18 on mainnet. ``` ``` Use the self_integrate_verification prompt with Express to generate verification middleware. ``` ## Claude Code plugin The repo also ships a Claude Code plugin with six skills (`self-agent-id-overview`, `register-agent`, `sign-requests`, `verify-agents`, `query-credentials`, `integrate-self-id`) and this MCP server: ```bash git clone https://github.com/selfxyz/self-agent-id.git claude --plugin-dir ./self-agent-id/plugin ``` ## Agents without MCP Frameworks that can't run MCP get the same features over HTTP: the [REST API](/docs/agent-id/rest-api/) and the [A2A endpoint](/docs/agent-id/rest-api/#a2a) at `https://agent-api.self.xyz`. ## Next steps - [Build an agent](/docs/agent-id/guides/agent-builder/) - [Verify agents in your API](/docs/agent-id/guides/service-operator/) - [Troubleshooting](/docs/agent-id/troubleshooting/)

Read https://docs.self.xyz/docs/agent-id/guides/mcp-user.md so I can ask questions about this Self documentation page.