How to Use Namefi in OpenAI Codex: Search, Register and Manage DNS

By the end of this guide, OpenAI Codex will be connected to Namefi, an ICANN-accredited registrar, and you will have searched for a domain, registered it, and pointed its DNS at your project without leaving your terminal or editor. It is the Codex edition of the Claude walkthrough: same Namefi server, same flow, but with Codex's own config file, commands and quirks.

Two paths get you there, and this guide covers both. The plugin path installs Namefi's first-party Codex plugin, which bundles the connection plus guided workflows. The config path adds the server by hand, which is the one that also works in the Codex IDE extension. Each step below says which path it belongs to. Every Codex command and config key in this guide was checked against OpenAI's current documentation, and the configuration was loaded by a real Codex CLI (version 0.154.0). The one thing we could not do is record a live registration transcript, so the conversation section shows prompts and what to check, not captured output. Where something is unverified, it says so.

What you are connecting

Codex can call external tools through the Model Context Protocol (MCP). OpenAI's docs say the ChatGPT desktop app, the Codex CLI and the IDE extension all support MCP servers and share MCP configuration for the same Codex host. Configure a server once and you can switch between those clients without redoing setup.

Namefi runs one hosted MCP server at https://api.namefi.io/mcp, over Streamable HTTP, which exposes the Namefi API as typed tools: Namefi's MCP page lists availability search, registration and payment, DNS records, portfolio and orders, and balance. Codex lists "Streamable HTTP servers" as a supported MCP transport, so no adapter is needed. For the tool catalog itself, see Namefi MCP Server: Domain Tools for AI Agents.

Prerequisites

• Codex. The CLI, the IDE extension, or Codex in the ChatGPT desktop app. The plugin path needs the CLI or the desktop app: OpenAI's plugin docs say the IDE extension doesn't support plugins. The config path works in all three.
• A Namefi sign-in or API key. Every Namefi MCP request is authenticated, including read-only ones; there is no anonymous tier. You can sign in with OAuth in a browser, or send an API key from namefi.io/api-key (sign-in required).
• A way to pay. Registration spends NFSC (Namefi Service Credits) on the paying wallet, per Namefi's agent instructions. Step 4 covers funding.

Step 1: Pick how Codex will authenticate

There are two credentials, and the choice decides your config.

OAuth (browser sign-in). Connect with no key. When Namefi's server answers with an HTTP 401, your client discovers the sign-in flow (OAuth 2.1 with PKCE and dynamic client registration), a browser window opens, you approve, and the client retries with the token. No secret is stored in a file. Codex documents OAuth for Streamable HTTP servers and a codex mcp login <server-name> command. This is the better default on a laptop, and the only comfortable option for GUI apps that do not inherit your shell's environment variables.

API key. Namefi's x-api-key header carries a key you generate at namefi.io/api-key. This suits unattended and headless runs. Two facts about the key matter before you create one:

• It inherits a wallet's permissions. Namefi's docs say the key must be generated from the wallet that owns the domain for write operations like DNS changes.
• It can spend money. The notice on Namefi's key-creation flow reads: "Anyone with this key can buy domains on your account", with purchases using your NFSC balance first and any remainder charged to the card saved in your payment methods. Treat the key like a card number: keep it out of repositories, shell history and chat transcripts.

Step 2: Connect Codex to Namefi

Path A: the Namefi plugin (CLI and desktop app)

Namefi publishes a Codex plugin in d3servelabs/namefi-codex-plugins. Its README gives two commands:

codex plugin marketplace add d3servelabs/namefi-codex-plugins
codex plugin add namefi@namefi

