Skip to content

Get started with the MCP Server

Prerequisites

Before you connect to the DomainTools MCP Server, you need the following:

Your own MCP-compatible client

DomainTools provides the MCP Server, but you must bring your own MCP-compatible LLM client. The client must support:

The server also exposes two MCP Resources (docs://usage-guide and docs://field-reference) that provide your AI client with built-in guidance on tool usage and response interpretation. Clients that support MCP Resources will load these automatically.

Tested clients: The following clients have been tested and confirmed to work with the DomainTools MCP Server:

Other clients: Any MCP-compatible client that meets the requirements above should work, even if not explicitly listed. See the MCP clients directory for a community-maintained list. If you encounter issues with a specific client, contact your DomainTools representative.

DomainTools API credentials

You must be provisioned for the DomainTools MCP Server, plus the DomainTools products you want to use. The available tools depend on your account entitlements:

  • Iris Investigate — required for domain lookup, pivot, evaluate, and history tools
  • Farsight DNSDB — required for passive DNS tools

To get provisioned, contact your DomainTools representative or email enterprisesupport@domaintools.com. Validate your account credentials and product access at your account dashboard.

Network access

Your client must be able to connect to the hosted MCP Server endpoint at https://api.domaintools.com/v1/mcp.

The MCP Server is fully hosted — there are no server-side components to install or manage. You only need a compatible MCP client on your local machine.

Set up your client

This section shows you how to connect your MCP-compatible client to the DomainTools MCP Server. The process is similar for other clients not listed in the examples below.

Understand authentication

The DomainTools MCP Server authenticates requests using an X-Api-Key HTTP header. During the MCP initialize handshake, the server validates your API key by making a request to the DomainTools /v1/account endpoint.

Store your API key in an environment variable rather than hardcoding it in configuration files. This prevents accidental exposure in version control and makes it easier to rotate keys:

export DOMAINTOOLS_API_KEY="your-api-key"

Connect your client to the server

Add the DomainTools MCP Server to your MCP client configuration. The exact steps vary by client, but all require the server URL and your API key.

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

The VS Code, Cline, and Gemini 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.

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

Configure VS Code with GitHub Copilot

VS Code 1.99 and later includes built-in MCP support through GitHub Copilot. 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.

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

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

Configure 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 that the connection works

After adding the server, verify that the tools are available:

  1. Start a new conversation in your MCP client
  2. Ask: "What tools are available?"
  3. Confirm you see tools listed, including lookup_single, lookup_bulk, evaluate, pdns_lookup_rrset, and registration_history

Try a domain lookup:

Look up threat intelligence for example.com using the lookup_single tool

The response includes comprehensive domain data including risk score, registration details, DNS records, and more.

Troubleshooting

If you have trouble connecting to the MCP Server or using its tools, check these common issues.

401 Unauthorized

An HTTP 401 response indicates your API key is missing or invalid. Verify your key at your account dashboard and confirm you're passing it correctly in the X-Api-Key header.

403 Forbidden

An HTTP 403 response indicates your API account is not authorized for the requested product. Each tool category requires its own product entitlement (see API credentials). Contact your DomainTools representative to verify your account entitlements.

Tools not appearing in your client

  • Confirm your client supports Streamable HTTP transport. Clients that only support the legacy SSE or stdio transports cannot connect.
  • Check that the server URL is exactly https://api.domaintools.com/v1/mcp with no trailing slash.
  • Restart your client or start a new session after adding the server configuration.

Connection timeouts

If requests time out, verify that your network allows HTTPS connections to api.domaintools.com. Corporate proxies, VPNs, and firewalls may block the connection.

Rate limiting

The MCP Server enforces a rate limit of 10 requests per second per API key, with a burst capacity of 20. If you exceed this limit, the server throttles requests.

Individual DomainTools products (Iris Investigate, DNSDB, etc.) also enforce their own rate limits and query quotas. If a tool call fails due to a product-level limit, the error message will indicate the source. Check your account dashboard for your current quota usage.