Skip to content

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

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:

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
Claude Code CLI ${DOMAINTOOLS_API_KEY} Your shell
VS Code / Cline ${env:DOMAINTOOLS_API_KEY} The client
Gemini CLI $DOMAINTOOLS_API_KEY The client
Codex CLI env_http_headers field The client
Codex Desktop Not supported Stored as literal
Goose Desktop Not supported Stored as literal

The VS Code, Cline, Gemini CLI, and Codex CLI 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. Codex Desktop and Goose Desktop don't support env var interpolation; see the relevant sections for hardening guidance.

Configure your client

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.

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.

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.

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).

Codex Desktop

Codex Desktop stores header values entered in its UI as literal strings — no environment variable indirection. Enter your API key directly:

  1. Open Codex > Settings > MCP servers > Add server.
  2. Select the Streamable HTTP tab.
  3. Fill out the MCP server name and URL fields.
  4. Add a header with the Key X-Api-Key and the Value YOUR_API_KEY.
  5. Click Save.

Replace YOUR_API_KEY with the API key provided by DomainTools.

Goose Desktop

Goose documentation

Goose Desktop stores extension header values as literal strings — no environment variable indirection. To integrate the DomainTools MCP Server, configure a custom extension:

  1. Open Extensions > Add custom extension.
  2. Change the Type to HTTP.
  3. Fill out the Extension Name and Endpoint fields.
  4. Add a request header with the Header Name X-Api-Key and the Value YOUR_API_KEY.
  5. Click Add Extension.

Replace YOUR_API_KEY with the API key provided by DomainTools.

Goose stores extension settings in ~/.config/goose/config.yaml. Restrict file permissions to owner-only:

chmod 600 ~/.config/goose/config.yaml

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.