API key authentication

The DomainTools MCP Server authenticates requests using an X-Api-Key HTTP header. This page shows you how to configure supported MCP clients with your API key.

For OAuth pre-registration instead, see OAuth authentication.

For how MCP credentials compare to the Python SDK and direct API authentication, see Authentication.

Before you begin

• An MCP-compatible client (prerequisites)

• A DomainTools API key (retrieve at your account dashboard)

  Before you can retrieve a key for MCP access, your organization admin must enable your account on the Group Admin page. See DomainTools API credentials for the full delegation steps.

Store your API key in an environment variable rather than hardcoding it in configuration files. This keeps secrets out of version control and makes rotation easier. For storage trade-offs and rotation guidance, see Storing credentials securely.

export DOMAINTOOLS_API_KEY="your-api-key"

Environment variable syntax by client

Each example below references the DOMAINTOOLS_API_KEY environment variable, but the syntax varies by client:

Client	Syntax in config	Resolved by
ChatGPT app	Env var name (Headers from env)	The app
Claude Code CLI	${DOMAINTOOLS_API_KEY}	Your shell
Claude Desktop	env block (via mcp-remote)	mcp-remote
Cline	${env:DOMAINTOOLS_API_KEY}	The client
Codex CLI	env_http_headers field	The client
Cursor	${env:DOMAINTOOLS_API_KEY}	The client
Gemini CLI	$DOMAINTOOLS_API_KEY	The client
VS Code	${env:DOMAINTOOLS_API_KEY}	The client

The Cline, Cursor, VS Code, Gemini CLI, Codex CLI, and ChatGPT app examples resolve the variable at runtime, so your API key stays out of configuration files. The Claude Code CLI example uses shell expansion, so the resolved key is stored in the config, but it’s still read from the environment variable you set earlier. The Claude Desktop mcp-remote bridge stores the key as a literal string; see that section for hardening guidance.

Configure your client

Note

MCP client interfaces and configuration formats are evolving rapidly. The steps on this page are accurate as of publication and we do our best to keep them updated. If you need help, contact your DomainTools representative.

ChatGPT app

The ChatGPT desktop app has a Codex tab and a ChatGPT tab at the top; both share the same MCP configuration, so a server you add here is available across both surfaces. The app connects to a remote MCP server directly over Streamable HTTP with header-based authentication, so you can use your DomainTools API key without OAuth registration.

MCP requires a paid ChatGPT subscription (Plus or higher) and isn’t available on Free or Go accounts.

1. Open Settings > Plugins, then select the MCPs tab.
2. Click + Add server to open Connect to a custom MCP.
3. Enter a Name (for example, domaintools).
4. Set Type to Streamable HTTP.
5. In the URL field, enter https://api.domaintools.com/v1/mcp.
6. Under Headers, add a header with the Key X-Api-Key and the Value set to your DomainTools API key.
7. Click Save, then enable the server’s toggle in the MCPs list.

Leave the Bearer token env var field blank: the DomainTools MCP Server authenticates with the X-Api-Key header, not a bearer token.

Entering the key under Headers stores it in the app’s configuration. To keep the key out of that config, use the Headers from environment variables section instead, with the Key X-Api-Key and the Value DOMAINTOOLS_API_KEY (the name of the environment variable that holds your key). The app resolves the variable at connection time. Because apps launched from the macOS Dock or Finder don’t inherit your shell environment, the variable must be visible to the app; launch it from a terminal where DOMAINTOOLS_API_KEY is exported.

Claude Code CLI

Run the following command in your terminal:

claude mcp add --transport http domaintools-mcp \
  https://api.domaintools.com/v1/mcp \
  --header "X-Api-Key: ${DOMAINTOOLS_API_KEY}"

The shell expands ${DOMAINTOOLS_API_KEY} when you run the command. This adds the server to your user-level configuration. To scope the server to a specific project instead, add --scope project.

Claude Desktop

Claude Desktop’s Custom Connectors UI only accepts OAuth Client ID/Secret: there’s no field for a plain header value, so API key authentication needs a bridge. (For the OAuth path, see Claude Desktop on the OAuth page.) Editing claude_desktop_config.json directly with a url/headers shape doesn’t work either: its mcpServers block only runs local STDIO servers (command/args/env), and Claude Desktop rejects any entry shaped otherwise.

