Como usar o Inspo MCP: leve referências de design e capturas para o desenvolvimento de UI com Claude Code ou Codex

Pedir ao Claude Code ou ao Codex para “criar uma landing page limpa, sofisticada e com bom design” normalmente já produz uma página funcional. O problema é que o resultado muitas vezes se resume ao conhecido fundo em degradê, cartões arredondados e um título enorme, sem incorporar a composição, o ritmo e a hierarquia visual que você realmente queria usar como referência.

O Inspo resolve esse problema mais específico: antes de o agente escrever a interface, ele recebe um conjunto de referências de design vindas de sites reais. O site oficial lista atualmente 832 sites em produção, 2.320 registros de páginas — cada um com capturas para desktop e celular —, 68 componentes de referência e dados extraídos como paletas de cores, tipografia, espaçamento, raios de borda, larguras de contêiner e estrutura da página. Tudo isso é disponibilizado via MCP para clientes como Claude Code e Codex.

Instalar o serviço, porém, não prova que o agente viu as capturas, muito menos que a página final reflete essas referências. Um fluxo de trabalho mais confiável é:

1. Conectar o Inspo MCP e confirmar que o cliente realmente está conectado.
2. Pedir primeiro ao agente que procure referências, sem deixá-lo escrever código imediatamente.
3. Verificar quais registros de páginas e URLs de imagens ele recebeu e se realmente leu as imagens.
4. Transformar as referências escolhidas em um “contrato de referências” explícito.
5. Depois da implementação, abrir o render real, comparar item por item e fazer os ajustes.

A seguir, usaremos uma tarefa hipotética: criar, para um projeto existente, uma landing page de produto B2B voltada a desenvolvedores. O exemplo serve para explicar o método; não significa que este artigo executou ou testou o seu projeto.

O que o Inspo MCP realmente oferece

O Inspo não é apenas uma ferramenta de busca por capturas. De acordo com a página oficial do MCP e o repositório do projeto, o agente pode receber três tipos de material de referência.

1. Páginas e capturas

search_screens permite localizar páginas reais por descrição em linguagem natural, estilo, setor, tipo de página, cor, modo claro ou escuro e estrutura. Os resultados podem incluir:

• título da página, slug do Inspo e endereço do site original;
• URLs das capturas para desktop e celular;
• miniatura da página;
• paleta de cores, fontes, stack tecnológico e tags;
• análise das características gerais e da estrutura das seções.

Quando precisar estudar um candidato específico, use get_screen para obter um registro mais completo, em vez de colocar muitos candidatos no contexto de uma só vez.

2. Sistema de design estruturado

Cada site indexado tem um arquivo DESIGN.md derivado das informações de suas páginas. get_design_system pode retornar tipografia, cores semânticas, escala tipográfica, espaçamento, raios, variáveis CSS, largura de contêiner e outros dados.

Isso importa porque “use este site como referência” é vago demais. Já requisitos como “use um hero em duas colunas, limite o conteúdo com um contêiner, destaque o botão principal com uma cor de alto contraste e mantenha bastante espaço entre as seções” são muito mais fáceis de executar com consistência.

3. Componentes de referência e código

O Inspo também oferece componentes de referência para navegação, hero, preços, rodapé e outras áreas. O agente pode primeiro usar find_reference_components para encontrar um componente adequado e depois chamar get_reference_jsx para obter o JSX correspondente.

Isso não significa que você deva copiar um site inteiro sem alterações. O melhor é aproveitar a composição do componente e a hierarquia da informação, adaptando-as ao stack, à marca, ao conteúdo e às interações do projeto atual.

recommend é o melhor ponto de partida. Você descreve a necessidade em linguagem comum, e a ferramenta combina estrutura da página, sites candidatos, componentes de referência, paletas e sugestões de layout. Na primeira utilização, costuma ser mais eficiente pedir ao agente que invoque recommend e depois aprofunde um ou dois candidatos do que pesquisar uma dúzia de páginas desde o início.

