# Namedesk MCP server: free domain statistics, no key

This is the official Namedesk MCP server. Ask your AI assistant how big a TLD is, which registrars are largest or where the 2026 round stands, and it answers from Namedesk. Give it your team's API key and it can also read your appraisals and start new ones, with every price stated before it spends.

## Connect

The server is at `https://api.namedesk.app/mcp` (Streamable HTTP). Statistics need no key. For your team's appraisals and wallet, send your API key as `Authorization: Bearer <key>`; create one in [Settings -> API keys](https://namedesk.app/settings/api-keys).

Claude Code, statistics only:

```bash
claude mcp add --transport http namedesk https://api.namedesk.app/mcp
```

Claude Code, with your team's key:

```bash
claude mcp add --transport http namedesk https://api.namedesk.app/mcp \
  --header "Authorization: Bearer $NAMEDESK_API_KEY"
```

Cursor, and other clients that take a JSON configuration:

```json
{
  "mcpServers": {
    "namedesk": {
      "url": "https://api.namedesk.app/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}
```

Leave out the key to use the statistics alone.

## Tools

| Tool | What it does | Key | Credits |
|---|---|---|---|
| `getStatsSummary` | The domain industry at a glance | No | Free |
| `listStatsTlds` | List TLDs | No | Free |
| `getStatsTld` | Get a TLD | No | Free |
| `listStatsTldMonths` | A TLD's months | No | Free |
| `listStatsRegistries` | List registry operators | No | Free |
| `getStatsRegistry` | Get a registry operator | No | Free |
| `listStatsRegistrars` | List registrars | No | Free |
| `getStatsRegistrar` | Get a registrar | No | Free |
| `getStatsGroup` | Get a company | No | Free |
| `getStatsDropCatch` | Drop catching in .com by year and half-year | No | Free |
| `getStatsRound` | The 2026 round | No | Free |
| `listStatsStrings` | List 2026 round strings | No | Free |
| `getStatsString` | Get a 2026 round string | No | Free |
| `getWallet` | Get current credit balance | Yes | Free |
| `getLatestReport` | Get the most recent report for a domain | Yes | Free |
| `getDomainPricing` | Get a domain's price bands | Yes | Free |
| `getResearchJob` | Get research job status | Yes | Free |
| `createResearchJob` | Appraise domains | Yes | 10 per domain |
| `createQuickResearchJob` | Quick-read domains | Yes | 1 or 10 per domain |
| `rerunDomain` | Re-appraise one domain | Yes | 10, or 1 or 10 with `quick` |
| `cancelResearchJob` | Cancel a research job | Yes | Returns unspent credits |

Each tool takes the same inputs as its API operation, and the [API reference](https://namedesk.app/docs/api) describes every field it returns.

## Spending credits

Reading never spends credits. Three tools start appraisals and draw on your team's wallet, the same one the dashboard uses: `createResearchJob`, `createQuickResearchJob` and `rerunDomain`. Each states its price in its description, so your assistant can tell you the most a request will cost and ask before it runs.

Two inputs protect the wallet. `max_credits` is the most you agreed to spend: a request that could cost more is refused, and nothing is charged. For a job, set it to at least 10 times the number of domains; for a rerun, at least 10. `idempotency_key` is a new value for each request. A retry with the same key returns the first answer and is never charged twice, as long as the request is the same; a different request under a used key is refused. A key belongs to the API key that sent it: the same value sent with another of your team's API keys is a separate request.

In a job, domains your team has already appraised come back with their existing report at no cost. A rerun always runs a fresh appraisal and always charges, even for a domain your team has appraised before.

## Limits and errors

The statistics tools share the Stats API's limits: 120 requests a minute per address without a key, 600 with one. Errors come back as tool results in the API's own shape, with an `error` code, a `message` and a `request_id`, so your assistant can read them and correct its request. Quote the request id when asking for help.
