npm package: @selfxyz/mcp-server
Description: MCP server for Self Agent ID — proof-of-human identity for AI agents
Author: Self Protocol
Latest version: 0.2.0

# @selfxyz/mcp-server

> **Part of the [Self Agent ID](https://github.com/selfxyz/self-agent-id) ecosystem** — on-chain proof-of-human identity for AI agents. See the [integration guides](https://docs.self.xyz/agent-id/guides/mcp-user) for detailed MCP usage.

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

<!-- badges -->
<!-- [![npm](https://img.shields.io/npm/v/@selfxyz/mcp-server)](https://www.npmjs.com/package/@selfxyz/mcp-server) -->

## What is this?

An [MCP](https://modelcontextprotocol.io/) server that gives AI coding agents
access to [Self Agent ID](https://app.ai.self.xyz) -- 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`):

```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:

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

## Development

```bash
npm install
npm run build
npm test
```

Run in dev mode (watch):

```bash
npm run dev
```

## Links

- [Self Protocol](https://self.xyz)
- [Self Agent ID dApp](https://app.ai.self.xyz)
- [ERC-8004: Agent Registry](https://eips.ethereum.org/EIPS/eip-8004)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Self Agent ID — Main Repository](https://github.com/selfxyz/self-agent-id)
- [Integration Guides](https://docs.self.xyz/agent-id/guides/mcp-user)

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

## License

MIT