Namefi

Namefi MCP Quickstart: Claude Code, Cursor & Windsurf

Per-editor OAuth and API-key MCP setup for Claude Code, Cursor, and Windsurf, then a five-step quickstart from a new app to a live custom domain.

Fenwei BianFenwei BianAuthorVictor ZhouVictor ZhouEditorJul 10, 2026est. 11 min read
  • ai-agents
  • guide
Share on X

You're already in the editor. The app is scaffolded, the first deploy just went out to a platform subdomain, and the only thing left before you can point people at it is a real domain. This is the quickstart for doing that registration step from the same coding agent session that built the app: exact MCP connection config for Claude Code, Cursor, and Windsurf, a condensed five-step flow, and — the part most domain guides skip — how to take the domain you just registered and point it at the deployment you just shipped. OAuth may open a browser once for authorization; the domain workflow then returns to the editor.

This guide covers three editors on purpose. If you're on OpenAI Codex, Gemini CLI, or Claude Desktop instead, How to Register a Domain with Your AI Agent on Namefi is the canonical hub with a verified setup for all six clients plus the raw REST path for anything that isn't MCP-native. Everything here connects to the same Namefi MCP server that hub documents, so nothing below contradicts it — this page is just the condensed, developer-tool-first cut through it, with a deployment step the hub doesn't cover.

Why register the domain inside the editor

"Go register a domain" is a context switch with an unusually high cost for a five-minute task: leave the editor, open a registrar's site, run a name search, sit through an upsell funnel for privacy protection and email hosting you didn't ask for, pay, then come back and figure out what DNS records to add.

The alternative is to let the same agent that scaffolded the project and wired up the deploy handle the last mile too: check the name, register it, and wire the DNS, all as tool calls inside the conversation you're already having. Cloudflare markets a version of this same idea for its own Registrar API — proof this isn't a niche preference but a workflow more than one registrar is building toward. The comparison section near the end covers the Cloudflare angle specifically; Namefi's version adds a tokenized-domain option and a wallet-signed payment path with no account at all, covered in Pay for Domains with a Crypto Wallet.

Set up the connection: three editors, three config files

All three editors below connect to https://api.namefi.io/mcp over Streamable HTTP. The current server advertises two authentication paths: OAuth 2.1 authorization code with PKCE (plus dynamic client registration) and a Namefi API key in the x-api-key header. Prefer OAuth when the client supports it and you do not already have a key; use a key for explicit header-based or automated setups.

One current-behavior caveat matters for this quickstart. Namefi's discovery descriptor says read-only tools need no authentication, but an unauthenticated MCP initialize request returned 401 Unauthorized when this article was verified on July 14, 2026. A client must initialize the MCP session before it can call even a read-only tool, so treat the live endpoint as authentication-required until the server behavior or descriptor changes.

Claude Code

For OAuth, add the server without a static authentication header:

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

Claude Code can also start the OAuth flow from /mcp inside an interactive session. Its documentation says a 401 or 403 marks the remote server as needing authentication; follow the browser authorization steps. For API-key authentication instead, add the custom header:

claude mcp add --transport http namefi https://api.namefi.io/mcp --header "x-api-key: YOUR_KEY"

Run only the authentication variant you intend to use. For the key command, replace YOUR_KEY with the real key and avoid committing it. By default Claude Code writes the server at local scope — available to you, in this project only. Add --scope user to make it available across every project on your machine, and confirm the connection with claude mcp list.

Cursor

Cursor reads MCP servers from mcp.json — a project copy at .cursor/mcp.json, or a global copy at ~/.cursor/mcp.json. Cursor documents OAuth support for Streamable HTTP servers. For OAuth, configure only the URL, enable the server, and complete the interactive authentication prompt:

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

For API-key authentication, Cursor's documented remote-server shape supports headers with environment-variable interpolation, so the key itself does not have to live in the file:

{
  "mcpServers": {
    "namefi": {
      "url": "https://api.namefi.io/mcp",
      "headers": {
        "x-api-key": "${env:NAMEFI_API_KEY}"
      }
    }
  }
}

${env:NAMEFI_API_KEY} resolves from whatever that variable holds in the shell that launched Cursor — export it before opening the editor. If an OAuth-capable server remains in a “Needs authentication” state, use Cursor's MCP settings to start the authorization flow; client-version and Remote SSH behavior can differ, so keep the API-key configuration as a fallback.

