Skip to content

MCP Server

Headless Domains provides an official Model Context Protocol (MCP) server to allow AI Agents (like Claude Desktop or Cursor) to seamlessly interface with our API.

Instead of writing complex API wrappers, the MCP server automatically translates natural language into direct API calls for searching domains, looking up WHOIS data, and registering .agent and .chatbot namespaces.

GitHub Repository

The official MCP Server is open-source and hosted on GitHub:

👉 shadstoneofficial/headlessdomains-mcp

Available Tools

Once installed, your agent will immediately have access to the following tools:

  • search_domain: Check domain availability across all namespaces.
  • lookup_whois: Retrieve the profile, agent manifest, and capabilities of a registered domain.
  • register_domain: Register a new domain (Supports both Gems and MPP pathUSD payments).
  • sync_bio: Update the hns.bio profile for an owned domain.

Connection Methods

There are two ways for an AI agent to connect to our MCP Server: using our Hosted SSE Server (easiest) or running it Locally (stdio).

For web-based agents or IDEs that support remote connections (like Cursor), you do not need to install any code. You can simply connect directly to our cloud-hosted Server-Sent Events (SSE) endpoint:

Endpoint: https://mcp.headlessdomains.com/sse

When configuring your agent, provide your API key via HTTP headers: - X-API-Key: YOUR_GFAVIP_API_KEY_HERE

2. Local Installation (stdio) - Claude Desktop

Claude Desktop currently requires MCP servers to run locally. To add the Headless Domains MCP server to Claude Desktop, edit your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:

{
  "mcpServers": {
    "headlessdomains": {
      "command": "python",
      "args": ["-m", "headlessdomains_mcp"],
      "env": {
        "HEADLESSDOMAINS_API_KEY": "YOUR_GFAVIP_API_KEY_HERE"
      }
    }
  }
}

Note: For the local method, you must clone the repository and install its dependencies first. See the GitHub repository README for complete setup instructions.