Using the MCP Server

# Using the MCP Server The Self Agent ID [MCP server](https://github.com/selfxyz/self-agent-id-mcp) gives AI coding agents access to the on-chain identity registry through the [Model Context Protocol](https://modelcontextprotocol.io/). It works with Claude Code, Cursor, Windsurf, Codex, and any MCP-compatible client. ## What is MCP? The Model Context Protocol (MCP) is an open standard that lets AI assistants access external tools and data. The Self Agent ID MCP server exposes 10 tools for agent registration, verification, authentication, and discovery. ## Configuration Add the server to your MCP client config: ::::tabs :::tab{label="Claude Code"} Add to `~/.claude.json` (global) or `.mcp.json` (per-project): ```json { "mcpServers": { "self-agent-id": { "command": "npx", "args": ["@selfxyz/mcp-server"], "env": { "SELF_NETWORK": "mainnet" } } } } ``` ::: :::tab{label="Cursor / Windsurf"} Add to your MCP configuration file: ```json { "mcpServers": { "self-agent-id": { "command": "npx", "args": ["@selfxyz/mcp-server"], "env": { "SELF_NETWORK": "mainnet", "SELF_AGENT_PRIVATE_KEY": "0x..." } } } } ``` ::: :::: ### Environment Variables | Variable | Required | Default | Description | | ------------------------ | :------: | ---------------------------- | --------------------------------------------------------- | | `SELF_AGENT_PRIVATE_KEY` | No | — | Agent private key (hex). Enables identity and auth tools. | | `SELF_NETWORK` | No | `mainnet` | `mainnet` or `testnet` | | `SELF_RPC_URL` | No | Network default | Custom RPC endpoint | | `SELF_AGENT_API_BASE` | No | `https://agent-api.self.xyz` | API base URL. Override to use your own deployment. | :::note **Mainnet is the default.** Registration on mainnet requires a real passport via the Self app. Use `SELF_NETWORK=testnet` for development — testnet also requires the Self app, but you can generate mock documents within the app instead of using a real passport. ::: ## Query-Only Mode Without `SELF_AGENT_PRIVATE_KEY`, these tools work for looking up and verifying agents: | Tool | Description | | ---------------------------- | ----------------------------------- | | `self_lookup_agent` | Look up an agent by on-chain ID | | `self_verify_agent` | Verify an agent's on-chain identity | | `self_verify_request` | Verify incoming request headers | | `self_list_agents_for_human` | List agents for a human address | | `self_register_agent` | Start a registration flow | | `self_check_registration` | Poll registration status | ### Example prompts ``` Look up Self Agent ID #5 on mainnet. ``` ``` Verify if address 0x83fa4380903fecb801F4e123835664973001ff00 is a registered agent on mainnet. ``` ``` List all agents registered to 0xYourAddress on mainnet. ``` ## Full Mode With `SELF_AGENT_PRIVATE_KEY` set, additional tools become available: | Tool | Description | | -------------------------- | ----------------------------------------- | | `self_get_identity` | Get the current agent's on-chain identity | | `self_deregister_agent` | Revoke the agent's identity | | `self_sign_request` | Generate auth headers for an HTTP request | | `self_authenticated_fetch` | Make a signed HTTP request | ### Example prompts ``` Register me as a Self Agent on mainnet. I'll scan my passport to prove I'm human. ``` ``` Sign an HTTP POST request to https://api.example.com/data with body {"query": "test"}. ``` ``` Make an authenticated request to https://api.example.com/protected. ``` ## Claude Code Plugin (guided workflows) For Claude Code specifically, the repo also ships a **plugin** that adds six skills. Each skill is a self-contained knowledge module (decision trees, code examples, reference docs) that loads automatically when your request matches, giving Claude full protocol context without manual setup. ```bash # Clone the repo, then add the plugin from the local checkout git clone https://github.com/selfxyz/self-agent-id.git claude plugin add ./self-agent-id/plugin ``` | Skill | Covers | | ------------------------ | --------------------------------------------------------------------------------------------- | | `self-agent-id-overview` | Architecture, contracts, trust model, ERC-8004, provider system | | `register-agent` | Registration in every mode (linked, wallet-free, ed25519, ed25519-linked, privy, smartwallet) | | `sign-requests` | ECDSA request signing, the 3-header auth system, signed-fetch patterns | | `verify-agents` | On-chain verification, `SelfAgentVerifier` middleware, reputation, freshness, sybil detection | | `query-credentials` | ZK-attested credentials, A2A agent cards, reputation scores | | `integrate-self-id` | End-to-end integration: agent-side, service-side, on-chain gating, MCP setup | The plugin and the MCP server are complementary: the plugin teaches Claude the protocol, while the MCP server gives it live tools to act on-chain. ## Agents without MCP support Frameworks that cannot run an MCP server (LangChain, AutoGPT, custom runtimes) do not need it. The [REST API](/docs/agent-id/rest-api/) and [A2A JSON-RPC endpoint](/docs/agent-id/rest-api/#a2a-protocol-json-rpc) at `https://agent-api.self.xyz` expose registration, verification, lookup, and deregistration directly over HTTP, so any agent can drive the full lifecycle with plain requests. ## Resources The server exposes two MCP resources: | URI | Description | | ----------------- | ------------------------------------------------ | | `self://networks` | Contract addresses, chain IDs, and RPC URLs | | `self://identity` | Current agent's on-chain identity (requires key) | ## Integration Prompt The server includes a built-in prompt for generating verification middleware: ``` Use the self_integrate_verification prompt with Express to generate verification middleware. ``` This generates framework-specific code using `SelfAgentVerifier` for Express, FastAPI, Flask, or Axum. ## Example Workflows ### Register and verify 1. "Register me as a Self Agent on mainnet" 2. Scan passport when prompted 3. "Check my registration status" 4. "What's my agent identity?" ### Verify a peer 1. "Is agent 0x83fa... registered on mainnet?" 2. "What credentials does Agent ID #5 have?" ### Build a gated API 1. "Use the self_integrate_verification prompt to generate Express middleware" 2. Customize the generated code for your routes ## Next Steps - [MCP Server Repository](https://github.com/selfxyz/self-agent-id-mcp) - [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/)