Skip to content

shadcn/ui in OpenAI Codex, CLI and IDE

Add one [mcp_servers.shadcnio] table to ~/.codex/config.toml and Codex can look up components, blocks and icons and install them, from the CLI or the IDE extension. It needs shadcn.io Pro.

Kind
Terminal agent
Goes in
~/.codex/config.toml
Connects
Over HTTP
Team config
No

Add it to config.toml

One TOML table in your home folder serves the Codex CLI and the IDE extension alike. With Pro and signed in, the block shown here holds your own URL.

  1. Copy the entry

    With Pro, its url line already ends in your token. No token yet? Make one on your account page.

  2. Paste it into config.toml

    Open ~/.codex/config.toml, or create it, and paste the table at the end. The key is mcp_servers, with an underscore.

  3. Or add it from the IDE

    In the extension, open the gear menu, choose MCP servers, then Add server. Pick Streamable HTTP, paste the URL, save, and click Restart extension.

  4. Start a new session

    Codex reads config.toml once, when it starts. Quit and run codex again, or restart the extension, and the 22 tools load.

~/.codex/config.toml
Sign in to get your config
Sign in with a Pro account, and this holds your MCP URL, ready to paste.

How it reads, with YOUR_TOKEN where your token goes:

[mcp_servers.shadcnio]
url = "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN"
startup_timeout_sec = 20

Codex keeps ~/.codex/config.toml in your home folder, away from your repos. The url carries your token, so regenerate it if the file is ever shared.

Where Codex reads the server from
FileWhere it sitsWhen Codex loads it
~/.codex/config.toml (above)Your home folderIn every project, in the CLI and the IDE extension
.codex/config.tomlA repo's rootOnly in projects you've marked as trusted
$CODEX_HOME/config.tomlWherever CODEX_HOME pointsIn place of ~/.codex, when the variable is set

Check that Codex sees it

In the CLI, /mcp lists the servers the session started. The extension shows the same servers under the gear menu's MCP servers, each marked enabled or not.

  1. Start codex in your project and type /mcp.
  2. Look for shadcnio with its 22 tools. From a plain shell, codex mcp list shows the servers in your config.
  3. In the IDE extension, open the gear menu, then MCP servers, and check shadcnio is enabled.
  4. Send the prompt below: Codex calls whoami and replies with your account and the calls left this minute.
Prompt
use shadcnio to show which shadcn.io account this Codex session uses

Three tasks in Codex

One in the terminal, one in the editor, one in a SolidStart app: the prompt, the calls Codex makes and the files it changes. Switch the MCP off to see what it writes from memory.

Your agent
  1. shadcn.io MCP connected · 22 tools
  2. You: Add a six-digit code step to sign-in for accounts with 2FA on.
  3. Agent step: Read package.jsonReturns: Next.js with @base-ui/react and a pnpm lockfile
  4. MCP call: search_components({ query: "one-time code" })Returns: input-otp, at the top of the results
  5. MCP call: get_component({ name: "input-otp", include: ["install", "usage"], packageManager: "pnpm" })Returns: pnpm dlx shadcn add …/r/input-otp.json, and how the slots nest
  6. Agent step: Ran pnpm dlx shadcn add (you approved it)Returns: components/ui/input-otp.tsx and the input-otp package
  7. Your agent: Accounts with 2FA now get a six-slot code step after the password, and pasting the code fills every slot.

In your project

Input OTP

  • Six slots, and a pasted code fills them all
  • The step shows only for accounts with 2FA on

1 prompt → 2 MCP calls

Prompts to try in Codex

Paste one into Codex, in the terminal or in the editor's panel. Each opens by naming the server, so Codex calls its tools before it writes anything.

01
use shadcnio to replace the country select on checkout with a searchable combobox
02
use shadcnio to build the developer settings page from blocks, starting with API keys
03
use shadcnio to swap the inline SVGs in src/components for matching Lucide icons
04
use shadcnio to read Popover's API, then fix the menu that opens off screen
05
use shadcnio to move the product filters into a sheet in this Nuxt app
06
use shadcnio to plan a landing page for a code review tool and install the blocks it picks
07
use shadcnio to restyle the dashboard after Vercel's DESIGN.md
08
use shadcnio to show a skeleton while the orders table loads