Separe a conexão do modelo do Inspo MCP

Claude Code ou Codex precisa de uma conexão funcional com um modelo para analisar, editar e raciocinar sobre o código. O Inspo MCP fornece material externo de design. São dois caminhos diferentes, com endpoints, autenticação e causas de falha distintos.

Se você já usa Claude Code ou Codex por meio da BetterToken, conclua primeiro a configuração do modelo usando a documentação correspondente:

• Documentação de conexão do Claude Code
• Documentação de conexão do Codex

Depois configure o Inspo separadamente. Não use https://inspomcp.dev/api/mcp como Base URL do modelo e não forneça sua API Key da BetterToken ao Inspo. O endpoint hospedado do Inspo não exige atualmente uma conta nem API Key. A BetterToken também não hospeda o Inspo, não concede licença sobre materiais de design de terceiros e não garante que o agente vá ler imagens ou gerar um tipo específico de interface.

Antes da conexão, basta confirmar que:

• Claude Code ou Codex está instalado e consegue concluir tarefas comuns de programação;
• o cliente consegue acessar o endpoint hospedado do Inspo;
• Node.js e npx estão disponíveis caso você pretenda usar o instalador ou o modo stdio local.

Conectando o Inspo MCP

O Inspo oferece um instalador automático, mas você também pode usar os comandos MCP do próprio cliente. Em uma máquina com várias ferramentas de programação com IA, comece com --dry-run para ver quais clientes e configurações serão alterados.

Método 1: usar o instalador do Inspo

Verificar o Claude Code sem gravar nenhuma configuração:

npx -y inspo-mcp install --dry-run --client claude-code

Instalar depois de revisar o plano:

npx -y inspo-mcp install --client claude-code

Verificar apenas o Codex:

npx -y inspo-mcp install --dry-run --client codex

Instalar depois de revisar o plano:

npx -y inspo-mcp install --client codex

Quando --client não é informado, o instalador detecta instalações existentes de Claude Code, Codex, Cursor, VS Code, Windsurf, Claude Desktop e Zed. A documentação oficial do Inspo MCP informa que ele primeiro exibe o plano e pede confirmação; --dry-run apenas imprime o plano sem gravar arquivos, enquanto -y ignora a confirmação.

Método 2: adicionar diretamente o MCP hospedado

O endpoint hospedado recomendado pelo Inspo é:

https://inspomcp.dev/api/mcp

O repositório oficial descreve o Inspo como somente leitura, mas ele continua sendo um MCP externo de terceiros. Em um ambiente de equipe, revise o repositório, o escopo dos dados e a política de rede antes de conectá-lo. O fato de ser “somente leitura” não elimina a necessidade de avaliar a confiança.

Segundo a documentação oficial de MCP do Claude Code, serviços remotos devem ser adicionados por HTTP. Para disponibilizar o Inspo em todos os projetos locais, execute:

claude mcp add --scope user --transport http inspo https://inspomcp.dev/api/mcp

Depois verifique:

claude mcp get inspo
claude mcp list

Também é possível digitar isto em uma sessão do Claude Code:

/mcp

A mensagem Added indica apenas que a configuração foi gravada. Para saber o estado real, consulte claude mcp list: Connected significa que há conexão. Resolva Failed to connect, Pending approval ou um serviço desativado antes de continuar.

A documentação da OpenAI sobre MCP no Codex informa que o Codex aceita serviços Streamable HTTP e STDIO. Adicione o MCP remoto com:

codex mcp add inspo --url https://inspomcp.dev/api/mcp

Liste os serviços configurados:

codex mcp list

Na interface interativa do Codex, você também pode usar:

/mcp

A documentação atual da OpenAI informa que o Codex CLI, a extensão de IDE e o aplicativo do ChatGPT para desktop compartilham a configuração MCP quando executados no mesmo host do Codex. Depois de adicionar ou alterar o serviço, reinicie o cliente atual ou abra uma nova sessão e confira se o Inspo aparece.