Windsurf (Cascade)

Windsurf's MCP integration — branded Cascade — reads ~/.codeium/windsurf/mcp_config.json. Current Cascade documentation says Streamable HTTP supports OAuth. Start with a URL-only entry and complete authorization from the MCP settings UI:

{
  "mcpServers": {
    "namefi": {
      "serverUrl": "https://api.namefi.io/mcp"
    }
  }
}

For API-key authentication, add the header through environment interpolation:

{
  "mcpServers": {
    "namefi": {
      "serverUrl": "https://api.namefi.io/mcp",
      "headers": {
        "x-api-key": "${env:NAMEFI_API_KEY}"
      }
    }
  }
}

One thing worth flagging: as of this guide's publish date, docs.windsurf.com/windsurf/cascade/mcp redirects to docs.devin.ai/desktop/cascade/mcp — Windsurf's docs now live under Cognition's Devin product-docs domain, and the config format above is what that current page documents. If you're on an older build, verify field names against whichever docs link your version's in-app help points to.

The five-step quickstart: new app to live DNS

Once one of the connections above is live, the rest of the flow is the same regardless of which editor you're in.

  1. Choose authentication. Use the editor's OAuth flow, or generate an API key on the Namefi API Keys page and keep it outside version control.
  2. Connect and authenticate using the matching config above. Then sanity-check it: ask "check whether <yourapp>.com is available on Namefi, and tell me which tool you called." checkAvailability is read-only and does not spend funds, but the MCP session currently still requires authentication to initialize.
  3. Register. Confirm a name and duration in plain language — "register it for one year." The agent submits registerDomain and polls the order until it reaches SUCCEEDED (or a terminal failure state); a typical registration finishes in a handful of poll cycles.
  4. Point it at your deploy. This is the step the next section covers in detail — add the DNS records your hosting platform asks for, through the same conversation.
  5. Verify it resolves. DNS propagation isn't instant, so give it a few minutes, then confirm with a public DNS lookup or by just loading the domain in a browser.

Point the fresh domain at what you just deployed

This is the part a generic "how to register a domain" guide never gets to, because it happens after registration, on the hosting platform's side — but it's the actual point of doing this inside the editor: your agent already knows which platform it deployed to and can wire the DNS in the same breath as the registration.

Vercel

Vercel's own domain docs walk through the flow from Settings → Domains in your project dashboard: add the domain, and Vercel tells you which record to create depending on whether it's an apex domain or a subdomain. For an apex domain (yourapp.com), Vercel asks for an A record pointing at its serving IP; for a subdomain (www.yourapp.com), it asks for a CNAME, and — worth knowing before you copy an example from an older guide — Vercel's docs are explicit that this CNAME target is unique per project, shown to you in the dashboard rather than a single fixed hostname every project shares.

With that value in hand, the DNS side is one more agent request:

"Add an A record for @ pointing to 76.76.21.21, and a CNAME for www pointing to the CNAME target Vercel gave me."

That calls createDnsRecord twice — once per record — the same DNS record tool used for any DNS write on Namefi. The trailing-dot rule applies here same as anywhere: rdata for a CNAME target needs a trailing dot, the zoneName (your domain) doesn't.

Cloudflare Pages

If your deploy target is Cloudflare Pages, the record path depends on whether you attach a subdomain or the apex. For a subdomain such as app.yourdomain.com whose DNS remains with another provider, Cloudflare's custom-domain documentation uses one CNAME pointing to your project's .pages.dev hostname. First add that exact subdomain under Workers & Pages → your project → Custom domains → Set up a domain; then create the CNAME at your DNS provider.

"Add a CNAME for app pointing to my-project.pages.dev."

For an apex domain such as yourdomain.com, Cloudflare documents a different requirement: add the domain as a Cloudflare zone and point the registrar's nameservers to the assigned Cloudflare nameservers. A CNAME at an external DNS provider is not the documented apex setup. In that case, the agent can help with registrar nameserver configuration only if the current Namefi tooling supports that operation; createDnsRecord alone is not a substitute. For the subdomain path above, it is the same DNS-record tool call and trailing-dot rule on the target as elsewhere.