The first registers the repository as a plugin marketplace (OpenAI's CLI docs say marketplace add accepts GitHub shorthand such as owner/repo). The second installs the plugin named namefi from the marketplace named namefi. Per the README, the marketplace entry requires sign-in at install time, so Codex walks you through authentication then. The plugin bundles the same hosted MCP server plus skills for domains, dynamic DNS and HTTPS routing, and the README says its domain skill requires you to confirm the exact name, duration and price before a paid registration.

Two caveats from the README: the plugin is not yet a published listing in the public OpenAI Plugins Directory, so you install it from the repository as above; and the plugin does not apply to the IDE extension. OpenAI's plugin docs also say to start a new session after installing before the bundled tools appear. You can browse installed plugins inside the CLI with /plugins.

Path B: add the server yourself (CLI, IDE extension, desktop app)

OpenAI's docs say Codex stores MCP configuration in config.toml, by default ~/.codex/config.toml, with .codex/config.toml for project-scoped servers in trusted projects. Each server is a [mcp_servers.<server-name>] table, and a Streamable HTTP server needs url.

With OAuth, one command does it. codex mcp add takes --url for a streamable HTTP server:

codex mcp add namefi --url https://api.namefi.io/mcp

That writes exactly this to ~/.codex/config.toml, which we confirmed by running it against a throwaway CODEX_HOME:

[mcp_servers.namefi]
url = "https://api.namefi.io/mcp"

If Codex does not open the browser by itself, run codex mcp login namefi and approve the sign-in. The command waits for you to finish in the browser, so run it where you can see the window.

With an API key, edit the file instead, and read the key from an environment variable so it never lands in the file. Codex's docs describe env_http_headers as a map of header names to environment variable names, with values pulled from the environment:

[mcp_servers.namefi]
url = "https://api.namefi.io/mcp"
env_http_headers = { "x-api-key" = "NAMEFI_API_KEY" }
default_tools_approval_mode = "prompt"

Then export the variable in the shell that launches Codex, taking the value from your secret manager rather than typing it into a command you will keep in history:

export NAMEFI_API_KEY="<value from your secret manager>"

Do not use bearer_token_env_var for this. Codex documents it for the Authorization: Bearer header, and Namefi's key travels in x-api-key, so it needs the general env_http_headers (or static http_headers) field instead.

The default_tools_approval_mode line is optional, but worth having for a server that can spend money. OpenAI documents it as the default approval behavior for a server's tools, with values auto, prompt, writes and approve; prompt makes Codex ask before tool calls. writes prompts only for tools not marked read-only, and Namefi's plugin repo notes its server's tools did not yet set read-only hints when that file was written, so writes may not distinguish searches from purchases. Prefer prompt.

A project-scoped .codex/config.toml is committed-file territory: put only the url and the variable name there, never a key. The IDE extension and desktop app read the same configuration. Because a GUI app launched from your dock or start menu may not see variables exported in a terminal profile, OAuth is the safer choice for them (this is a general desktop-launch behavior, not something Namefi or OpenAI documents specifically).

Step 3: Confirm the connection

Check Codex sees the server before spending anything:

codex mcp list
codex mcp get namefi

For the API-key config above, codex mcp get namefi printed:

namefi
  enabled: true
  transport: streamable_http
  url: https://api.namefi.io/mcp
  bearer_token_env_var: -
  http_headers: -
  env_http_headers: x-api-key=NAMEFI_API_KEY
  http_headers_helper: -
  default_tools_approval_mode: prompt
  remove: codex mcp remove namefi

That proves Codex parsed the config, not that Namefi accepted your credential. For the live check, start a session with codex and run /mcp, which OpenAI's docs say shows your active MCP servers, then ask a read-only question:

"Using the Namefi tools, check whether example.com is available to register. Tell me which tool you called. Don't register anything."

If the server answers with a result and names a Namefi tool, you are connected. If you get a 401, jump to the troubleshooting table.

Step 4: Fund your account

Registration is a paid operation. Namefi's agent instructions say it spends NFSC on the paying wallet; the key-creation notice above adds that any shortfall can fall through to a saved card. Namefi's MCP page lists card, NFSC, x402 and MPP as payment routes, but its agent instructions say x402 and MPP are separate HTTP endpoints, not MCP tools. So from Codex you pay with NFSC or a saved card; the wallet-signing routes are covered in Pay for Domains with a Crypto Wallet.

• Production: top up NFSC and manage cards from Namefi's Payment Methods page (linked in the site's account section at namefi.io). We did not verify a price, a minimum top-up or an NFSC-to-USD rate for this guide, so check the amount on screen before you confirm anything.
• Testing: Namefi's docs describe an NFSC faucet for test balances, POST /v-next/user/faucet, in Managing your balance. It is for sandbox environments, not production.

If a payment is blocked, the error body from Namefi already carries the URL to send you to (a top-up or add-card link), per Namefi's agent instructions. Open that link rather than asking Codex to improvise one.

Step 5: The conversation

With the server connected and funds in place, the rest is plain language. These prompts are a template, not a recorded transcript; the behavior in each step comes from Namefi's documented API.

1. Search.

"Check whether acme-widgets.com and acmewidgets.io are available on Namefi, and show me the price for each."

Namefi's tools cover one name or many, with pricing. Ask for the price every time, and compare it against the amount you expect before moving on.

2. Register, with a hard stop for your approval.

"Register acme-widgets.com for 1 year. Before you submit the order, show me the exact domain, the duration and the total price with its currency, and wait for me to say yes."

Namefi's registration request takes a normalizedDomainName (lowercase, no trailing dot) and a durationInYears from 0 to 10, defaulting to 1, plus an optional wallet that receives the domain's ownership NFT, which defaults to the buyer's wallet on Base. With the plugin, its domain skill asks for the same confirmation by design. With the manual config, your prompt and the prompt approval mode are the safeguard.

3. Wait for the order.

"Check the order status until it finishes and tell me the final status."

