Claude Design MCP significa três coisas diferentes: um servidor embutido que retornou HTTP 404 no Claude Code 2.1.181, o comando /design-sync e um servidor da comunidade. Veja a configuração exata para Claude Code e Codex, além da correção para cada erro relatado.
Ao pesquisar por Claude Design MCP, você cai em três lugares diferentes ao mesmo tempo. Um é um servidor embutido que o Claude Code injeta por conta própria e que respondeu com erro 404 para muita gente em junho de 2026. Outro é o comando /design-sync, que envia sua biblioteca de componentes para o Claude Design. O terceiro é um servidor da comunidade que controla o site do Claude Design a partir de um terminal, e é o único dos três que também se conecta ao Codex.
Confundir os três é o motivo de a maioria dos relatos de "não está funcionando" não levar a lugar nenhum: a correção de um não resolve os outros. Este artigo separa os três, mostra os comandos exatos de configuração do servidor para Claude Code e Codex, e percorre cada mensagem de erro que as pessoas realmente relataram, com a causa e o caminho mais curto para resolver.
💡 Resumo rápido: o 404 do servidor embutido é um problema do lado do servidor que você não consegue corrigir localmente,
/design-syncfalha por causa de requisitos de login e de projeto, e o servidor da comunidade falha por causa de sessões do Chrome e timeouts. Vá para a seção que corresponde ao seu erro.
O Claude Design é a ferramenta da Anthropic para criar protótipos, slides e peças de marketing conversando com o Claude. Ele foi lançado em 17 de abril de 2026 sob o Anthropic Labs, roda no Claude Opus 4.7 e está disponível nos planos Pro, Max, Team e Enterprise. Nas organizações Enterprise ele vem desativado por padrão, então um administrador precisa ativá-lo. Quando um design está pronto, você pode exportá-lo como pasta, PDF, PPTX, HTML independente, arquivo do Canva, URL da organização ou transferi-lo para o Claude Code.
"MCP" aparece neste produto de três maneiras separadas, e cada uma tem seu próprio padrão de falha.
O Claude Code 2.1.181 passou a injetar um servidor chamado claude_design em cada sessão. Ele aponta para https://api.anthropic.com/v1/design/mcp, e, para muita gente, esse endpoint retornou um 404. O comando /doctor sinalizou o problema, e /mcp exibiu a mensagem "Failed to reconnect to claude_design: HTTP 404 at https://api.anthropic.com/v1/design/mcp".
O servidor é injetado dinamicamente, então não fica em nenhum arquivo de configuração, e tentar removê-lo termina com "Cannot remove MCP server from scope: dynamic". O relato na issue #69323 foi aberto em 18 de junho de 2026 e fechado como duplicado em 22 de junho de 2026, junto com vários outros quase idênticos, como o #69325.
Anunciada em 17 de junho de 2026, /design-sync roda dentro do terminal do Claude Code. Ela puxa seu sistema de design real (componentes React, tokens CSS, fontes) para o Claude Design, para que os protótipos partam dos seus componentes, e envia o código de volta para que você continue editando na tela de trabalho. /design-login autoriza o acesso com sua conta claude.ai. Só você pode iniciá-la: a skill está marcada como não invocável pelo modelo, então o Claude não consegue iniciá-la por conta própria.
claude-design-mcp é um servidor não oficial, com licença MIT, que controla o Claude Design a partir de CLIs agênticas. Ele expõe cerca de 30 ferramentas, incluindo create_design_system, generate, iterate, list_files, read_file, export e publish. Nos bastidores, ele automatiza o Chrome no claude.ai, o que significa que depende de endpoints internos não documentados e pode quebrar sempre que o site mudar. O README deixa claro que ele não é afiliado nem endossado pela Anthropic.
| Peça | Onde roda | Funciona no Codex | Falha típica |
|---|---|---|---|
claude_design embutido | Injetado pelo Claude Code | Não | HTTP 404 |
/design-sync | Comando de barra do Claude Code | Não | Autorização, 403 |
claude-design-mcp | Servidor stdio local mais Chrome | Sim | Sessão expirada, timeouts |
Dez minutos de verificação poupam uma tarde de depuração. A maioria dos casos de "o MCP está quebrado" acaba sendo um requisito que falta, e não um servidor com defeito.
/design-sync exige uma conta claude.ai de primeira parte. Uma credencial de API, ou uma configuração de Bedrock ou Vertex, não serve./design-sync alerta sobre importações que levam horas e sobre custos de tokens em repositórios grandes./design-sync. Execute claude --version para verificar.dist/ publicado, ou React com Storybook. Vue, Angular e Svelte não são suportados. Inicie o comando no repositório do sistema de design, e não na aplicação que o consome.💡 Se
/design-logindisser Unknown command, verifique sua versão antes de qualquer outra coisa. Versões anteriores à v2.1.234 são o primeiro suspeito.
Só o servidor da comunidade você instala por conta própria, então esta configuração trata desse. O servidor embutido e /design-sync não precisam de nada além dos requisitos acima.
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
O script chrome:cdp abre o Chrome com um perfil persistente guardado em .auth/cdp-chrome. Entre no claude.ai nessa janela uma vez, e a sessão se mantém entre as chamadas de ferramentas.
claude mcp add --transport stdio --scope user claude-design -- node /absolute/path/to/claude-design-mcp/dist/server.js
O -- separa as opções do próprio Claude do comando que inicia o servidor. Prefere um arquivo compartilhado com a equipe? Coloque a mesma entrada em .mcp.json na raiz do projeto:
{
"mcpServers": {
"claude-design": {
"command": "node",
"args": ["/absolute/path/to/claude-design-mcp/dist/server.js"]
}
}
}
| Escopo | Quem vê | Armazenado em |
|---|---|---|
local (padrão) | Você, neste projeto | ~/.claude.json |
project | Todos, pelo controle de versão | .mcp.json |
user | Você, em todos os projetos | ~/.claude.json |
claude mcp list
claude mcp get claude-design
Depois, abra /mcp dentro de uma sessão. Um servidor saudável aparece como conectado, e pedir ao Claude para listar meus projetos do Claude Design deve retornar resultados reais. Servidores de escopo de projeto pedem sua aprovação na primeira vez; se você recusou por engano, claude mcp reset-project-choices faz o aviso voltar.
O Codex lê os servidores MCP de ~/.codex/config.toml, ou de um .codex/config.toml com escopo de projeto, usando uma tabela [mcp_servers.<name>] para cada servidor. A documentação MCP do Codex lista todas as opções.
codex mcp add claude-design -- node /absolute/path/to/claude-design-mcp/dist/server.js
codex mcp list
Ou escreva a tabela você mesmo:
[mcp_servers.claude-design]
command = "node"
args = ["/absolute/path/to/claude-design-mcp/dist/server.js"]
startup_timeout_sec = 30
tool_timeout_sec = 300
O Codex usa por padrão 10 segundos para a inicialização e 60 segundos por chamada de ferramenta. Uma ferramenta que controla um site pode facilmente passar dos dois, então aumentá-los é o primeiro ajuste que vale a pena fazer. Na interface de terminal do Codex, /mcp mostra quais servidores estão ativos.
💡 Caminhos no Windows: no TOML, uma barra invertida inicia uma sequência de escape dentro de aspas normais. Escreva
C:/Users/you/claude-design-mcp/dist/server.jscom barras normais ou envolva o caminho em aspas simples.
Uma ressalva honesta: o README da comunidade mostra apenas a configuração para Claude Code e Cursor. A entrada do Codex acima aplica o formato documentado do Codex ao mesmo comando de inicialização, então confirme com codex mcp list antes de confiar nela.
O servidor claude_design embutido é injetado pelo Claude Code, /design-sync e /design-login são comandos do Claude Code, e o botão de transferência envia os pacotes para o Claude Code. O Codex não tem nenhum desses recursos. O que ele pode fazer é chamar as ferramentas do servidor da comunidade, como read_file e export, ou simplesmente trabalhar a partir de uma pasta exportada ou de um arquivo HTML independente, que são arquivos comuns no disco.
| Tarefa | Claude Code | Codex |
|---|---|---|
| Adicionar um servidor stdio | claude mcp add name -- cmd | codex mcp add name -- cmd |
| Arquivo de configuração | ~/.claude.json, .mcp.json | ~/.codex/config.toml, .codex/config.toml |
| Listar servidores | claude mcp list | codex mcp list |
| Painel dentro da sessão | /mcp | /mcp |
| Timeout de inicialização | MCP_TIMEOUT (ms) | startup_timeout_sec (padrão 10) |
| Timeout de ferramenta | MCP_TOOL_TIMEOUT (ms) | tool_timeout_sec (padrão 60) |
Encontre sua mensagem na tabela e depois leia a seção correspondente.
| O que você vê | Causa mais provável | Primeiro passo |
|---|---|---|
HTTP 404 at .../v1/design/mcp | Endpoint embutido respondendo 404 | Atualize e depois ignore |
/design-login requires an interactive terminal | Sessão headless, web ou não interativa | Execute em uma sessão de terminal normal |
status code 403 durante o registro de acesso | Autorização recusada | Verifique de novo a conta e a política da organização |
| O servidor falha ou as ferramentas dão timeout | Timeout de inicialização ou de ferramenta baixo demais | Aumente os valores de timeout |
| Ferramentas retornam erros de login | Sessão do Chrome expirada | Execute pnpm run chrome:cdp de novo |
Este não é um problema seu. O endpoint respondeu 404, o servidor é injetado em vez de configurado, e o relato observou que a autenticação não era a causa. Não há entrada para excluir nem token para renovar.
/doctor de novo./mcp e veja os seus próprios servidores. Se apenas claude_design aparecer em vermelho, trate como ruído.claude mcp get <name> e compare com o endereço na documentação do servidor.
Duas mensagens aparecem com mais frequência: "DesignSync needs design-system authorization, but /design-login requires an interactive terminal and is not available in this environment" e um simples Unknown command. A primeira significa que você está em uma sessão que não consegue exibir um fluxo de login, como a versão web ou uma execução headless. Um relato relacionado (#91063) observa que ainda não há um caminho não interativo, o que bloqueia jobs de CI.
/design-login em um terminal normal e interativo do Claude Code, depois /design-sync.
Um 403 aparece como "Couldn't record Design agent access ... Request failed with status code 403". As pessoas encontraram isso no aplicativo para macOS, no Claude Code Web e na CLI do Windows, e já tinham confirmado que o acesso pelo navegador funcionava, então não era problema de plano. Quando verifiquei, a issue #75024 ainda estava aberta, sem resposta de nenhum mantenedor. Enquanto isso, confirme se sua organização permite o Claude Design, entre com uma conta de primeira parte e tente de novo.
Os timeouts são do servidor da comunidade. No Claude Code, aumente os dois limites antes de iniciar:
MCP_TIMEOUT=30000 MCP_TOOL_TIMEOUT=600000 claude
O PowerShell não aceita essa forma com prefixo, então defina as variáveis primeiro:
$env:MCP_TIMEOUT = 30000; $env:MCP_TOOL_TIMEOUT = 600000; claude
No Codex, aumente startup_timeout_sec e tool_timeout_sec na tabela TOML.
O servidor da comunidade usa o perfil do Chrome em .auth/cdp-chrome. Se as ferramentas começarem a retornar erros de login ou listas de projetos vazias, a sessão do claude.ai provavelmente expirou.
pnpm run chrome:cdp e entre de novo no claude.ai.git pull, pnpm install e pnpm run build. O servidor depende de endpoints internos, então as correções chegam ao repositório quando o site muda.O Claude Design roda no Claude Opus 4.7, e o mesmo modelo está disponível como modelo de texto na PicassoIA. Ele é uma boa segunda opinião para um erro de MCP que você não consegue entender de relance. Este é o roteiro:
/mcp em Imagem. Se o texto pequeno ficar ilegível, aumente Max Image Resolution (o padrão é 0,5 megapixel).Quer respostas mais rápidas para erros simples? Claude Sonnet 5 funciona do mesmo jeito.
💡 Nunca cole tokens, cookies ou senhas reais em nenhuma caixa de chat. Troque-os por marcadores antes.
Protótipos do Claude Design cheios de caixas cinzas de espaço reservado parecem inacabados, e fotos de banco de imagens raramente combinam com uma marca. Gerar as imagens no mesmo terminal onde você executa o Claude Code ou o Codex fecha essa lacuna.
A PicassoIA oferece uma API para desenvolvedores em https://api.picassoia.com/v1 e um conector MCP, então um agente pode solicitar mídia como qualquer outra chamada de ferramenta. Os jobs são assíncronos: crie uma predição, consulte até que ela termine e depois busque o resultado. Cada conta roda até 5 predições ao mesmo tempo, compartilhadas entre tokens e conexões MCP, e as conexões são gerenciadas em picassoia.com/en/mcp/accounts depois que você entra. Consulte a página de preços para ver o que o seu plano inclui antes de construir algo sobre isso.
Três modelos importam para trabalho de design:
No site, o Seedream 5 Pro é outra opção de texto para imagem para cenas fotorrealistas.
Toda correção acima termina no mesmo lugar: um fluxo de trabalho de design funcionando ainda precisa de imagens. Abra o Picasso IA Image, descreva uma cena como você faria um briefing para um fotógrafo e veja-a ser renderizada. Mude a lente, a luz e o local até o enquadramento parecer certo, depois envie a melhor versão pelo Image Editor Pro para os ajustes finais, ou anime-a com o Picasso IA Video. Teste três prompts hoje, um para um banner principal, um para a foto de um produto e um para um retrato, e veja o quanto mais rápido seu próximo protótipo fica pronto.
Escolha seu idioma
