OAuth authentication

The DomainTools MCP Server supports OAuth 2.0 authentication with pre-registered client credentials. Your MCP client redirects you to sign in with your DomainTools account.

For clients that don't support OAuth pre-registration (Codex, Goose Desktop), see API key authentication. Cline currently uses API key authentication only.

DomainTools does not support Dynamic Client Registration. Every MCP client must be pre-registered by DomainTools before it can complete the OAuth flow.

OAuth vs API key

Both authentication modes have equal access to MCP Server tools. Choose OAuth when you want per-user sign-in tied to a DomainTools account, or when your security policy prefers token-based flows over a static header. Choose API key authentication when you want the fastest path to a working connection, or when your client isn't in the pre-registration clients list.

Before you begin

Contact your DomainTools representative or email enterprisesupport@domaintools.com to request OAuth credentials. Before you contact DomainTools:

1. Choose one or more clients from the pre-registration clients list below.
2. Identify the redirect URI for each client. See the client-specific sections for details.
3. (Optional) Propose a client name for each registration. If you don't, DomainTools generates one. The name is a human-readable label in DomainTools' registry — it identifies your entry in support requests but is not sent during the OAuth flow, so you can use the same label on both sides or diverge if needed.
4. Include the redirect URIs and any proposed client names in your request.

Email template

Copy, fill in, and send the following to enterprisesupport@domaintools.com:

Subject: MCP Server OAuth registration request

Company / account: <your DomainTools account name or group>
Primary contact:   <name, email>
MCP client(s):     <e.g. Claude Code, Claude Desktop, Cursor, Gemini CLI, VS Code>

For each client, provide:
  - Redirect URI(s) — see the client-specific sections in
    https://docs.domaintools.com/mcp/oauth/
  - Proposed client name (optional)

Notes: <anything else — SSO provider, number of users, etc.>

DomainTools will provide you with:

• The confirmed client name for your registration
• A client ID and client secret for OAuth authentication

Store the client secret like any other credential. Don't commit it to source control. See the per-client sections for guidance on keeping it out of config files where the client supports environment-variable interpolation.

Pre-registration clients

The following MCP clients support pre-registered credentials. Each has its own redirect URI format and configuration method.

The CLIENT_NAME placeholder in the examples below is a local label only — it identifies the server entry inside your client's config. The authorization server validates connections by client ID, client secret, and registered redirect URI, not by this name. Use any label you like, though matching the name DomainTools confirmed in your registration response makes support requests easier to trace.

Claude Code

Claude Code documentation

By default, Claude Code uses a random port for its redirect URI. To use OAuth with DomainTools, configure a fixed callback port so the redirect URI is consistent.

Pick a fixed port (for example, 61264) and provide the following redirect URI during registration:

http://localhost:61264/callback

Add the MCP Server with the --callback-port option:

claude mcp add CLIENT_NAME https://api.domaintools.com/v1/mcp \
  --transport http \
  --callback-port 61264 \
  --client-id CLIENT_ID \
  --client-secret CLIENT_SECRET

Replace CLIENT_NAME with the registered client name.

Claude Desktop

Claude Desktop Custom Connectors documentation

Claude Desktop uses a static redirect URI. Provide the following during registration:

https://claude.ai/api/mcp/auth_callback

Claude Desktop's Custom Connectors support pre-registered credentials via the Advanced settings section.

To configure a custom connector:

1. Open Claude > Settings > Connectors > Add custom connector.
2. Enter the registered client name in the Name field, and fill out the Remote MCP server URL field.
3. Click Advanced settings, then fill out the OAuth Client ID (optional) and OAuth Client Secret (optional) fields with the values provided by DomainTools.
4. Click Add.

To trigger the OAuth flow, click the overflow menu (⋯) next to the MCP server's name in the Connectors list and select Connect.

Cursor

Cursor documentation

Cursor uses a static redirect URI. Provide the following during registration:

cursor://anysphere.cursor-mcp/oauth/callback

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

{
  "mcpServers": {
    "CLIENT_NAME": {
      "type": "http",
      "url": "https://api.domaintools.com/v1/mcp",
      "auth": {
        "CLIENT_ID": "YOUR_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Replace CLIENT_NAME with the registered client name. Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the credentials provided by DomainTools.

Keep secrets out of version control

Cursor supports ${env:VAR} interpolation in the auth block. Export your credentials as env vars and reference them instead of pasting the secret into .cursor/mcp.json:

{
  "mcpServers": {
    "CLIENT_NAME": {
      "type": "http",
      "url": "https://api.domaintools.com/v1/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"
      }
    }
  }
}

Gemini CLI

Gemini CLI documentation

By default, Gemini CLI uses a random port for its redirect URI. To set a static redirect URI, configure the mcpServers.SERVER_NAME.oauth.redirectUri setting.

Pick a fixed port (for example, 7777) and provide the following redirect URI during registration:

http://localhost:7777/oauth/callback

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

{
  "mcpServers": {
    "CLIENT_NAME": {
      "httpUrl": "https://api.domaintools.com/v1/mcp",
      "oauth": {
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "redirectUri": "http://localhost:7777/oauth/callback"
      }
    }
  }
}

Replace CLIENT_NAME with the registered client name. Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the credentials provided by DomainTools.

VS Code

VS Code MCP documentation

MCP in VS Code is accessed through GitHub Copilot's agent mode.

Add a remote MCP server using the Command Palette's MCP Add command. VS Code prompts you for the resource URL, then generates two redirect URIs, for example:

• http://127.0.0.1:33418
• https://vscode.dev/redirect

VS Code then prompts for a client ID and client secret. Provide the generated redirect URIs during registration, then enter the credentials provided by DomainTools.

VS Code prompts for a Server ID that becomes the key in mcp.json. Because VS Code doesn't transmit this identifier during OAuth or the MCP connection, it doesn't need to match the registered client name.

Troubleshooting OAuth

In addition to the general errors documented in Get started > Troubleshooting, OAuth registrations have a few specific failure modes.

Redirect URI mismatch

The authorization server rejects the flow with an invalid_request or redirect_uri_mismatch error when the redirect URI your client sends doesn't exactly match a URI registered for your client ID. Causes:

• Host, port, path, or scheme differs by even one character (for example, http://localhost:61264/callback registered but client sends http://localhost:61265/callback).
• Claude Code or Gemini CLI fell back to a random port because the fixed-port option wasn't configured. Re-check --callback-port (Claude Code) or mcpServers.<name>.oauth.redirectUri (Gemini CLI).
• VS Code's local redirect URI was regenerated on a new machine. Send the new URI to DomainTools for registration.

Invalid client ID or secret

An invalid_client error during the token exchange means the client ID or client secret is wrong, or the secret has been rotated. To rotate or reissue credentials, contact your DomainTools representative or email enterprisesupport@domaintools.com.

Rotating or revoking a registration

There is no self-serve endpoint for rotating a client secret or decommissioning a registration. Contact enterprisesupport@domaintools.com.

Corporate proxies and SSO

If your corporate network forces HTTPS through a proxy, the OAuth redirect back to your local client may fail. Work with your network team to allow outbound HTTPS to api.domaintools.com (MCP Server) and account.domaintools.com (OAuth authorization server). Both must be reachable from the MCP client host. If your DomainTools account uses SSO, the sign-in page redirects to your identity provider before returning to the MCP client — confirm that users have active SSO sessions.

Related pages

• API key authentication — per-client setup for clients that use the X-Api-Key header (Codex, Goose Desktop, and more)
• Get started with the MCP Server — prerequisites and verification
• MCP Server tools reference — available tools and usage
• MCP Server FAQ