How this compares to Cloudflare's in-editor registration

Cloudflare is the other registrar actively marketing an in-editor angle, worth naming directly. Its Registrar API, reported in beta as of April 2026, also integrates with MCP-capable editors including Cursor and Claude Code, letting an agent search, price, and register a domain synchronously without leaving its current context — the same core idea this guide walks through for Namefi. The same report notes that, at beta, Cloudflare's API doesn't yet cover post-registration management like transfers and renewals, planned for later in 2026.

Namefi's MCP server covers the full lifecycle today — registration, DNS, auto-renew — plus two things Cloudflare's path doesn't have: the domain registers as a tokenized-domain NFT by default (redirectable to any wallet), and it supports a wallet-signed checkout with no Namefi account at all, detailed in Pay for Domains with a Crypto Wallet. Both are building toward the same "don't leave the editor" workflow; which fits depends on whether you want a standard registration or one that's also an on-chain asset.

Frequently Asked Questions

Does this cover Codex or Gemini CLI too?

Not here — this guide is deliberately scoped to Claude Code, Cursor, and Windsurf. How to Register a Domain with Your AI Agent on Namefi has the same exact, verified config for Codex CLI, Gemini CLI, and Claude Desktop.

Do I need a Namefi account before I can try this?

You need an authenticated MCP session before the current live endpoint will initialize. Use OAuth, or provide an API key. The availability call itself is read-only and does not require funds, but do not rely on the discovery descriptor's unauthenticated-read claim until it matches live behavior.

What if my deployment platform isn't Vercel or Cloudflare Pages?

The pattern holds everywhere: your platform's dashboard tells you which DNS record type it needs — almost always an A record for an apex domain, a CNAME for a subdomain — and you hand that value to your agent to write via createDnsRecord.

Is the domain automatically tokenized when I register it this way?

Yes, by default — the domain registers as an NFT on Base to the authenticated buyer's wallet, unless you specify a different nftReceivingWallet in the request. See What Are Tokenized Domains? if that's new to you.

Can I skip the API key entirely?

Yes. Use OAuth 2.1 with PKCE in a compatible MCP client, so no static Namefi API key is stored in the editor configuration. Separately, Namefi's wallet-signed x402 checkout path can authorize and pay for a registration without an API key, as covered in Pay for Domains with a Crypto Wallet. That x402 transaction path does not make an unauthenticated MCP initialize request succeed.

Ship the name with the app

The domain is infrastructure, like the deploy target and the database. Connect one of the three configs above, complete OAuth or provide a key, then run the five-step flow. OAuth may require a browser authorization step; registration, DNS changes, and verification can continue from the editor after that.

Use OAuth or generate a Namefi API key, then try the availability-check prompt in whichever editor you already have open. Read the full Claude Code walkthrough with an annotated transcript if you want to see every step spelled out.

Sources and further reading

Contributors

Fenwei Bian
Fenwei BianAuthor
Software Developer & Writer • Namefi

Fenwei Bian is a software developer in her thirties who spends her working hours in pull requests and her weekends with her hands in soil or sawdust. Years of open source on GitHub taught her that names are interfaces: a good one is clear, honest about what it does, and kind to whoever has to use it next.

She gardens because it rewards patience and punishes wishful thinking, and she does woodwork because a joint either fits or it doesn't. Both habits show up in how she writes about naming — measure twice, check the source, and don't sand over a rough spot and hope no one notices.

For Namefi she writes about how domain markets actually move, the practical trade-offs of tokenizing and flipping names, and picking a domain you'll still be glad you own in twenty years.

Victor Zhou
Victor ZhouEditor
Founder & Standards Editor • Namefi
LinkedIn

Victor Zhou is a technology founder and standards editor focused on digital identity and trust. He founded Namefi, edits Ethereum Improvement Proposals, and previously led smart-contract architecture work at Google Labs.

His work sits at the intersection of naming, ownership, and the systems people use to establish identity online. That perspective makes him especially interested in the way names move between personal meaning, public recognition, and digital infrastructure.

For Namefi, Victor edits and writes about domains as durable digital identity: how names become ownable onchain assets, how tokenization changes custody and trust, and what naming can learn from the systems people use to establish identity online.

Related guides

Discuss this post

View the discussion on Namefi Discuss