MCP server setup

The DomainCare MCP server lets AI assistants interact with your DomainCare account through the Model Context Protocol. List domains, trigger rechecks, pause/resume monitoring, view events, and more — all from Claude, Cursor, or any MCP-compatible tool.

There are two ways to connect:

• Hosted server (recommended) — point your client at https://domaincare.io/api/mcp and sign in with OAuth: click Connect, approve in the browser, done. No API key, no config file for most clients. Best for Claude Desktop, Claude Code, Claude.ai, Cursor, and Codex. An API key remains available as a headless/CI fallback.
• Local npm package — run domaincare-mcp as a local process via npx. Use this if you prefer a local process or need the extended tool set (status pages, per-check overrides).

Prerequisites

• A DomainCare account with an active paid plan
• For the OAuth path (recommended): nothing else — you sign in through the browser, no key required
• For headless setups only: an API key (create one at Settings → API Keys)

Option A — Hosted server (recommended)

Connect to the hosted endpoint at:

https://domaincare.io/api/mcp

The easiest path is OAuth. Point your client at that URL and it discovers the sign-in flow automatically: a browser window opens, you sign in with your DomainCare account, approve the scopes, and you're connected — no API key, no token to paste. The consent screen requests mcp:read, mcp:write, and mcp:full scopes; approve only what your use case needs.

Pick your client below. If you can't use a browser (CI, headless, a shared server), skip to Headless setup with an API key.

Claude Desktop

1. Open Settings → Connectors → Add custom connector
2. Fill in:
   • Name: DomainCare
   • Remote MCP server URL: https://domaincare.io/api/mcp
3. Click Connect — a browser window opens
4. Sign in to DomainCare and approve the access request
5. Done — no config file or API key needed

Custom connectors are generally available on Claude Desktop and Claude.ai. As of mid-2026, the Free plan allows one custom connector and Pro/Max allow unlimited — see Anthropic's plan comparison for current limits.

Claude Code

Add the server without an API key so it uses OAuth (omit --header):

claude mcp add --transport http domaincare https://domaincare.io/api/mcp

Then start a session, run /mcp, select domaincare, and choose Authenticate — a browser opens for sign-in and consent. After approving, claude mcp list shows domaincare ✓ Connected.

Add --scope user to the command to make the server available across all your projects (the default is the current project only).

Cursor

Add the server with just a URL (no headers block) to ~/.cursor/mcp.json (global) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "domaincare": {
      "url": "https://domaincare.io/api/mcp"
    }
  }
}

Because there's no token in the config, Cursor treats the server as OAuth-protected: open Settings → MCP (Tools & Integrations), and when DomainCare shows Needs login, click it to sign in via the browser. Cursor stores the resulting credentials for you.

Codex CLI

Codex's codex mcp add command is for local stdio servers only, so add the remote server by editing ~/.codex/config.toml directly:

[mcp_servers.domaincare]
url = "https://domaincare.io/api/mcp"

Then run the OAuth login, which opens a browser to sign in and consent:

codex mcp login domaincare

Remote (Streamable HTTP) MCP support is recent in Codex — update to the latest Codex CLI if url isn't recognized. Some builds require experimental_use_rmcp_client = true at the top of config.toml to enable the remote MCP client.

Or let your AI set it up

Don't want to touch a config file? Paste this prompt into Claude Code, Cursor, Codex, or any agentic coding tool — it'll wire up the connection itself, OAuth-first.

Set up the DomainCare MCP server in this tool so you can manage my domains.

It's a hosted Streamable HTTP MCP server at: https://domaincare.io/api/mcp
It supports OAuth — prefer signing in over an API key whenever the client can.

- If you are Claude Code, run (no key — this triggers OAuth):
  claude mcp add --transport http domaincare https://domaincare.io/api/mcp
  then tell me to run /mcp → domaincare → Authenticate and sign in.
- If you are Cursor, add to its MCP config (URL only, no headers) and tell me to
  click "Needs login" in Settings → MCP to sign in:
  { "mcpServers": { "domaincare": { "url": "https://domaincare.io/api/mcp" } } }
- If you are Codex, add to ~/.codex/config.toml:
  [mcp_servers.domaincare]
  url = "https://domaincare.io/api/mcp"
  then run: codex mcp login domaincare

If the client genuinely can't do a browser sign-in, ask me for an API key instead
(from domaincare.io → Settings → API Keys; needs an active paid plan) and send it
as the "X-Api-Key" header.
Then confirm it works by calling list_domains and showing me my domains.

Headless setup with an API key