stdio é apenas um transporte alternativo

Se não for conveniente conectar o cliente a uma URL remota, ele pode iniciar o serviço stdio por meio do npx:

claude mcp add --scope user inspo -- npx -y inspo-mcp

codex mcp add inspo -- npx -y inspo-mcp

Também é possível acrescentar --local ao comando de instalação automática. Mesmo assim, esse modo continua buscando o catálogo do Inspo em uma CDN; portanto, não equivale a operação offline nem a auto-hospedagem completa.

No primeiro uso, encontre referências antes de pedir código

Um erro comum é juntar “buscar referências” e “implementar a página” em uma só frase:

Use o Inspo para criar uma landing page bonita para mim.

Isso deixa o agente escolher as referências, decidir o que aproveitar e começar a programar imediatamente. Se o resultado ficar ruim, será difícil saber se a busca trouxe páginas inadequadas, se as capturas nunca entraram no contexto ou se a implementação se afastou das referências.

Uma primeira instrução mais segura é:

Ainda não modifique o código nem comece a desenhar a página.

Use o Inspo MCP para encontrar 4 referências candidatas para uma “landing page de produto B2B de API de IA voltada a desenvolvedores”.

Requisitos:
- visual sóbrio e profissional, sem grandes áreas de degradês coloridos;
- o hero deve comunicar claramente o valor do produto e ter um CTA principal;
- pode mostrar a interface do produto ou um fluxo de chamadas, mas não deve parecer um site corporativo tradicional;
- examine referências para desktop e celular;
- comece por recommend e use search_screens, get_screen ou get_design_system apenas se necessário.

Para cada candidato, retorne:
1. título da página, Inspo slug e sourceUrl;
2. URLs das capturas para desktop e celular, caso estejam presentes no resultado da ferramenta;
3. macrostructure, paleta principal e tipografia;
4. 3 decisões específicas de design que vale a pena aproveitar;
5. elementos de marca, textos ou decoração que não devem ser copiados.

Ao final, recomende apenas uma referência principal e no máximo duas referências auxiliares, explicando o que cada uma deve controlar. Ainda não escreva código.

O objetivo não é obter mais adjetivos, e sim identificadores de página e evidências rastreáveis. Você deve ver um slug concreto, a URL do site original, as URLs das capturas e dados de design, em vez de apenas um resumo como “moderno, limpo e profissional”.

Como confirmar que o agente realmente recebeu as referências

A verificação pode ser dividida em quatro níveis. Passar por um nível não prova automaticamente o seguinte.

Nível	Evidência observável	O que isso prova
MCP configurado	O Claude Code mostra Connected, ou o Inspo aparece na lista MCP do Codex	Connected confirma a conexão do Claude Code; a entrada no Codex confirma a configuração, e uma chamada bem-sucedida de ferramenta deve confirmar o acesso ao serviço
A ferramenta retornou dados	A resposta contém um slug real, sourceUrl, cores, tipografia, estrutura da página e URLs de capturas	O agente chamou o Inspo e recebeu um registro estruturado
As imagens foram lidas	O agente abre as URLs com uma ferramenta capaz de ler imagens ou usa um visualizador disponível e descreve detalhes visuais concretos	O agente fez mais do que ler descrições ou links; a presença de miniaturas no resultado, por si só, não comprova isso
A página reflete a referência	O render real tem correspondência explicável com a estrutura, a hierarquia, o ritmo e o comportamento responsivo escolhidos	A referência realmente influenciou a implementação

Essa distinção é importante. O formato de resposta do Inspo sempre contém texto estruturado e pode incluir as URLs originais das imagens. Nos caminhos compatíveis, ele também pode inserir miniaturas como blocos nativos de imagem no resultado da ferramenta. Porém, a implementação do formato de resposta trata explicitamente outros dois casos: se a obtenção da imagem falhar, o bloco de imagem pode ser omitido enquanto o texto e as URLs permanecem; e uma configuração com prioridade para texto pode retornar apenas texto.

