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:

A search result:

{
  "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:

search_domains returns the same buy_url on both.

No sign-in, Claude Code:

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

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