Codex settings worth knowing

The config keys and habits that change how Codex works with the server: tokens, instructions, approvals, headless runs and timeouts.

  • One file for the CLI and the IDE

    The CLI and the IDE extension both read ~/.codex/config.toml, so the entry you add once shows up in each. Neither notices an edit mid-session: restart whichever one you have open.

  • Read the token from your shell

    bearer_token_env_var names a variable Codex sends as an Authorization: Bearer header. Drop ?token=… from the url, export SHADCNIO_TOKEN in your shell profile, and the file holds no secret.

    [mcp_servers.shadcnio]
    url = "https://…/api/mcp"
    bearer_token_env_var = "SHADCNIO_TOKEN"
    startup_timeout_sec = 20
  • A line in AGENTS.md

    Codex reads AGENTS.md from ~/.codex and from your repo at the start of each session. One line there and it looks up the registry before it writes UI, with no need to name the server.

    Before writing UI, look up the component or block with the shadcnio MCP, and install it with the command the server returns.
  • Fewer approval prompts

    Add this line under [mcp_servers.shadcnio] and Codex asks only for tools that aren't marked read-only. Every shadcnio tool carries that mark, so lookups go through; the installs still follow your sandbox rules.

    default_tools_approval_mode = "writes"
  • Headless, with codex exec

    codex exec loads the same config, so scripts and CI get the server too. It starts read-only: --sandbox workspace-write lets it write files, and the install also needs sandbox_workspace_write.network_access = true. Add required = true to the entry to stop the run if shadcnio can't start.

    $ codex exec --sandbox workspace-write "use shadcnio to show a skeleton while the orders table loads"
  • Timeouts and an off switch

    A server gets 10 seconds to start; the entry raises that to 20 with startup_timeout_sec. Each call gets 60, set by tool_timeout_sec. To switch shadcnio off without deleting it, set enabled = false.

When Codex can't reach it

What you see in Codex, and what to change. For every client at once, see the troubleshooting guide.

Codex says shadcnio timed out while starting.
Startup gets 10 seconds unless the entry says otherwise. The one on this page sets startup_timeout_sec = 20: raise it to 40 or 60 on a slow network, then start a new session.
/mcp doesn't list shadcnio after you edited config.toml.
Codex reads the file only at startup: run codex again, or click Restart extension in the IDE. Still missing? Check the header reads [mcp_servers.shadcnio] and the rest of the file is valid TOML.
The server in a repo's .codex/config.toml never loads.
Codex skips project config until you trust the project. Mark it as trusted, or move the entry to ~/.codex/config.toml.
Calls to shadcnio fail with a 401.
The token is missing, or you regenerated it and the entry still has the old one. Copy the entry from this page again; with bearer_token_env_var, check the variable is exported in the shell that starts Codex.
Calls to shadcnio fail with a 403.
The token is valid, but the account behind it has no active Pro plan. Once Pro starts again, the same entry works within a few minutes, with nothing to edit.
Codex writes its own component instead of calling shadcnio.
Check /mcp lists the server, then open the prompt with use shadcnio. A line in AGENTS.md makes that the habit for the whole repo.

Get the MCP for OpenAI Codex with Pro

The MCP comes with every Pro plan, with every block and premium template, for you or your whole team. Monthly, yearly or lifetime.

4.9/5 out of 5 · 150+ reviewsfrom 150+ founders and developers.

  • Secure checkout via Stripe
  • Code lives in your repo
  • Keep what you've shipped if you cancel
  • License terms

Frequently asked questions

The shadcn MCP in OpenAI Codex: setup, limits, and the rest.

4.9 out of 5 from 150+ developers

Put the registry in your config.toml

Components for React, Vue, Svelte and Solid, 6,231 blocks and 294k icons, ready in the Codex CLI and the IDE extension with any Pro plan.

Get Pro