@selfxyz/mcp-server

Part of the Self Agent ID ecosystem — on-chain proof-of-human identity for AI agents. See the integration guides for detailed MCP usage.

MCP server for Self Agent ID -- proof-of-human identity for AI agents.

What is this?

An MCP server that gives AI coding agents access to Self Agent ID -- an on-chain registry where AI agents prove they are operated by a real, passport-verified human. Works with Claude Code, Cursor, Windsurf, Codex, and any MCP-compatible client.

Quick Start

1. Add to your MCP config

Claude Code (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "self-agent-id": {
      "command": "npx",
      "args": ["@selfxyz/mcp-server"],
      "env": {
        "SELF_NETWORK": "mainnet"
      }
    }
  }
}

2. Configure environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SELF_AGENT_PRIVATE_KEY | No | -- | Agent's private key (hex). Enables identity and auth tools. Omit for query-only mode. | | SELF_NETWORK | No | testnet | mainnet or testnet | | SELF_RPC_URL | No | Network default | Custom RPC endpoint | | SELF_AGENT_API_BASE | No | https://app.ai.self.xyz | Canonical API base URL override |

3. Use

Ask your agent to check if someone is registered:

Look up Self Agent ID #5 on testnet.

Or register your agent with proof-of-human:

Register me as a Self Agent on mainnet.
I'll scan my passport to prove I'm human.

Available Tools

| Tool | Description | Requires Key? | |------|-------------|:-------------:| | self_register_agent | Register a new agent with proof-of-human verification | No | | self_check_registration | Check whether a registration is complete | No | | self_get_identity | Get the current agent's on-chain identity | Yes | | self_deregister_agent | Revoke the agent's on-chain identity | Yes | | self_sign_request | Generate auth headers for an HTTP request | Yes | | self_authenticated_fetch | Make an authenticated HTTP request | Yes | | self_verify_agent | Verify another agent's on-chain identity | No | | self_verify_request | Verify incoming request headers | No | | self_lookup_agent | Look up an agent by on-chain ID | No | | self_list_agents_for_human | List all agents registered to a human address | No | | self_demo_verify | Test agent identity against the live demo endpoint | Yes |

"Requires Key" means the tool needs SELF_AGENT_PRIVATE_KEY to be set. Tools marked "No" work in query-only mode.

Resources

| URI | Description | |-----|-------------| | self://networks | Contract addresses, chain IDs, and RPC URLs for all supported networks | | self://identity | Current agent's on-chain identity (requires private key) |

Workflows

Register an agent

1. Call self_register_agent with the human's wallet address
2. Server returns a QR code URL -- human scans passport with Self app
3. Poll self_check_registration until verification completes
4. Agent is now registered on-chain with proof-of-human

Make an authenticated API call

1. Call self_authenticated_fetch with the target URL, method, and body
2. Server signs the request with the agent's key and sends it
3. The receiving server verifies headers using SelfAgentVerifier

Verify a peer agent

1. Call self_verify_agent with the agent's address or ID
2. Server checks the on-chain registry for valid registration
3. Returns verification status, credentials, and proof-of-human details

Build a gated service

1. Use the self_integrate_verification prompt with your web framework
2. Server generates middleware code using SelfAgentVerifier
3. Add the middleware to your API routes
4. Only registered, proof-of-human agents can access protected endpoints

Registration Modes

| Mode | Label | Key Type | Wallet Needed | Best For | |------|-------|----------|---------------|----------| | linked | Linked Agent | EVM (generated) | Yes | Developers who already have a wallet | | walletfree | Wallet-Free | EVM (generated) | No | Quick start without any wallet setup | | smartwallet | Smart Wallet | EVM (passkey) | No | Modern passkey-based authentication | | privy | Social Login (Privy) | EVM (embedded) | No | Non-crypto-native users who prefer social login | | ed25519 | Ed25519 | Ed25519 | No | Agents using Ed25519 keys (Eliza, OpenClaw, etc.) | | ed25519-linked | Ed25519 + Guardian | Ed25519 + EVM | Yes | Ed25519 agents where a human wants wallet-based control |

Cursor / Windsurf / OpenClaw

Add to your MCP configuration file:

{
  "mcpServers": {
    "self-agent-id": {
      "command": "npx",
      "args": ["@selfxyz/mcp-server"],
      "env": {
        "SELF_NETWORK": "mainnet",
        "SELF_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Development

npm install
npm run build
npm test

Run in dev mode (watch):

npm run dev

Links

• Self Protocol
• Self Agent ID dApp
• ERC-8004: Agent Registry
• Model Context Protocol
• Self Agent ID — Main Repository
• Integration Guides

Note: The @selfxyz/agent-sdk dependency will resolve from npm once published. During development, it uses a local file: reference.

License

MIT