Skip to content
DomainTools Technical Documentation

Get started with the MCP Server

Prerequisites

Section titled “Prerequisites”

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

Your own MCP-compatible client

Section titled “Your own MCP-compatible client”

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

  • Streamable HTTP transport for MCP connections (STDIO (Standard Input/Output) transport requires the server to run as a local process on the same machine; it can’t connect to a remotely hosted service)
  • Custom HTTP headers (specifically X-Api-Key) for API key authentication, or OAuth 2.0 with pre-registered credentials
  • MCP tools

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

Section titled “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.

After provisioning, an organization admin must delegate MCP access to each user before they can connect:

  1. The admin signs in and goes to the Group Admin page.
  2. In the user list, select the Enabled checkbox next to the user’s DomainTools username.
  3. After the admin enables access, retrieve your API key at the account dashboard.

Network access

Section titled “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.

Understand authentication

Section titled “Understand authentication”

The DomainTools MCP Server supports two authentication modes:

  • API key authentication — pass your DomainTools API key in an X-Api-Key HTTP header. Works with every supported client (Claude Code CLI, VS Code, Cline, Gemini CLI, Codex, Goose Desktop) and is the fastest path to a working connection.
  • OAuth authentication — pre-registered OAuth credentials for Claude Code, Claude Desktop, Cursor, Gemini CLI, and VS Code. Your MCP client redirects you to sign in with your DomainTools account. Requires a registration step with DomainTools.

During the MCP initialize handshake, the server validates your credentials by making a request to the DomainTools /v1/account endpoint. For how MCP credentials compare to the Python SDK and direct API authentication, see Authentication.

Verify that the connection works

Section titled “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

Section titled “Troubleshooting”

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

401 Unauthorized

Section titled “401 Unauthorized”

An HTTP 401 response indicates your API key or OAuth credentials are missing or invalid. Verify your key at your account dashboard and confirm you’re passing it correctly in the X-Api-Key header, or that your OAuth registration is active.

403 Forbidden

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Next steps

Section titled “Next steps”