exchangehandles-mcp

MCP server for ExchangeHandles — the AI Agent Identity Registry. Check handle availability, get AI valuations, search the marketplace, and manage agent identities across 23+ platforms.

Quick Install

npx exchangehandles-mcp

Or install globally:

npm install -g exchangehandles-mcp

Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "exchangehandles": {
      "command": "npx",
      "args": ["-y", "exchangehandles-mcp"],
      "env": {
        "EXCHANGEHANDLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "exchangehandles": {
      "command": "npx",
      "args": ["-y", "exchangehandles-mcp"],
      "env": {
        "EXCHANGEHANDLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenClaw

Add to your OpenClaw MCP configuration:

{
  "mcpServers": {
    "exchangehandles": {
      "command": "npx",
      "args": ["-y", "exchangehandles-mcp"],
      "env": {
        "EXCHANGEHANDLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "exchangehandles": {
      "command": "npx",
      "args": ["-y", "exchangehandles-mcp"],
      "env": {
        "EXCHANGEHANDLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

API Key

An API key is optional for public tools (check, appraise, search, list). It's required for agent management tools (register, claim, release).

Get your API key at exchangehandles.com/developers.

Configuration Priority

The server reads your API key from (in order):

1. Command line: exchangehandles-mcp --api-key=your-key
2. Environment variable: EXCHANGEHANDLES_API_KEY
3. Config file: ~/.exchangehandles/config.json

Config file format:

{
  "apiKey": "your-api-key-here"
}

Tools

check_handle

Check if a handle is available on a specific platform.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | handle | string | ✅ | The handle to check (e.g. "coolname") | | platform | string | ✅ | Platform ID (e.g. "twitter", "github") |

Example: "Is @nova available on Twitter?"

check_handle_all

Check handle availability across ALL 23+ platforms at once.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | handle | string | ✅ | The handle to check everywhere |

Example: "Where is the handle 'quantum' available?"

appraise_handle

Get an AI-powered valuation for a handle.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | handle | string | ✅ | The handle to appraise | | platform | string | ❌ | Single platform (use this OR platforms) | | platforms | string[] | ❌ | Multiple platforms (use this OR platform) |

Example: "How much is @crypto worth on Twitter and Instagram?"

search_handles

Search the marketplace for handles for sale or trade.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | ✅ | Search query | | platform | string | ❌ | Filter to a specific platform |

Example: "Find short 3-letter handles on GitHub"

list_platforms

List all supported platforms with IDs and descriptions.

Input: None

Returns: 23+ platforms including Twitter, Instagram, TikTok, GitHub, Reddit, Discord, Bluesky, domains, and more.

register_agent 🔑

Register a new AI agent identity. Requires API key.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agentName | string | ✅ | Name for your agent | | agentDescription | string | ❌ | What the agent does |

Example: "Register an AI agent called 'market-analyzer'"

claim_handle 🔑

Claim/reserve a handle for your agent. Requires API key.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | handleName | string | ✅ | Handle to claim | | platform | string | ✅ | Platform to claim on |

Example: "Claim @market-analyzer on Twitter for my agent"

release_handle 🔑

Release a previously claimed handle. Requires API key.

Input: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | handleId | string | ✅ | ID from the claim response |

What Can AI Agents Do?

• Brand research: Check if a name is available across all platforms before launching
• Handle valuation: Get AI-powered appraisals for handles you own or want to buy
• Marketplace discovery: Search for premium handles available for sale
• Identity management: Register AI agents and claim handles across platforms
• Portfolio analysis: Appraise multiple handles across multiple platforms

Supported Platforms

| Platform | ID | Description | |----------|-----|-------------| | Twitter / X | twitter | Social media (@handles) | | Instagram | instagram | Photo & video sharing | | TikTok | tiktok | Short-form video | | YouTube | youtube | Video platform | | GitHub | github | Code hosting & dev profiles | | Reddit | reddit | Community forums | | Snapchat | snapchat | Ephemeral messaging | | LinkedIn | linkedin | Professional networking | | Facebook | facebook | Social networking | | Pinterest | pinterest | Visual discovery | | Twitch | twitch | Live streaming | | Discord | discord | Chat & communities | | Telegram | telegram | Messaging | | Threads | threads | Text-based social | | Bluesky | bluesky | Decentralized social | | Mastodon | mastodon | Federated social | | Spotify | spotify | Music streaming | | SoundCloud | soundcloud | Audio sharing | | Medium | medium | Blogging | | Substack | substack | Newsletters | | npm | npm | Node.js packages | | PyPI | pypi | Python packages | | Domains | domains | Web domains |

Development

# Clone and install
git clone https://github.com/exchangehandles/exchangehandles-mcp.git
cd exchangehandles-mcp
npm install

# Build
npm run build

# Run locally
node dist/index.js

# Watch mode
npm run dev

Technical Details

• Transport: stdio (standard for CLI MCP servers)
• Protocol: MCP (Model Context Protocol) v2024-11-05
• Runtime: Node.js 18+ (uses built-in fetch)
• Dependencies: @modelcontextprotocol/sdk, zod (peer dep)

License

MIT