Portanto, o fato de o agente fornecer uma URL de captura não prova que o modelo leu os pixels. Envie uma instrução de verificação como esta:

Primeiro prove que você recebeu a referência principal. Não comece a escrever código.

Retorne:
- os nomes das ferramentas do Inspo realmente usadas nesta sessão;
- o slug, sourceUrl, URL da captura para desktop e URL da captura para celular da referência principal;
- 3 fatos visuais concretos observados na captura de desktop e 3 na captura de celular, como composição do hero, posição da navegação, alinhamento do CTA, recorte da imagem, disposição dos cartões ou comportamento de recolhimento;
- quais conclusões vieram das capturas e quais vieram apenas dos campos de texto do Inspo.

Se o cliente atual recebeu apenas texto ou URLs e não leu os pixels das imagens, escreva explicitamente “os pixels das imagens não foram lidos”. Não deduza detalhes visuais a partir da descrição.

O resultado ideal não é uma longa crítica de design, mas uma separação clara entre os elementos realmente visíveis na imagem e as conclusões fornecidas pelos dados estruturados.

Se o agente apenas repetir a paleta, a tipografia e a descrição northstar, peça que ele abra as URLs das capturas usando o navegador ou a ferramenta de leitura de imagens já disponível no cliente. Se o cliente e o modelo atuais aceitam entrada visual, baixe as capturas e envie-as como imagens anexadas. Se o modelo ou a rota do provedor não processa imagens, anexar um arquivo não resolve: use o Inspo para analisar estrutura, cor e texto ou mude para uma configuração compatível com entrada visual. O MCP poder retornar imagens não significa que toda combinação de cliente e modelo vai consumi-las.

Transforme as referências em um “contrato de referências”

Depois de escolher os candidatos, não pare em “use o estilo da referência A”. Defina a responsabilidade de cada fonte e deixe claro o que não pode ser copiado.

Peça ao agente para preparar um contrato como este:

Com base na referência principal e nas referências auxiliares já confirmadas, prepare primeiro um “contrato de referências”. Ainda não modifique o código.

Inclua:

1. Referência principal
- slug / sourceUrl:
- Responsável apenas por: estrutura geral da página, composição do hero, ritmo das seções

2. Referência auxiliar A
- slug / sourceUrl:
- Responsável apenas por: hierarquia tipográfica, largura do texto principal, espaço em branco

3. Referência auxiliar B (somente se for realmente necessária)
- slug / sourceUrl:
- Responsável apenas por: um componente específico ou o comportamento de reorganização no celular

4. O projeto atual deve preservar
- o stack tecnológico, o roteamento e as convenções de componentes existentes
- os textos reais do produto, os limites das funcionalidades e as cores da marca
- as interações, os requisitos de acessibilidade e os requisitos de desempenho já existentes

5. Explicitamente proibido
- não copiar o logotipo, o nome da marca, as ilustrações, as fotos nem os textos originais do site de referência
- não reproduzir o site inteiro pixel a pixel
- não inventar recursos que o produto atual não possui apenas para se aproximar da referência

6. Critérios de aceitação
- em um viewport comum de desktop, o hero apresenta por completo o título, a explicação, o CTA e o visual principal
- a hierarquia de informações segue a referência principal, mas o conteúdo pertence ao produto atual
- a versão móvel tem uma estratégia deliberada de reorganização, e não apenas uma versão reduzida do layout de desktop
- o espaçamento entre seções, a largura do contêiner, a hierarquia tipográfica e a prioridade dos botões seguem regras verificáveis

O contrato transforma inspiração em restrições. A referência principal controla a estrutura geral, enquanto as auxiliares resolvem problemas locais. Mais referências não significam necessariamente um resultado melhor: se cinco sites controlarem ao mesmo tempo cores, tipografia, cartões e hero, a página tende a voltar para um estilo genérico de IA, sem prioridades claras.

Deixe Claude Code ou Codex implementar a página