Registration is asynchronous: the registration call returns an order, and the order is polled until it reaches a terminal status. Codex should report back once it is done instead of declaring success after the first call.

4. Add DNS records.

"Add an A record for @ pointing to 203.0.113.10 with a TTL of 300 seconds, and a CNAME for www pointing to cname.vercel-dns.com."

Two formatting rules from Namefi's record format: the zone name is the bare domain with no trailing dot, while FQDN values like a CNAME target are lowercase with a trailing dot. Namefi's ttl is in seconds. Our guide to DNS record types explains the record types if you need them.

5. Optionally, set up dynamic DNS. The plugin includes workflows for pointing a hostname at a machine without a static IP, and Namefi's command-line tool does the same job as a background service. That is a separate topic from registration, so we only mention it here.

Step 6: Verify it resolves

DNS propagation takes time, so give new records a few minutes. Ask Codex to list the records back, or check from your own terminal, independently of Codex:

dig +short A acme-widgets.com
dig +short CNAME www.acme-widgets.com

If you use a deployment platform, finish its own domain-verification step too. Reading records through Namefi's API needs no authentication per its docs, but through the MCP server, expect to be signed in.

Troubleshooting

Frequently Asked Questions

Does Namefi work in the Codex IDE extension and the desktop app, or only the CLI?

The MCP connection works in all three: OpenAI says the desktop app, CLI and IDE extension share MCP configuration. The Namefi plugin does not, because OpenAI's plugin docs say the IDE extension doesn't support plugins. If you use the extension, configure the server directly (Path B).

Should I use the plugin or add the MCP server by hand?

The plugin adds guided workflows (domains, dynamic DNS, HTTPS routing) and a confirm-before-paying step in its domain skill, and installs in two commands. The manual config is smaller, works in the IDE extension, and gives you full control of the config. Both use the same server at https://api.namefi.io/mcp.

Do I need an API key?

No. Connect without one and sign in with OAuth in the browser. Use a key for headless or unattended runs, where nobody is there to approve a browser prompt.

Can Codex spend my money without asking?

Only if you let it. A Namefi key can buy domains, so keep Codex's approval mode at prompt for the Namefi server, tell Codex to show the exact name, duration and price and wait for a yes, and read the price yourself before approving.

Why does Codex say the server needs authentication even for a simple availability check?

Namefi's MCP server has no anonymous tier. Its agent instructions note that a plain availability lookup is available over open REST without credentials, but the MCP tools require sign-in or a key.

The Namefi MCP page shows a different Codex install command. Which one is right?

namefi.io/mcp lists an npx codex-marketplace add … command for Codex. This guide uses the two native codex plugin commands from the plugin repository's README, which the Codex CLI supports directly. The npx tool is a separate community package that we have not tested, so we do not recommend it here.

Is a domain registered this way an NFT?

By default, yes: Namefi's registration request sends the domain's ownership token to the buyer's wallet on Base unless you specify another receiving wallet. See tokenized domains for what that means.

Where do I go for other agents?

How to Register a Domain with Your AI Agent on Namefi covers six clients side by side, and Buy a Domain with Claude is the Claude version of this guide. If you want to know why MCP rather than raw REST, read MCP vs REST API.

Buy your next domain from your terminal

Codex plus Namefi comes down to one config table or two commands, one credential, and a habit of reading the price before saying yes. For what else the server can do once connected, including how the same tools show up in the browser, see Namefi MCP Server: Domain Tools for AI Agents and WebMCP on Namefi.

Create a Namefi API key, or skip the key and run codex mcp add namefi --url https://api.namefi.io/mcp.

Sources and further reading

• OpenAI — Model Context Protocol (config file location, [mcp_servers.<name>] tables, Streamable HTTP keys url, bearer_token_env_var, http_headers, env_http_headers, OAuth, codex mcp add/login, /mcp, approval modes, shared config across CLI, IDE extension and desktop app; the page developers.openai.com/codex/mcp redirects here)
• OpenAI — Command line options (codex mcp, codex plugin, codex plugin marketplace add with GitHub shorthand)
• OpenAI — Plugins (CLI /plugins browser, new session after install, no plugins in the IDE extension)
• OpenAI — Codex IDE extension (install and configuration)
• Namefi — d3servelabs/namefi-codex-plugins (README install commands, package layout, authentication notes; SUBMISSION.md for directory status)
• Namefi — namefi.io/mcp (endpoint, tool categories, authentication, plugins, payment routes)
• Namefi — namefi.io/llms.txt (authentication, OAuth and API key flows, registration fields, DNS record format, payment-blocked handoff)
• Namefi — namefi.io/api-key (key creation; sign-in required)
• Namefi — namefi.io/cli (command-line tool for dynamic DNS and portfolio listing)
• Namefi — docs.namefi.io: Managing your balance (NFSC test faucet)
• Model Context Protocol — What is MCP? (protocol overview)