To use API key authentication with Claude Desktop, bridge through mcp-remote, a community-maintained stdio-to-HTTP proxy that Claude Desktop can run as a local process. Add the following to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "domaintools": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.domaintools.com/v1/mcp",
        "--header",
        "X-Api-Key: ${DOMAINTOOLS_API_KEY}"
      ],
      "env": {
        "DOMAINTOOLS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with the API key from your account dashboard. Restart Claude Desktop after saving the file.

mcp-remote is a third-party tool, not built or supported by DomainTools. Treat it as a workaround rather than an officially supported path; a Claude Desktop or mcp-remote update could change this behavior. The mcp-remote bridge is the only way to reach API key authentication from Claude Desktop, and it’s unsupported by both DomainTools and Anthropic.

Cline

In the Cline VS Code extension or CLI settings, add the following MCP Server configuration:

{
  "mcpServers": {
    "domaintools": {
      "disabled": false,
      "timeout": 15,
      "type": "streamableHttp",
      "url": "https://api.domaintools.com/v1/mcp",
      "headers": {
        "X-Api-Key": "${env:DOMAINTOOLS_API_KEY}"
      }
    }
  }
}

Cline resolves ${env:DOMAINTOOLS_API_KEY} from your environment when the server connects.

Codex CLI

Codex MCP documentation

Codex CLI supports environment variable indirection for header values via the env_http_headers field. This keeps the API key out of your config file.

Add the following to your ~/.codex/config.toml file:

[mcp_servers.SERVER_ALIAS]
url = "https://api.domaintools.com/v1/mcp"
env_http_headers = { "X-Api-Key" = "DOMAINTOOLS_API_KEY" }

Replace SERVER_ALIAS with any name of your choice. The value DOMAINTOOLS_API_KEY is the name of the environment variable Codex reads at runtime; make sure it’s set in your shell. See Codex MCP headers for the distinction between http_headers (static values) and env_http_headers (environment variable names).

Cursor

Add the following to your .cursor/mcp.json file:

{
  "mcpServers": {
    "domaintools": {
      "url": "https://api.domaintools.com/v1/mcp",
      "headers": {
        "X-Api-Key": "${env:DOMAINTOOLS_API_KEY}"
      }
    }
  }
}

Cursor resolves ${env:DOMAINTOOLS_API_KEY} from your environment when the server connects. Cursor also supports OAuth pre-registration; see Cursor on the OAuth page.

Gemini CLI

Add the following to your ~/.gemini/settings.json file:

{
  "mcpServers": {
    "domaintools": {
      "httpUrl": "https://api.domaintools.com/v1/mcp",
      "headers": {
        "X-Api-Key": "$DOMAINTOOLS_API_KEY"
      }
    }
  }
}

Gemini CLI expands $DOMAINTOOLS_API_KEY from your environment when settings are loaded. The ${DOMAINTOOLS_API_KEY} syntax also works.

VS Code with GitHub Copilot

VS Code 1.99 and later supports MCP servers through GitHub Copilot’s agent mode. Add the following to your workspace’s .vscode/mcp.json file:

{
  "servers": {
    "domaintools": {
      "type": "http",
      "url": "https://api.domaintools.com/v1/mcp",
      "headers": {
        "X-Api-Key": "${env:DOMAINTOOLS_API_KEY}"
      }
    }
  }
}

VS Code resolves ${env:DOMAINTOOLS_API_KEY} from your environment when the server connects.

Other clients

Most MCP clients use a JSON configuration with the same core fields. If your client isn’t listed above, adapt this general pattern and replace YOUR_API_KEY with the API key value from your account dashboard:

{
  "mcpServers": {
    "domaintools": {
      "url": "https://api.domaintools.com/v1/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Common variations between clients include the top-level key name (mcpServers vs servers), the transport type field (type, transport), and the URL field (url vs httpUrl). Check your client’s documentation for the exact format and whether it supports environment variable interpolation.

Verify the connection

See Verify that the connection works on the Get Started page.

Related pages

• Get started with the MCP Server: prerequisites and verification
• OAuth authentication: pre-registered OAuth credentials for Claude Code, Claude Desktop, Cursor, Gemini CLI, VS Code
• MCP Server tools reference
• MCP Server FAQ