Skip to content
← All install options

Install Better Design MCP in Codex

Install the Better Design plugin in the Codex app, or run npx better-design.

Install from the plugin directory
Open Better Design in the Codex app

No desktop app? Open the listing in your browser (opens in a new tab).

  1. 1

    Select Install plugin and sign in

  2. 2

    Ask for Better Design in a new Codex chat

Install from the terminal
Adds Better Design without replacing your other servers.
terminal
npx better-design

Or configure Codex manually

Paste the settings below when you need to inspect every value.

Need more detail? Read the official Codex MCP documentation.

Config
toml
[mcp_servers.better-design]
url = "https://better-design.com/api/mcp"
http_headers = { Authorization = "Bearer <YOUR_API_KEY>", X-Better-Design-Client = "codex" }

Prerequisites before you connect Better Design

This page assumes Codex is already installed and can sign in. In the Codex app, the plugin above is the shortest path. The Codex IDE extension does not support plugins, so use the installer or the TOML there. For the Codex CLI and the editor extension, the Better Design installer is: it detects installed coding tools, lets you choose Codex, and updates the existing config without replacing other MCP servers.

terminal
npx better-design
  • Choose Codex when the installer lists detected clients.
  • Let the installer create a limited free key, or use BETTER_DESIGN_API_KEY when your environment already supplies one.
  • Restart Codex after the installer finishes so the app and CLI load the new MCP server.
  • Use the manual TOML path below only when you need to inspect every setting.

Check Codex before manual setup

Use these checks only when you choose the config.toml path. Keeping them as terminal text makes the commands selectable, copyable, and easier to update than an image of a terminal.

terminal
codex --version
codex login status

Verify the Better Design MCP server

Relaunch Codex after saving the TOML block. Then inspect the named server and the complete server list. A listed server proves that Codex loaded the configuration; the first small tool call proves that the key and remote connection work.

terminal
codex mcp get better-design
codex mcp list
  • Confirm the server name is better-design and the URL is https://better-design.com/api/mcp.
  • Do not paste the rendered config or diagnostic output into a public place because the static header contains the API key.
  • Start with a read-only request such as finding a design system or loading one UI principle.

Use an environment variable instead of a static header

Codex can also read a bearer token from an environment variable. Use this path when your local secret manager or shell environment already supplies BETTER_DESIGN_API_KEY. Do not commit the variable value.

terminal
codex mcp add better-design \
  --url https://better-design.com/api/mcp \
  --bearer-token-env-var BETTER_DESIGN_API_KEY

What Codex can use after setup

Better Design supplies focused design context and review tools. Codex still owns the code change, and the repository remains the source of truth for components, data flow, tests, and delivery status.

  • Find a catalog design system or create a custom brand system before frontend work begins.
  • Load UI principles for visual decisions and UX principles for flows and behavior.
  • Retrieve component and icon guidance that matches the selected system.
  • Run review rules, comprehension checks, and measured spacing inspection on rendered pages.

Keep API-key and tool permissions narrow

The Better Design API key authenticates the remote MCP server. Codex permissions separately control local files and commands. Configure and review both boundaries instead of treating a successful connection as broad approval.

  • Use the key only on the Better Design MCP URL.
  • Regenerate the key if it appears in a commit, screenshot, log, or public message.
  • Keep Codex sandbox and approval settings proportional to the current repository task.
  • Review every external tool result as untrusted context before it changes code or data.

Troubleshoot Codex MCP setup

Read the exact failure before replacing the configuration. Installation, authentication, TOML syntax, API-key, and server-availability failures have different fixes.

  • Codex does not list better-design: confirm ~/.codex/config.toml contains one [mcp_servers.better-design] block, save it, and relaunch Codex.
  • Codex reports invalid TOML: check quotes, braces, and duplicate table names around the pasted block.
  • The server returns 401: regenerate or reveal the current Better Design API key and replace only the token value.
  • The server is listed but tools are missing: run codex mcp get better-design, confirm the URL, then start a new Codex session.
  • The wrong Codex installation loads another config: run which codex or Get-Command codex and confirm the active executable and home directory.

Questions

Does this page install Codex CLI?

No. It connects Better Design to an existing Codex installation. Use the Codex CLI guide for platform installation, authentication, commands, configuration, permissions, and skills.

Where does Codex store MCP configuration?

The default user file is ~/.codex/config.toml. Trusted projects can also use project-scoped .codex/config.toml files when a server belongs only to that repository.

How do I verify Better Design in Codex?

Relaunch Codex, run codex mcp get better-design and codex mcp list, then make one small read-only Better Design request. Do not share output that contains the static Authorization header.

Can I avoid putting the API key in config.toml?

Yes. Use codex mcp add with --bearer-token-env-var BETTER_DESIGN_API_KEY when a protected local environment supplies the key. Keep the variable value out of the repository and command history.

Does Better Design change Codex permissions?

No. Better Design adds remote design tools. Codex sandbox and approval settings still control local files and commands, and you should keep them proportional to each task.

Official Codex resources

Related