Shadcn MCP for OpenAI Codex

One MCP URL gives Codex live tools to search, preview, and install every block, component, and icon on shadcn.io — no hallucinated props, no broken installs.

Install

Open your Codex configuration file — ~/.codex/config.toml for global settings or .codex/config.toml at the root of a trusted project — and add the shadcnio server:

Paste it in once you're signed in with an active Pro subscription — the config carries your personal token, so treat the full URL like an API key. Pro starts at $19/mo and includes MCP access across every editor plus 6,000+ production-ready blocks. Not Pro yet? See what you unlock →

codex mcp add is for local STDIO servers only — shadcn.io runs as a remote HTTP server, so config.toml is the only path. The same file is shared by the Codex CLI and the IDE extension, so one edit covers both clients.

Pick the right scope

Codex only loads project-scoped config from projects you've marked as trusted — a safety check against unknown servers in cloned repos. For teams, commit .codex/config.toml referencing an env-derived header so nobody commits their token directly:

[mcp_servers.shadcnio]
url = "https://www.shadcn.io/api/mcp"
env_http_headers = { "Authorization" = "SHADCNIO_BEARER" }
startup_timeout_sec = 20

Each teammate exports SHADCNIO_BEARER="Bearer $SHADCNIO_TOKEN" in their shell (or a git-ignored .env). A Team or Organization plan gives every workspace member their own Pro entitlement.

Install your first block

use shadcnio to install hero-announcement into my project

What Codex actually does, in order:

1. search_items({ query: "hero-announcement" }) to confirm the slug resolves.
2. get_item({ name: "hero-announcement" }) for a cheap metadata peek.
3. get_install_command({ name: "hero-announcement" }) — returns a shadcn add https://www.shadcn.io/r/hero-announcement.json?token=… URL with your token already in the query string.
4. Runs it. Files land under components/ui/.

Name the server explicitly (use shadcnio…) when multiple MCPs are active. Without it, Codex picks one at random or skips tools entirely.

The example above uses hero-announcement, a Pro block — the install runs once you're signed in with an active subscription.

Manage the connection

Inside the Codex TUI, run /mcp to see every active server and its live status. From a shell, codex mcp --help lists the full lifecycle commands (list, remove, login, etc.). Codex reads config.toml at startup, so restart the session after editing the [mcp_servers.shadcnio] block.

Set enabled = false in the config to disable the server without removing it (useful while debugging). Flip back to true when you need it again — no re-auth required.

If your Pro subscription lapses, the next tool call returns 403. Resubscribing restores access on the following request — no reconfigure, no reinstall. The token itself stays valid across subscription gaps.

FAQ