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.
Copy the entry
With Pro, its
urlline already ends in your token. No token yet? Make one on your account page.Paste it into config.toml
Open
~/.codex/config.toml, or create it, and paste the table at the end. The key ismcp_servers, with an underscore.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.
Start a new session
Codex reads
config.tomlonce, when it starts. Quit and runcodexagain, or restart the extension, and the 22 tools load.
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.
| File | Where it sits | When Codex loads it |
|---|---|---|
~/.codex/config.toml (above) | Your home folder | In every project, in the CLI and the IDE extension |
.codex/config.toml | A repo's root | Only in projects you've marked as trusted |
$CODEX_HOME/config.toml | Wherever CODEX_HOME points | In 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.
- Start
codexin your project and type/mcp. - Look for
shadcniowith its 22 tools. From a plain shell,codex mcp listshows the servers in your config. - In the IDE extension, open the gear menu, then MCP servers, and check
shadcniois enabled. - Send the prompt below: Codex calls
whoamiand replies with your account and the calls left this minute.
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.
- shadcn.io MCP connected · 22 tools
Agent step: Read package.jsonReturns: Next.js with @base-ui/react and a pnpm lockfileMCP call: search_components({ query: "one-time code" })Returns: input-otp, at the top of the resultsMCP call: get_component({ name: "input-otp", include: ["install", "usage"], packageManager: "pnpm" })Returns: pnpm dlx shadcn add …/r/input-otp.json, and how the slots nestAgent step: Ran pnpm dlx shadcn add (you approved it)Returns: components/ui/input-otp.tsx and the input-otp package
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.
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_varnames a variable Codex sends as anAuthorization: Bearerheader. Drop?token=…from theurl, exportSHADCNIO_TOKENin 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.mdfrom~/.codexand 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 execloads the same config, so scripts and CI get the server too. It starts read-only:--sandbox workspace-writelets it write files, and the install also needssandbox_workspace_write.network_access = true. Addrequired = trueto 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 bytool_timeout_sec. To switch shadcnio off without deleting it, setenabled = 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. /mcpdoesn't list shadcnio after you editedconfig.toml.- Codex reads the file only at startup: run
codexagain, 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.tomlnever 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
/mcplists the server, then open the prompt withuse shadcnio. A line inAGENTS.mdmakes 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.
No. The Codex CLI and the IDE extension read the same ~/.codex/config.toml, so the one entry covers both. Each reads the file when it starts, so start a new codex session and restart the extension after you add it.
Yes. In the extension, open the gear menu, choose MCP servers, then Add server. Name it shadcnio, pick Streamable HTTP, paste your URL, save, and click Restart extension. If its startup times out, add startup_timeout_sec = 20 to the entry in config.toml.
Codex gives each server 10 seconds to start by default, which a slow connection can miss. The entry raises it to 20 seconds. Go to 40 or 60 if you still see timeouts; each tool call has its own 60 second limit, set by tool_timeout_sec.
Only if you trust the project: Codex skips a repo's .codex/config.toml until you do. The entry on this page holds your token in its url, so keep it in ~/.codex/config.toml, or use bearer_token_env_var before you commit a project file.
Codex reads AGENTS.md from ~/.codex and from your repo, once per session. Add one line there telling it to look up components and blocks with the shadcnio MCP before it writes UI, and it will without being asked.
That depends on your approval settings. Set default_tools_approval_mode = "writes" under the server and Codex asks only for tools that aren't marked read-only; every shadcnio tool is marked read-only. The install commands Codex runs afterwards still follow your sandbox and approval rules.
The same registry, for Vue. Codex reads your package.json, and in place of one shadcn command the server's get_install_plan returns every file with its path and the packages to add. Codex writes the files and runs the install. Svelte and Solid work the same way.
Yes. List the tool names you want in enabled_tools under [mcp_servers.shadcnio], or the ones to hide in disabled_tools, which applies after it. If you only use it for icons, for example, keep search_icons, get_icon and list_icon_libraries.
Yes. codex exec reads the same config.toml, so a script or a CI job gets shadcnio like an interactive session does. It starts in a read-only sandbox: pass --sandbox workspace-write so it can write files, and set sandbox_workspace_write.network_access = true so the install command can download them.
Add required = true under [mcp_servers.shadcnio]. Codex then fails at startup when an enabled server can't initialize, and codex exec exits with an error, instead of carrying on and writing components from memory.
Keep the url plain and add bearer_token_env_var = "SHADCNIO_TOKEN" to the entry, then pass the token to the job as a secret under that name. Codex sends it as a Bearer header, and the config file itself holds no secret.
It sits in plain text in your home folder, outside every repo, like other CLI credentials. To keep it out of the file entirely, read it from an environment variable with bearer_token_env_var. If it ever leaks, regenerate it on your account page and the old one stops working within a few minutes.
Only the calls Codex makes: the tool's name and its arguments, such as a component's name or a search phrase. Your files, your prompts and your terminal output never reach shadcn.io. Every shadcnio tool only reads the registry, and the installs run on your machine under your sandbox settings.
Codex reads config.toml only when it starts. Quit and run codex again, or click Restart extension in the IDE. If it's still missing, check the header is [mcp_servers.shadcnio], with an underscore, and that the rest of the file is valid TOML.
A 401 means the token is missing or no longer valid, usually after you regenerated it. A 403 means the token is fine but the account has no active Pro plan. A 429 means more than 600 calls in a minute on one token: wait for the time in Retry-After.
Codex picks tools from your prompt, and a vague one looks answerable from memory. Start with use shadcnio, name the component or the page, and check /mcp lists the server. A line in AGENTS.md makes it the default for the repo.
Using another agent too?
The same URL works in every MCP client: use it beside OpenAI Codex, in your editor, your terminal or your chat app.
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