MCP and sign-in
Nymwell runs a hosted MCP server: 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 | Search, prices, endings, DNS presets and buy links. Account tools answer with how to sign in. |
https://nymwell.com/mcp/account | Google, once (OAuth 2.1) | Everything above, plus everything the person can do in the console, acting with their role: buying and renewing (on the saved card within the agent limits), transfers, DNS and settings, members and keys. Only a person adds the card or changes the agent limits. |
A third address, https://nymwell.com/mcp/lookup, is the read-only version listed in app directories: five lookup tools (search, suggestions, screening, domain info and endings), no sign-in, and answers that link to nymwell.com pages instead of buy links.
Connect with sign-in
- claude.ai or Claude Desktop: Customize → Connectors → + Add → Add custom connector, and paste
https://nymwell.com/mcp/account. - ChatGPT (web): Plugins → + → Add custom MCP server, with
https://nymwell.com/mcp/accountand OAuth. Business, Enterprise and Edu plans allow actions such as buying; Pro is read-only. - Claude Code: run the command below, then
/mcpand sign in in the browser. - Codex: run the commands below.
claude mcp add --transport http nymwell https://nymwell.com/mcp/account
codex mcp add nymwell --url https://nymwell.com/mcp/account
codex mcp login nymwellOther clients: {"mcpServers": {"nymwell": {"url": "https://nymwell.com/mcp/account"}}}.
The person sees a Nymwell page that names the app, the workspace and what the app may do, and allows it. Only a workspace owner or admin can. They can disconnect the app any time in AI Agents.
Connect without sign-in
claude mcp add --transport http nymwell https://nymwell.com/mcpsearch_domains returns a buy_url for every name that can be registered; the person opens it, signs in and pays. When an agent calls an account tool here, the answer says to use buy_url or connect to /mcp/account, and carries a mcp/www_authenticate challenge that ChatGPT uses to link the account.
How sign-in works
For client developers. Nymwell is its own OAuth 2.1 authorization server, issuer https://nymwell.com.
| What | Where |
|---|---|
| Protected resource metadata | https://nymwell.com/.well-known/oauth-protected-resource/mcp/account |
| Authorization server metadata | https://nymwell.com/.well-known/oauth-authorization-server |
| Authorization | https://nymwell.com/oauth/authorize (code flow, PKCE S256 required) |
| Token | https://nymwell.com/oauth/token (authorization_code, refresh_token) |
| Dynamic client registration | https://nymwell.com/oauth/clients |
| Revocation | https://nymwell.com/oauth/revoke |
- Clients identify themselves with a Client ID Metadata Document (an https
client_id) or by dynamic registration. - Send
resource(RFC 8707) ashttps://nymwell.com/mcp/account. Responses carryiss(RFC 9207). - Scope:
account. Access tokens last an hour; refresh tokens rotate and last 60 days. - Without a token,
/mcp/accountanswers 401 withWWW-Authenticate: Bearer resource_metadata="…", scope="account". - Tokens work on MCP only, never on the REST API. A grant stops working if the person who allowed it is no longer an owner or admin.
Code mode
Agents that would rather not load every tool can connect to https://nymwell.com/mcp?mode=code (or /mcp/account?mode=code signed in). It lists two tools: search_tools returns only the tools a task needs, with their schemas, and run_tools runs several in one call, passing an earlier answer on with "$0.path". Every step is an ordinary tool call with the same sign-in, scopes, limits and audit. Experimental.
Command line
For agents and people in a terminal (Claude Code, Codex, scripts), with no install:
npx nymwell lookup yourbrand --tlds all # up to 500 names, free: DNS and public registry records
npx nymwell check yourbrand.com # the registrar's answer and exact price
npx nymwell info example.com # everything public about one domain
npx nymwell tlds # every ending, with pricesWith an agent key in NYMWELL_KEY: quote, buy (the saved card within the agent limits, otherwise a payment link), order, domains, dns and transfer-in. --json prints the raw answer. Package: https://www.npmjs.com/package/nymwell · Source: https://github.com/nymwell/nymwell
In Claude Code, the Nymwell plugin teaches Claude when to use the CLI: claude plugin marketplace add nymwell/nymwell, then claude plugin install nymwell@nymwell.
Agent keys, for scripts
Scripts and servers can send an agent key instead of signing in: X-Nymwell-Key: nw_live_… or Authorization: Bearer nw_live_…. A signed-in owner creates it in AI Agents, or with POST /api/v1/api-keys (scopes, an optional domain allowlist, an expiry of up to 90 days). It is shown once. Never ask a person to paste it into a conversation.
Tools
tools/list marks each tool with securitySchemes: noauth for the public ones, oauth2 for the rest.
| Tool | Access | What it does |
|---|---|---|
nymwell_ | Public | Read Nymwell backend, database and provider-adapter readiness. |
list_ | Signed in | List domains visible to the signed-in Nymwell organization. |
list_ | Signed in | List DNS records for a managed domain. refresh: true first pulls the records from the registrar (including ones changed outside Nymwell). |
list_ | Signed in | List invoice metadata for the signed-in Nymwell organization. |
list_ | Signed in | List members and roles for the signed-in Nymwell organization. |
list_ | Signed in | Read recent immutable audit evidence for the signed-in Nymwell organization: who (person, API key, OAuth app, schedule, registrar), how (console, API, MCP) and the outcome, with a summary. Reads are left out unless include_reads is true. |
check_ | Signed in | Before a sensitive action, ask whether it can happen now. For transfer_out, renew and cancel it returns state (eligible, action_required, blocked, in_progress), reasons with a code, the source (registry, namecom, nymwell), an until date when the block ends, the next action, and what the action requires (roles, Google confirmation, approval, payment). Staging checks the same rules again. |
stage_ | Signed in | Change DNS records (create, update, delete), applied at the registrar in order. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. Values are checked first (invalid_record names the change and field). For update and delete, pass record_id from list_dns_records when a name has more than one record of that type. |
search_ | Public | The authoritative check: which domain names can be registered and what they cost, from the live registrar (not DNS or RDAP). Call it on the few names you will offer, right before get_quote; for many names, run screen_domains first (it is free and wide). Up to 20 names: exact domains, or a name plus endings. If Nymwell is not connected to a live registrar, this tool refuses sandbox data; use screen_domains for a public-record first pass. Prices are USD for the minimum term; get_quote gives the exact price for a chosen term. Each name has tier (standard or premium) when it can be registered, or reason (domain_unavailable, extension_not_supported, extension_disallows_registration) when it cannot. No sign-in needed. |
screen_ | Public | The fast lookup, for many names at once (up to 500, or one name across every ending with tlds ["all"]): taken or not from DNS and public registry records (RDAP), with registrar and expiry, parked-for-sale, and for names with no record the ending's list price and a buy_url. Costs no registrar call, so use it first and widely; it is NOT availability, so confirm the names you will offer with search_domains (the registrar's answer and exact price). If the call runs out of lookups, pending lists the names to send again. No sign-in needed. |
domain_ | Signed in | Everything public about one domain, wherever it is registered: registry record (registrar, created, expires, statuses, transfer lock, DNSSEC), DNS (nameservers and where it is hosted, A/AAAA, MX, SPF, DMARC, parked for sale), whether HTTPS answers, and the next step: a buy_url for a name with no record, or a transfer_url (and when a transfer becomes possible) for a registered one. No sign-in needed. |
get_ | Signed in | Lock the exact price for one domain: action "register" (default) for an available name, "renew" for a domain this organization holds, or "transfer" to bring one from another registrar (adds one year; the owner then submits the auth code in the console). Valid for 40 minutes; purchase_domain charges exactly this. |
purchase_ | Signed in | Buy what a quote priced (registration, renewal or transfer). You act for the person who connected you: when the workspace has a saved card and the amount is inside the agent spending limits (get_dashboard shows them), the card is charged at once and the order runs; the person is told. Otherwise (no card, over a limit, or pay_with "checkout") it returns a checkout_url and checkout_reason: give the link to the person to pay. The registrar call (and, for a registration, the DNS records you pass) then runs on its own. Poll get_order for the result. Nobody but a person can add or change the card. |
get_ | Signed in | Read where a purchase is: awaiting_payment, registering, registered, needs_attention or failed_refunded, with the DNS records that were created. workflow.state says what to do: in_progress or blocked = check again later; action_required = give workflow.action.url to the person; succeeded or failed = stop (failed carries workflow.error). |
list_ | Public | List the DNS presets purchase_domain and apply_dns_preset accept (Vercel, Netlify, GitHub Pages, Cloudflare Pages, Agent Lab Deploy, Google Workspace email). No sign-in needed. |
apply_ | Signed in | Add a preset's DNS records to one domain this organization manages (records that already exist are skipped). Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. undo_dns_apply takes it back. |
suggest_ | Public | Names a live registrar can sell now that fit a keyword, with prices (registration inventory only). Sandbox suggestions are refused; use screen_domains until nymwell_status reports a live registrar. No sign-in needed. |
get_ | Public | What an ending costs (registration, renewal, transfer) and its rules: allowed terms, days left to renew after expiry, WHOIS privacy, DNSSEC, HSTS preload. Pass up to 10 tlds for live answers, or none for every ending Nymwell sells (the same list as https://nymwell.com/tlds.json). No sign-in needed. |
get_ | Signed in | Live state of a domain this organization holds through Nymwell: expiry, renewal price, transfer lock, WHOIS privacy, registry locks, nameservers, contact verification and any transfer in progress. |
set_ | Signed in | Turn Nymwell's auto-renew on or off for a domain. When it is on and the workspace has a saved card, Nymwell charges that card for a one-year renewal from 14 days before expiry (retrying 7, 3 and 1 day before); without a card it sends reminders instead. The answer says which applies. The registrar's own auto-renew always stays off. |
update_ | Signed in | Change WHOIS privacy or the transfer lock. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. |
set_ | Signed in | Change nameservers: 2 to 13 hostnames, or "default" to return to Nymwell DNS. Pointing elsewhere means the records in Nymwell stop applying. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. |
set_ | Signed in | Change contacts. registrant is required (it is the legal holder); admin, tech and billing are optional. A new registrant must confirm by email within 15 days or the domain stops resolving. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. |
request_ | Signed in | Unlock a domain and get its transfer auth code, to move it to another registrar. When applied, the code is in the result (shown once; owners get a notice). Not possible within 60 days of a registration or transfer. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. |
cancel_ | Signed in | Cancel a registration made in the last few days (the registry's add grace period, about 5 days): the domain is deleted and the payment refunded. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. |
list_ | Signed in | Read DNSSEC DS records, URL forwarding, email forwarding or branded (vanity) nameservers for a domain, live from the registrar. |
change_ | Signed in | Change DNSSEC, URL forwarding, email forwarding or a vanity nameserver. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. data: dnssec {key_tag, algorithm, digest_type, digest} (delete: digest); url_forwarding {host, forwards_to, type: masked/redirect/302, title?, meta?} (delete: host); email_forwarding {email_box, email_to} (delete: email_box); vanity_nameservers {hostname, ips} (delete: hostname). |
list_ | Signed in | Transfers into Nymwell for this organization and where each one is. |
cancel_ | Signed in | Cancel a transfer: direction "in" stops one coming to Nymwell (the payment is refunded), "out" stops a domain leaving for another registrar. Applies at once when you act for an owner or admin and the workspace lets agents apply changes (the default); otherwise it waits in list_approvals. workflow.state says which. |
list_ | Signed in | Registrant emails still waiting for ICANN verification on this organization's domains, with the deadline. A domain whose registrant misses it stops resolving. |
get_ | Signed in | Whether this organization has its registrant on file, and its details. The customer is the legal holder of every domain; save_registrant sets it and accepts the registration terms for the person you act for, before the first registration or transfer. |
list_ | Signed in | Changes waiting for approval, and the ones already decided, each with workflow.state (action_required, in_progress, succeeded, failed). decide_approval approves or rejects one when you act for an owner or admin. |
resend_ | Signed in | Send the ICANN verification email again for one verification_id from list_unverified_contacts. |
get_ | Signed in | One look at the workspace: domain counts, what needs attention, recent notices, whether a card is saved, and the agent policy (do your changes apply at once, and how much you may charge to the saved card per order and per 30 days). |
list_ | Signed in | Recent orders (registrations, renewals, transfers) with status, amount, how they were paid and by whom. |
submit_ | Signed in | Start a transfer in: give the auth code from the current registrar. Nymwell seals the code at rest, checks the name is held elsewhere, and returns a transfer quote; then call purchase_domain with its quote_id. A name nobody holds returns domain_not_exists (register it instead). |
check_ | Signed in | Checks, read-only. kind "dns": website, www, email (MX/SPF/DKIM/DMARC) and DNSSEC findings with one-step fixes. kind "ssl": does HTTPS work, which certificate authorities issued certificates (certificate transparency logs), CAA suggestions. kind "transfer": can these names (domains, up to 20) move to Nymwell now, grouped ready / needs action / not possible, with reasons. |
track_ | Signed in | Track a domain registered elsewhere (expiry, registrar, DNS) without moving it. Nymwell reads public registry data daily and reminds you before it expires. |
apply_ | Signed in | Apply a DNS preset (list_dns_presets) or a saved template (tpl_…) to up to 100 domains at once; existing records are skipped. dry_run: true shows what each domain would get. Applies at once when you act for an owner or admin and the workspace lets agents apply changes. |
undo_ | Signed in | Take back the records the last preset or template added to a domain (only those still there). |
dns_ | Signed in | Saved DNS templates. action "list"; "save" with name and records (or from_domain to copy a domain's records); "delete" with id. |
dns_ | Signed in | action "export": the domain's records as a BIND zone file. action "import": a zone file becomes one change set of creates and deletes (dry_run: true only shows the plan). |
set_ | Signed in | Write a note on one DNS record (what it is for), shown next to it in the console. Empty note clears it. |
set_ | Signed in | Add or remove tags on up to 500 domains at once (tags filter the domain list). |
domain_ | Signed in | The domain's own page: "for_sale" (price, minimum offer, offers reach the owner) or "parked". action "get" shows it and the offers; "save" turns it on or off (enabled) and changes mode, price_minor, min_offer_minor, headline or message; fields left out keep what is saved. |
managed_ | Signed in | The optional Managed Domain plan (managed DNS, SSL for secure redirects, renewal management; yearly on the saved card). action "get" shows price, status and the consent text; "enable" charges the first year (send accept_charge: true after the person agreed to the consent text; within the agent spending limits); "disable" stops renewal (no refund). |
workspace_ | Signed in | What every new domain starts with: auto_renew, transfer_lock, privacy, dns_preset {preset, target}, forward_to, tags. action "get"; "save" (fields left out keep what is saved); "apply" puts them on the given domains now. |
domain_ | Signed in | Move a domain to another Nymwell workspace (it stays at the registrar). action "list" (incoming and outgoing); "request" with domain and to_email (an owner or admin there accepts within 5 days; possible 10 days after registration); "accept" or "decline" an incoming move (id) sent to the person you act for; "cancel" an outgoing one (id). |
decide_ | Signed in | Approve or reject a change waiting in list_approvals (one prepared by a teammate or another agent). Needs the account:manage scope and an owner or admin behind you. An approved change is applied at once and recorded in the person's name, with you named. |
save_ | Signed in | Set who every new domain is registered to (the legal holder) and accept the registration terms for the person you act for. Read links from get_registrant first and tell the person. contact: firstName, lastName, companyName?, address1, address2?, city, state?, zip?, country (2 letters), email, phone (+886.912345678). Needs account:manage. |
manage_ | Signed in | action "list" members and pending invitations; "invite" email with role (admin, billing_admin, domain_manager, dns_operator, viewer). Inviting needs account:manage. |
manage_ | Signed in | API keys of this workspace. action "list" (metadata only, never secrets); "create" with name, scopes (no wider than yours), expires_in_days (1-90), optional domain_allowlist and ip_allowlist; the secret is returned once. "revoke" with id. create and revoke need account:manage. |
connected_ | Signed in | AI apps connected over OAuth. action "list"; "revoke" with id disconnects one (needs account:manage). |
contact_ | Signed in | Send Nymwell support a message (category: domain, dns, billing, transfer, account, other; optional domain). The team is alerted at once and replies to the email of the person you act for. action "notices" lists what Nymwell told the workspace (security changes, renewals, price changes). |
Schemas: https://nymwell.com/mcp-tools.json · Server card: https://nymwell.com/.well-known/mcp/server-card.json · Official MCP Registry: com.nymwell/mcp