custom-domain-mcp

An MCP server for the Custom Domain API. It lets an AI assistant (Claude, Cursor, any MCP client) register your customers' hostnames, show them their DNS records, check why a domain isn't live yet, and recheck or delete it. It acts as one application, with that application's own API key.

Setup

uvx custom-domain-mcp        # or: pip install custom-domain-mcp

It reads two settings from the environment:

Claude Code:

claude mcp add custom-domain --env CUSTOM_DOMAIN_API_URL=https://edge.example.net \
  --env CUSTOM_DOMAIN_API_KEY=cd_... -- uvx custom-domain-mcp

Claude Desktop, Cursor and other clients (mcpServers in their config):

{
  "mcpServers": {
    "custom-domain": {
      "command": "uvx",
      "args": ["custom-domain-mcp"],
      "env": {
        "CUSTOM_DOMAIN_API_URL": "https://edge.example.net",
        "CUSTOM_DOMAIN_API_KEY": "cd_..."
      }
    }
  }
}

Tools

What it can't do

• No operator actions. It never holds an operator token, only the application's key, so it can do exactly what the application's backend can.
• No webhook creation or rotation. Their responses carry the signing secret, which would end up in the assistant's conversation. Create webhooks through the API or the portal.

Customer data is data, not instructions. Hostnames, workspace references, metadata and check messages come from your application's customers and from DNS. The server tells the assistant to report them, never to follow them, and to call delete_domain only when you explicitly asked for that domain to be deleted, repeating its hostname back to you first. Your MCP client's own confirmation for destructive tools adds a second check.

The server's instructions also tell the assistant the one rule integration code must follow: select the tenant from the verified X-Custom-Domain-Assertion, never from Host (verifying requests).