Depois de confirmar as referências e os critérios de aceitação, deixe o agente examinar o repositório e alterar o código. A instrução abaixo evita fixar npm run dev, uma pasta de framework ou um comando de testes, porque esses elementos devem ser identificados no projeto atual, e não adivinhados.

Comece agora a implementação.

Primeiro examine o stack tecnológico do repositório atual, os pontos de entrada das páginas, as variáveis de design, os componentes reutilizáveis e os scripts disponíveis. Depois modifique a página de acordo com o “contrato de referências” confirmado.

Requisitos de implementação:
- use o framework, o sistema de componentes e as dependências existentes; não adicione um novo framework de UI sem necessidade real;
- preserve o conteúdo e as funcionalidades reais do produto e não copie ativos de marca nem textos dos sites de referência;
- transforme as referências no layout, nas variáveis CSS e nos componentes próprios deste projeto;
- implemente desktop e celular de forma deliberada; não deixe a versão móvel para o fim contando com escala automática;
- corrija primeiro a estrutura geral, a hierarquia da informação e o espaçamento; depois cuide de detalhes decorativos como sombras e raios;
- não substitua componentes existentes do projeto apenas porque o Inspo fornece JSX.

Antes de modificar os arquivos, explique brevemente:
1. quais arquivos pretende alterar;
2. em qual componente ou regra de estilo cada ponto da referência será aplicado;
3. qual conteúdo existente deve permanecer inalterado.

Ao concluir:
- execute o formatador, as verificações de tipo ou os testes já existentes no repositório;
- inicie a visualização local disponível;
- liste os arquivos realmente alterados;
- mostre um mapeamento “ponto da referência → local da implementação”;
- não avalie o resultado apenas com frases como “mais moderno” ou “mais premium”.

Se o projeto já usa design tokens, peça ao agente que altere primeiro os tokens ou as variáveis semânticas, em vez de espalhar cores e dimensões fixas por vários componentes. Assim, será muito mais fácil corrigir o ritmo geral da página na próxima iteração.

A avaliação final deve se basear no render real, não no diff do código

Uma página compilar só prova que o código funciona. Para saber se ela reflete as referências, é preciso ver a página real.

As páginas do Inspo normalmente incluem capturas para desktop e celular. O Colophon oficial informa que o arquivo usa larguras de 1440 e 375 pixels. Você não precisa repetir exatamente a altura, mas inspecionar a implementação em larguras semelhantes facilita a comparação da estrutura geral e da reorganização móvel.

Se o Claude Code ou o Codex já tiver um navegador, Playwright ou outra ferramenta de captura configurada, peça ao agente que abra a página local. Caso contrário, abra você mesmo a visualização no navegador, faça capturas de desktop e celular e devolva-as ao agente.

Peça que ele revise usando este formato:

Compare:
- as capturas de desktop e celular já confirmadas da referência principal;
- capturas reais da página atual em larguras aproximadas de 1440px e 375px.

Ainda não redesenhe nem altere o código. Primeiro mostre uma tabela de diferenças:

| Ponto de verificação | Evidência observável na referência | Implementação atual | Diferença | Alteração recomendada |
| --- | --- | --- | --- | --- |
| Estrutura do hero |  |  |  |  |
| Hierarquia do título e do CTA |  |  |  |  |
| Contêiner e espaço em branco |  |  |  |  |
| Hierarquia tipográfica |  |  |  |  |
| Cor e contraste |  |  |  |  |
| Disposição dos componentes |  |  |  |  |
| Reorganização no celular |  |  |  |  |

Depois selecione apenas as 3 diferenças de maior impacto e corrija-as. Renderize novamente e revise após as mudanças. Não introduza uma nova direção visual na mesma rodada.

Uma boa observação deve ser visível e acionável. Por exemplo:

• Não diga: “O hero ainda não parece premium o bastante.”
• Diga: “A referência principal mostra o título, o CTA e a interface do produto dentro do primeiro viewport. A página atual tem espaço vertical demais, então a interface fica abaixo da primeira dobra. Reduza o espaçamento vertical do hero, limite a largura do título e faça o visual principal aparecer dentro de uma altura comum de desktop.”

