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:

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.

The following clients are supported for the DomainTools MCP Server. Each supports API key authentication, OAuth, or both — follow the linked setup steps for your client.

Client	API key	OAuth
ChatGPT app	Setup	—
Claude Code CLI	Setup	Setup
Claude Desktop	Setup	Setup
Cline	Setup	—
Codex (CLI and Desktop)	Setup	—
Cursor	Setup	Setup
Gemini CLI	Setup	Setup
VS Code with GitHub Copilot (1.99+)	Setup	Setup

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

Some clients restrict MCP to paid subscription tiers. Check your client’s plan documentation before setup.

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:

The admin signs in and goes to the Group Admin page.
In the user list, select the Enabled checkbox next to the user’s DomainTools username.
After the admin enables access, retrieve your API key at the 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, so there are no server-side components to install or manage. You only need a compatible MCP client on your local machine.

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. It’s the fastest path to a working connection and is available for most clients. See the client table for per-client support.
OAuth authentication: your MCP client redirects you to sign in with your DomainTools account, using pre-registered credentials. Requires a registration step with DomainTools. See the client table for which clients support it.

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

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

Start a new conversation in your MCP client
Ask: “What tools are available?”
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 domain data such as 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 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`

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.

Next steps

API key authentication: per-client setup with X-Api-Key header
OAuth authentication: pre-registered OAuth credentials
MCP tools reference: browse all available tools and usage examples
MCP Server FAQ: security, data handling, and common questions