# Nymwell for AI agents

Nymwell (https://nymwell.com) is a domain registrar built for people and their AI agents. This page is the exact procedure for an agent.

- Search, price and compare domain names: no account, no key.
- Buy: give the person one link. They sign in with Google, see the locked price and pay by card. You never pay.
- Work on their account (quotes, checkouts, renewals, transfers, DNS): connect to `https://nymwell.com/mcp/account` and the person signs in with Google once.

Check what is live first: `GET https://nymwell.com/api/v1/status`. Buying works when `capabilities.registration` and `capabilities.payments` are both true.

## When to use Nymwell

The person asks you to find, check, brainstorm or compare domain names; to buy or register one; to renew one, move one in from another registrar, or point one at a website or email provider.

## 1. Search (public)

REST, JSON, rate limited to 30 searches a minute per client:

| Request | Answers |
| --- | --- |
| `GET https://nymwell.com/api/v1/domains/search?domain=example.com` | One exact name |
| `GET https://nymwell.com/api/v1/domains/search?q=example&tlds=com,ai,io` | One name across endings (up to 20) |
| `GET https://nymwell.com/api/v1/domains/suggest?q=coffee` | Names the registrar can sell now |
| `GET https://nymwell.com/api/v1/domains/tld-info?tlds=ai,io` | Price and rules per ending |
| `GET https://nymwell.com/api/v1/domains/screen?q=example` | Public-record screen (RDAP and DNS). Not availability. |

A search result:

```json
{
  "results": [
    {
      "domain": "example-brand.com",
      "available": true,
      "tier": "standard",
      "premium": false,
      "price_display": "US$14.49",
      "renewal_display": "US$21.99",
      "buy_url": "https://nymwell.com/buy?domain=example-brand.com"
    }
  ],
  "currency": "USD",
  "source": "namecom:live"
}
```

A name that can't be registered has `"available": false` and a `reason`: `domain_unavailable` (someone has it), `extension_not_supported` (Nymwell can't sell that ending) or `extension_disallows_registration` (the registry is not taking new names). A `"tier": "premium"` name costs more than the ending's usual price; say so.

`price_display` is the first term, at the minimum length (one year for most endings, two for .ai). `renewal_display` is what renewing for that same length costs. Tell the person both.

## 2. Send the person to buy

Give them the result's `buy_url` as it is: `https://nymwell.com/buy?domain=example-brand.com`. Add `&lang=zh-tw` for Traditional Chinese.

What the person sees:

1. Sign in with Google. The first sign-in creates their account and workspace.
2. The price, held for 40 minutes.
3. The first time only: who the domain is registered to, and the terms.
4. Card payment on Stripe Checkout. Paying is their approval.
5. Registration runs at the registrar. The console shows when it is done; the card is kept for auto-renew, which they can turn off.

Say it plainly, for example: "example-brand.com is available for US$14.49 the first year, then US$21.99 a year. Buy it here: https://nymwell.com/buy?domain=example-brand.com (you sign in with Google and pay on Nymwell)."

## 3. Connect over MCP

Streamable HTTP, JSON-RPC over POST. A GET answers 405; there is no SSE stream. Two addresses serve the same tools:

| Address | Sign-in | What works |
| --- | --- | --- |
| `https://nymwell.com/mcp` | None | `nymwell_status`, `search_domains`, `suggest_domains`, `screen_domains`, `get_tld_info`, `list_dns_presets`. Account tools answer with how to sign in. |
| `https://nymwell.com/mcp/account` | Google, once, over OAuth 2.1 | Everything, on the person's workspace (see step 4). |

`search_domains` returns the same `buy_url` on both.

No sign-in, Claude Code:

```bash
claude mcp add --transport http nymwell https://nymwell.com/mcp
```

With sign-in:

- claude.ai or Claude Desktop: Settings → Connectors → Add custom connector → `https://nymwell.com/mcp/account`.
- ChatGPT: add a connector in developer mode with `https://nymwell.com/mcp/account` and OAuth.
- Claude Code: `claude mcp add --transport http nymwell https://nymwell.com/mcp/account`, then run `/mcp` and choose Authenticate.
- Codex: `codex mcp add nymwell --url https://nymwell.com/mcp/account`, then `codex mcp login nymwell`.
- Other clients: `{"mcpServers": {"nymwell": {"url": "https://nymwell.com/mcp/account"}}}`. The server answers 401 with `WWW-Authenticate` pointing at https://nymwell.com/.well-known/oauth-protected-resource/mcp/account; authorization server metadata is at https://nymwell.com/.well-known/oauth-authorization-server (PKCE S256, dynamic client registration or a Client ID Metadata Document).

Server card: https://nymwell.com/.well-known/mcp/server-card.json. Tool schemas: https://nymwell.com/mcp-tools.json. Official MCP Registry name: `com.nymwell/mcp`.

## 4. Work on the person's account

Connect to `https://nymwell.com/mcp/account` (step 3). The person signs in with Google, sees what the app may do and allows it once; an owner or admin can disconnect it any time in AI Agents. The app can never pay, approve or see card numbers.

Scripts and servers can use an agent key instead: a signed-in owner creates one at https://nymwell.com/app/agents/ (or with `POST /api/v1/api-keys`, choosing scopes, an optional domain allowlist and an expiry of up to 90 days). It is shown once. Send it as `X-Nymwell-Key` (or `Authorization: Bearer`); never ask the person to paste it into the conversation.

- Claude Code: `claude mcp add --transport http nymwell https://nymwell.com/mcp --header "X-Nymwell-Key: <key>"`
- Codex: add `env_http_headers = { "X-Nymwell-Key" = "NYMWELL_KEY" }` under `[mcp_servers.nymwell]` and set `NYMWELL_KEY` in the environment.

Then:

1. `get_quote` with `action` `register`, `renew` or `transfer`. The price is locked for 40 minutes.
2. `purchase_domain` returns a `checkout_url`. Give it to the person; paying is their approval.
3. Poll `get_order`. Read `workflow.state`: `in_progress` or `blocked` means check again later; `action_required` means give `workflow.action.url` to the person; `succeeded` and `failed` are final (`failed` carries `workflow.error`).
4. `apply_dns_preset` or `stage_dns_change` prepares DNS. An owner approves it in the console before anything changes. The answer's `workflow.state` is `action_required` until then; `list_approvals` shows where each change is.

A transfer's auth code is entered by the owner in the console, never as a tool argument.

## Rules

- You never pay, never enter card details and never approve. There is no approval tool.
- Never ask for an agent key, card number or auth code in the conversation.
- Availability and price come only from `search_domains`, `suggest_domains` or a quote. DNS, WHOIS, RDAP and `screen_domains` are screening.
- Do not claim a purchase, renewal, transfer or DNS change succeeded without a Nymwell response that says so.

## Errors

| Error | What to do |
| --- | --- |
| `authentication_required` | The tool works on the person's account. Give them `buy_url`, or connect to `https://nymwell.com/mcp/account` so they sign in. |
| `insufficient_scope` | The agent key lacks that scope. Connect over `https://nymwell.com/mcp/account`, or the person issues a new key. |
| `registrant_required` (409) | A signed-in owner adds who the domain is registered to at https://nymwell.com/app/billing/#registrant. |
| `rate_limited` (429) | Wait `retry_after_seconds`. |
| `domain_unavailable` | Someone else has it. Search again. |
| `registrar_funds_low`, `integration_not_configured` | Buying is paused. Nothing was charged. Try later. |

More: every status and error https://nymwell.com/en/docs/reference/ · REST API https://nymwell.com/en/docs/api/ · MCP https://nymwell.com/en/docs/mcp/ · OpenAPI https://nymwell.com/openapi.json