Outro exemplo:

• Não diga: “A versão móvel ainda não se parece o suficiente com a referência.”
• Diga: “No celular, a referência mostra primeiro o título e o CTA, seguidos por um cartão de produto em uma única coluna. A implementação atual mantém o layout de duas colunas do desktop, comprimindo o texto e a imagem. Mude para uma coluna no celular e mantenha o CTA antes do visual principal.”

Corrigir poucas diferenças de grande impacto em cada rodada costuma convergir mais rápido do que repetir “deixe mais bonito”.

Problemas comuns

O comando de configuração funcionou, mas o agente não encontra o Inspo

Verifique o estado do cliente antes de reinstalar qualquer coisa.

Claude Code:

claude mcp get inspo
claude mcp list

Codex:

codex mcp list

Confirme que o endpoint não contém caracteres extras e reinicie o cliente. Se o Claude Code usar um .mcp.json no nível do projeto, talvez também seja necessário aprovar o serviço em um workspace confiável.

O MCP está conectado, mas o agente nunca chama o Inspo

Separe a etapa de busca da etapa de programação. Exija explicitamente: “chame o Inspo primeiro, retorne o slug, o sourceUrl e as URLs das capturas; não altere o código até que as referências sejam confirmadas”. Verifique também em /mcp se o serviço está habilitado.

O agente retornou a descrição da página, mas nenhuma imagem apareceu

A chamada pode ter retornado apenas texto, a obtenção da miniatura pode ter falhado, o cliente pode não exibir blocos de imagem do MCP ou a rota do modelo pode não processar imagens. Confira se as URLs das capturas para desktop e celular ainda estão presentes e peça ao agente que diga claramente se leu os pixels. Se o cliente e o modelo atuais aceitam entrada visual, abra as URLs com uma ferramenta de navegador ou envie as capturas como anexos. Para um modelo somente de texto, use os dados estruturados ou mude para uma configuração que processe imagens.

A página continua parecendo um template genérico

A solução normalmente não é buscar mais dez referências, mas restringir o briefing: uma referência principal controla a macroestrutura, uma auxiliar controla tipografia e espaço em branco, e no máximo outra controla um componente específico. Registre essas funções no contrato e exija um mapeamento entre cada ponto da referência e sua localização no código.

O contexto ficou grande demais e o agente começou a misturar as referências

Use recommend para obter candidatos e chame get_screen ou get_design_system apenas para um ou dois selecionados. Não carregue vários registros completos de páginas e códigos de componentes ao mesmo tempo. Chame get_reference_jsx somente quando precisar de um componente específico.

O site original já não corresponde à captura do Inspo

O Inspo preserva o material da página no momento da captura, enquanto o site original pode ter sido redesenhado depois. Compare com a captura e o registro escolhidos no Inspo. sourceUrl serve para rastrear a origem; não se deve presumir que o site continuará visualmente idêntico ao arquivo para sempre.

O objetivo não é apenas “instalar um MCP”, mas construir uma cadeia de evidências

O valor do Inspo MCP não está em decidir automaticamente o que é um bom design. Ele transforma “quero uma sensação parecida com esta” em páginas, capturas, dados de design e componentes de referência rastreáveis.

Uma rodada confiável de desenvolvimento de UI deve deixar quatro tipos de evidência:

1. o cliente confirma que o Inspo está conectado;
2. o agente retorna páginas específicas e material de design;
3. é possível confirmar que ele leu as capturas, ou ele informa com honestidade que recebeu apenas texto;
4. o render final permite explicar, ponto a ponto, quais regras de estrutura, hierarquia e responsividade vieram das referências.

Quando busca, confirmação, implementação e verificação são separadas, Claude Code ou Codex deixa de apenas “criar uma página bonita por intuição”. Ele passa a trabalhar dentro de um contexto de design que você consegue inspecionar, corrigir e reutilizar.