If a browser-based sign-in isn't possible — CI, a headless box, or a client that doesn't support OAuth — authenticate with an API key instead. Create one at Settings → API Keys (needs an active paid plan) and pass it via either Authorization: Bearer <key> or the X-Api-Key: <key> header.

Claude Code

claude mcp add --transport http domaincare https://domaincare.io/api/mcp \
  --header "X-Api-Key: dc_your_key_here"

Claude Desktop

Add DomainCare to your claude_desktop_config.json with the key in the headers block:

{
  "mcpServers": {
    "domaincare": {
      "url": "https://domaincare.io/api/mcp",
      "headers": {
        "Authorization": "Bearer dc_your_key_here"
      }
    }
  }
}

You can use "X-Api-Key": "dc_your_key_here" instead of the Authorization header — both work. Then restart Claude Desktop.

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If your Claude Desktop version doesn't read a remote url from the config file, bridge through the mcp-remote npm package (requires Node.js 18+):

{
  "mcpServers": {
    "domaincare": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://domaincare.io/api/mcp",
        "--header",
        "Authorization: Bearer dc_your_key_here"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "domaincare": {
      "url": "https://domaincare.io/api/mcp",
      "headers": { "X-Api-Key": "dc_your_key_here" }
    }
  }
}

Codex CLI

Store the key in an environment variable and reference it from ~/.codex/config.toml:

[mcp_servers.domaincare]
url = "https://domaincare.io/api/mcp"
bearer_token_env_var = "DOMAINCARE_API_KEY"

Option B — Local npm package

Prefer a local process? The domaincare-mcp package runs over stdio and covers the same capabilities (status pages, per-check overrides, custom domains) except pause_domain/resume_domain, which are hosted-only — see the tool table below for the naming differences. Requires Node.js 18 or later.

Install

npm install -g domaincare-mcp

Or use npx without installing:

npx domaincare-mcp

Configure

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "domaincare": {
      "command": "npx",
      "args": ["-y", "domaincare-mcp"],
      "env": {
        "DOMAINCARE_API_KEY": "dc_your_key_here"
      }
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Add to your project's .claude/settings.json or global ~/.claude/settings.json:

{
  "mcpServers": {
    "domaincare": {
      "command": "npx",
      "args": ["-y", "domaincare-mcp"],
      "env": {
        "DOMAINCARE_API_KEY": "dc_your_key_here"
      }
    }
  }
}

Cursor

Open Settings > MCP Servers > Add Server and enter:

• Name: domaincare
• Command: npx -y domaincare-mcp
• Environment: DOMAINCARE_API_KEY=dc_your_key_here

Available tools

Once connected, your AI assistant has access to these tools. The Hosted column marks the tools available on the hosted server (Option A). The local npm package (Option B) covers the same capabilities, with two differences. Its status-page custom-domain tools are named get_custom_domain, add_custom_domain, verify_custom_domain, and remove_custom_domain — attach and verify as separate steps, calling the same API endpoints as the hosted get_/set_/delete_status_page_custom_domain tools below. And it does not include pause_domain/resume_domain, which are hosted-only.

The hosted server is now at full parity with the REST API — every API capability has a matching MCP tool.

Recommended scope

With OAuth, you choose scopes on the consent screen each time you connect — grant mcp:read for a query-only assistant, add mcp:write to let it add domains and tune checks, and only approve mcp:full if you specifically need destructive tools like delete_domain. Approve the least you need.

With an API key (headless setup), the key's scope sets the ceiling: create a Read only key for a query-only assistant, a Read + Write key to let it add domains, and Full access only if you need delete_domain.

Verify it works

After configuring, ask your AI assistant:

"List my DomainCare domains"

You should see your domains returned. If you get an authentication error, re-run the OAuth sign-in (Claude Code: /mcp → Authenticate; Cursor: Needs login; Codex: codex mcp login domaincare) — or, for a headless setup, verify your API key is correct. Either way, confirm your subscription is active.

Environment variables

Troubleshooting

"DOMAINCARE_API_KEY is required" — The server could not find your API key. Make sure the env block in your MCP configuration includes the key.

401 errors — Your API key may be expired or revoked. Create a new key at Settings > API Keys.

403 errors — API access requires a paid plan. Free trial accounts cannot use the API or MCP server.

Tool not showing up — Restart your AI tool after changing the MCP configuration. Some tools require a full restart to pick up new servers.

OAuth sign-in didn't open or expired — Re-trigger it: in Claude Code run /mcp → domaincare → Authenticate; in Cursor click Needs login under Settings → MCP; in Codex run codex mcp login domaincare. Make sure you're signing in to the DomainCare account whose organization owns the domains, and that its plan is active.