Claude Design MCP means three different things: a built-in server that returned HTTP 404 in Claude Code 2.1.181, the /design-sync command, and a community server. See the exact setup for Claude Code and Codex, plus the fix for every reported error.
Search for Claude Design MCP and you land in three different places at once. One is a built-in server that Claude Code injects on its own and that answered with a 404 for many people in June 2026. Another is the /design-sync command that pushes your component library into Claude Design. The third is a community server that drives the Claude Design website from a terminal, and it is the only one of the three that also plugs into Codex.
Mixing them up is why most "not working" reports go nowhere: a fix for one does nothing for the others. This article separates the three, shows the exact server setup commands for Claude Code and Codex, and walks through every error message people have actually reported, with the cause and the shortest way out.
💡 Short version: the built-in 404 is a server-side problem you cannot fix locally,
/design-syncfails over login and project requirements, and the community server fails over Chrome sessions and timeouts. Jump to the section that matches your error.
Claude Design is Anthropic's tool for building prototypes, slides and marketing pieces by chatting with Claude. It launched on April 17, 2026 under Anthropic Labs, runs on Claude Opus 4.7, and is available on Pro, Max, Team and Enterprise plans. Enterprise organizations get it switched off by default, so an admin has to enable it. When a design is ready you can export it as a folder, PDF, PPTX, standalone HTML, a Canva file, an organization URL, or a handoff to Claude Code.
"MCP" shows up in this product in three separate ways, and each has its own failure pattern.
Claude Code 2.1.181 began injecting a server called claude_design into every session. It points at https://api.anthropic.com/v1/design/mcp, and for many people that endpoint returned a 404. The /doctor command flagged it, and /mcp printed "Failed to reconnect to claude_design: HTTP 404 at https://api.anthropic.com/v1/design/mcp".
The server is injected dynamically, so it lives in no settings file, and trying to remove it ends with "Cannot remove MCP server from scope: dynamic". The report in issue #69323 was filed on June 18, 2026 and closed as a duplicate on June 22, 2026, next to several near-identical ones such as #69325.
Announced on June 17, 2026, /design-sync runs inside the Claude Code terminal. It pulls your real design system (React components, CSS tokens, fonts) into Claude Design so prototypes start from your components, and it pushes code back so you can keep editing on the canvas. /design-login authorizes the access with your claude.ai account. Only you can launch it: the skill is marked as not model invocable, so Claude cannot start it on its own.
claude-design-mcp is an unofficial, MIT-licensed server that drives Claude Design from agentic CLIs. It exposes roughly 30 tools, including create_design_system, generate, iterate, list_files, read_file, export and publish. Under the hood it automates Chrome against claude.ai, which means it relies on undocumented internal endpoints and may break whenever the site changes. The README says plainly that it is not affiliated with or endorsed by Anthropic.
| Piece | Runs where | Works in Codex | Typical failure |
|---|---|---|---|
Built-in claude_design | Injected by Claude Code | No | HTTP 404 |
/design-sync | Claude Code slash command | No | Authorization, 403 |
claude-design-mcp | Local stdio server plus Chrome | Yes | Expired session, timeouts |
Ten minutes of checking saves an afternoon of debugging. Most "MCP is broken" cases turn out to be a missing requirement, not a broken server.
/design-sync needs a first-party claude.ai account. An API credential, Bedrock or Vertex setup will not do./design-sync warns about hours-long imports and token costs on big repositories./design-sync. Run claude --version to check.dist/, or React with Storybook. Vue, Angular and Svelte are not supported. Start the command in the design system repo, not in the application that consumes it.💡 If
/design-loginsays Unknown command, check your version before anything else. Builds older than v2.1.234 are the first suspect.
Only the community server is something you install yourself, so this setup is about that one. The built-in server and /design-sync need nothing beyond the requirements above.
git clone https://github.com/e-brokenc0de/claude-design-mcp.git
cd claude-design-mcp
pnpm install
pnpm exec playwright install chromium
pnpm run chrome:cdp
pnpm run build
The chrome:cdp script launches Chrome with a persistent profile stored in .auth/cdp-chrome. Sign in to claude.ai in that window once, and the session carries across tool calls.
claude mcp add --transport stdio --scope user claude-design -- node /absolute/path/to/claude-design-mcp/dist/server.js
The -- separates Claude's own options from the command that starts the server. Prefer a team-shared file? Put the same entry in .mcp.json at the project root:
{
"mcpServers": {
"claude-design": {
"command": "node",
"args": ["/absolute/path/to/claude-design-mcp/dist/server.js"]
}
}
}
| Scope | Who sees it | Stored in |
|---|---|---|
local (default) | You, this project | ~/.claude.json |
project | Everyone via version control | .mcp.json |
user | You, every project | ~/.claude.json |
claude mcp list
claude mcp get claude-design
Then open /mcp inside a session. A healthy server shows as connected, and asking Claude to list my Claude Design projects should return real results. Project-scoped servers ask for your approval the first time; if you declined by accident, claude mcp reset-project-choices brings the prompt back.
Codex reads MCP servers from ~/.codex/config.toml, or from a project-scoped .codex/config.toml, using one [mcp_servers.<name>] table per server. The Codex MCP documentation lists every option.
codex mcp add claude-design -- node /absolute/path/to/claude-design-mcp/dist/server.js
codex mcp list
Or write the table yourself:
[mcp_servers.claude-design]
command = "node"
args = ["/absolute/path/to/claude-design-mcp/dist/server.js"]
startup_timeout_sec = 30
tool_timeout_sec = 300
Codex defaults to 10 seconds for startup and 60 seconds per tool call. A tool that drives a website can easily outlast both, so raising them is the first tweak worth making. Inside the Codex terminal UI, /mcp shows which servers are active.
💡 Windows paths: in TOML, a backslash starts an escape inside normal quotes. Write
C:/Users/you/claude-design-mcp/dist/server.jswith forward slashes, or wrap the path in single quotes.
One honest caveat: the community README shows the Claude Code and Cursor config only. The Codex entry above applies Codex's documented format to the same launch command, so confirm it with codex mcp list before relying on it.
The built-in claude_design server is injected by Claude Code, /design-sync and /design-login are Claude Code commands, and the handoff button sends bundles to Claude Code. Codex gets none of those. What it can do is call the community server's tools such as read_file and export, or simply work from an exported folder or standalone HTML file, which are ordinary files on disk.
| Task | Claude Code | Codex |
|---|---|---|
| Add a stdio server | claude mcp add name -- cmd | codex mcp add name -- cmd |
| Config file | ~/.claude.json, .mcp.json | ~/.codex/config.toml, .codex/config.toml |
| List servers | claude mcp list | codex mcp list |
| In-session panel | /mcp | /mcp |
| Startup timeout | MCP_TIMEOUT (ms) | startup_timeout_sec (default 10) |
| Tool timeout | MCP_TOOL_TIMEOUT (ms) | tool_timeout_sec (default 60) |
Match your message in the table, then read the matching section.
| What you see | Most likely cause | First move |
|---|---|---|
HTTP 404 at .../v1/design/mcp | Built-in endpoint answering 404 | Update, then ignore it |
/design-login requires an interactive terminal | Headless, web or non-interactive session | Run in a normal terminal session |
status code 403 while recording access | Authorization rejected | Re-check account and org policy |
| Server fails or tools time out | Startup or tool timeout too low | Raise the timeout values |
| Tools return login errors | Chrome session expired | Re-run pnpm run chrome:cdp |
This one is not yours. The endpoint answered 404, the server is injected rather than configured, and the report noted that authentication was not the cause. There is no entry to delete and no token to refresh.
/doctor again./mcp and look at your own servers. If only claude_design is red, treat it as noise.claude mcp get <name> and compare it with the address in the server's docs.
Two messages come up most: "DesignSync needs design-system authorization, but /design-login requires an interactive terminal and is not available in this environment" and a plain Unknown command. The first means you are in a session that cannot show a login flow, such as the web version or a headless run. A related report (#91063) notes there is no non-interactive path yet, which blocks CI jobs.
/design-login in a normal, interactive Claude Code terminal, then /design-sync.
A 403 reads "Couldn't record Design agent access ... Request failed with status code 403". People hit it on the macOS app, Claude Code Web and the Windows CLI, and they had already confirmed their browser access worked, so it was not a plan problem. When I checked, issue #75024 was still open with no maintainer reply. Meanwhile, confirm your organization allows Claude Design, sign in with a first-party account, and retry.
Timeouts belong to the community server. In Claude Code, raise both limits before launching:
MCP_TIMEOUT=30000 MCP_TOOL_TIMEOUT=600000 claude
PowerShell does not accept that prefix form, so set the variables first:
$env:MCP_TIMEOUT = 30000; $env:MCP_TOOL_TIMEOUT = 600000; claude
In Codex, raise startup_timeout_sec and tool_timeout_sec in the TOML table instead.
The community server uses the Chrome profile in .auth/cdp-chrome. If tools start returning login errors or empty project lists, the claude.ai session probably lapsed.
pnpm run chrome:cdp and sign in to claude.ai again.git pull, pnpm install and pnpm run build. The server rides on internal endpoints, so fixes land in the repository when the site changes.Claude Design runs on Claude Opus 4.7, and the same model is available as a text model on PicassoIA. It makes a good second pair of eyes for an MCP error you cannot read at a glance. Here is the routine:
/mcp panel in Image. If small text comes out unreadable, raise Max Image Resolution (the default is 0.5 megapixels).Want quicker answers on simple errors? Claude Sonnet 5 runs the same way.
💡 Never paste live tokens, cookies or passwords into any chat box. Swap them for placeholders first.
Claude Design prototypes full of gray placeholder boxes look unfinished, and stock photos rarely match a brand. Generating the imagery from the same terminal where you run Claude Code or Codex closes that gap.
PicassoIA offers a developer API at https://api.picassoia.com/v1 and an MCP connector, so an agent can request media like any other tool call. Jobs are asynchronous: create a prediction, poll until it finishes, then fetch the result. Each account runs up to 5 predictions at once, shared across tokens and MCP connections, and connections are managed from picassoia.com/en/mcp/accounts after you sign in. Check the pricing page for what your plan includes before you build on it.
Three models matter for design work:
On the website, Seedream 5 Pro is another text-to-image option for photorealistic scenes.
Every fix above ends in the same place: a working design pipeline still needs pictures. Open Picasso IA Image, type a scene the way you would brief a photographer, and watch it render. Change the lens, the light and the location until the frame feels right, then send the best one through Image Editor Pro for final fixes, or animate it with Picasso IA Video. Try three prompts today, one for a hero banner, one for a product shot and one for a portrait, and see how much faster your next prototype comes together.
