Se você já adicionou o Playwright MCP ao Claude Code mas ainda não consegue abrir uma página, reinstalar tudo normalmente não é o melhor ponto de partida. A maioria dos problemas de configuração do MCP se resume a algumas causas comuns: o servidor MCP de nível de projeto ainda não foi aprovado, o comando de inicialização está incorreto ou os binários do navegador necessários estão faltando.
Comece executando /mcp para verificar se o servidor está conectado e se as ferramentas do Playwright estão disponíveis. Depois, peça ao agente para abrir uma página. Isso ajuda a identificar se o problema está na conexão MCP, no próprio Playwright ou no ambiente do navegador, sem alterar repetidamente uma configuração que talvez já esteja correta.
Mas abrir uma página é apenas o primeiro passo. Tarefas reais no navegador costumam envolver pesquisar, abrir várias páginas, transitar entre fontes diferentes e decidir o que fazer em seguida com base no que aparece na página. Ao investigar um erro, por exemplo, o agente pode precisar revisar os resultados de busca, abrir várias discussões relevantes, comparar ambientes e mensagens de erro relatados e avaliar as correções sugeridas antes de decidir qual vale a pena testar.
Com o ego (lite), o agente pode manter essas páginas abertas e continuar trabalhando dentro de um Space de navegador separado, sem interromper a janela do navegador que você está usando. Você pode entrar nesse Space a qualquer momento para revisar o que o agente encontrou ou assumir quando for necessário o julgamento humano.
Este artigo começa com a configuração do MCP no Claude Code e a solução de problemas comuns do Playwright e do navegador. Em seguida, usa a mesma tarefa de investigação para demonstrar uma abordagem diferente para fluxos de trabalho no navegador. Um servidor MCP exibindo “connected” significa apenas que as ferramentas estão disponíveis. O que importa é se o agente consegue realmente usá-las para concluir a tarefa de navegador que vem a seguir.
O que um servidor MCP adiciona ao Claude Code?
O Claude Code já vem com ferramentas próprias, mas um servidor de protocolo de contexto de modelo permite adicionar capacidades nomeadas que ele não tem por padrão, como um navegador, um banco de dados ou uma API SaaS. A documentação oficial do Claude Code descreve os servidores como uma forma de conectar ferramentas e fontes de dados externas, adicionados com claude mcp add e gerenciados na sessão com /mcp.
O próprio protocolo é definido em modelcontextprotocol.io, que é onde os transportes e as capacidades são especificados.
A referência de CLI por trás desses comandos é a documentação oficial de MCP do Claude Code.
A conexão usa JSON-RPC 2.0. O Claude Code atua como host, o servidor MCP roda como subprocesso (stdio) ou endpoint acessível (HTTP), e cada ferramenta traz um nome, uma descrição e um esquema de entrada que o modelo lê antes de chamá-la. É por causa desse esquema que um servidor mal configurado falha como ferramentas ausentes em vez de travar: a conexão abre, mas nenhuma ferramenta é descoberta.
Um servidor não é um plugin nem uma extensão. Um plugin pode incluir um servidor MCP, mas adicionar um servidor diretamente grava uma entrada na sua configuração de MCP. Essa distinção importa quando a mesma ferramenta aparece duas vezes, uma vinda de um plugin e outra da sua própria configuração, com argumentos diferentes.
Qual escopo escolher: local, project ou user?
O Claude Code resolve servidores MCP por escopo, e o escopo controla duas coisas ao mesmo tempo: onde a configuração fica e quem mais pode carregá-la. Escolha pelo modo como o servidor deve circular, não por hábito.
| Escopo | Armazenado em | Quem pode ver | Melhor uso |
|---|---|---|---|
| local (padrão) | ~/.claude.json sob o caminho do projeto | Apenas o projeto atual, sem compartilhamento | Um servidor privado que você quer em um repositório e em nenhum outro. |
| project | .mcp.json na raiz do projeto | Apenas o projeto atual, compartilhado via controle de versão | Um servidor de que toda a equipe precisa, fixado em uma única configuração. |
| user | ~/.claude.json | Todos os seus projetos, sem compartilhamento | Um servidor pessoal que você quer disponível em todos os lugares. |
Quando o mesmo nome de servidor aparece em mais de um escopo, o Claude Code adota a entrada de maior precedência por inteiro. Local vence project, project vence user, e a entrada vencedora não é mesclada com as outras. Uma entrada antiga no escopo user pode ofuscar silenciosamente uma do escopo project.
Como adicionar e verificar um servidor MCP?
Adicione um servidor stdio local com claude mcp add, usando -- para separar as flags do próprio Claude Code do comando do servidor que ele vai iniciar. O sinal duplo de hífen impede que qualquer coisa depois dele seja interpretada como opção do Claude Code.
claude mcp add --scope project playwright -- \
npx --yes @playwright/mcp@latest --isolatedPara um servidor HTTP remoto, informe o transporte e o endpoint. Uma entrada JSON com url mas sem type é um erro de configuração, então declare o type quando você escrever a configuração à mão.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcpA verificação é separada da adição. claude mcp list mostra um status de integridade por servidor, e claude mcp get recebe o nome do servidor e imprime o detalhe da falha, quando existe. Dentro de uma sessão, /mcp lista os servidores conectados, a contagem de ferramentas de cada um e os que precisam de autenticação ou aprovação.
claude mcp list
claude mcp get playwrightUm servidor que mostra Connected mas não expõe nenhuma ferramenta, ou que mostra Failed to connect com um código de erro, não passou na verificação. A configuração salva é o começo da checagem, não o fim.
Quando um servidor de projeto pede aprovação?
Servidores com escopo project vindos de um arquivo .mcp.json pedem aprovação na primeira vez que uma sessão interativa do Claude Code tenta usá-los. Isso é intencional: um arquivo versionado não deveria entregar o controle do navegador ao agente silenciosamente só porque existe no repositório.
Execuções não interativas mudam a regra. Em claude -p, em sessões do Agent SDK e em sessões na nuvem não há prompt para exibir, então o Claude Code carrega servidores com escopo project sem perguntar. É por isso que uma configuração em que você confia localmente pode ser uma superfície maior na CI.
| Tipo de execução | Comportamento de aprovação | O que observar |
|---|---|---|
| Sessão interativa | Exibe o prompt antes de usar um servidor de projeto | Pending approval é um estado de confiança, não uma falha. |
| claude -p / Agent SDK / cloud | Carrega servidores de projeto sem o prompt | Um .mcp.json versionado age sem nenhuma validação humana. |
| Workspace não confiável | Aprovações registradas no repositório são ignoradas até você confiar na pasta | O servidor fica como Pending approval até você executar claude e aceitar. |
Se você nunca quiser que um servidor de projeto específico carregue, adicione-o a disabledMcpjsonServers. Se quiser começar apenas com os servidores que passar explicitamente, use --strict-mcp-config. Ambos são controles deliberados, não uma forma de contornar um prompt de confiança.
Quais correções o Playwright MCP realmente precisa?
O Playwright MCP é o servidor de navegador que as pessoas mais conectam ao Claude Code, e suas falhas se concentram em três pontos. Cada um tem uma correção melhor do que reinstalar.
O servidor em todos os exemplos aqui é o microsoft/playwright-mcp, onde ficam a lista de ferramentas e as issues abertas.
A API que ele encapsula está documentada em playwright.dev.
Se você ainda está escolhendo qual servidor de navegador conectar, a comparação de servidores MCP de navegador para o Claude Code classifica as opções.
Se você está começando de uma máquina limpa em vez de consertar um servidor existente, o guia de configuração do Playwright MCP para Claude Code e Cursor cobre a instalação e o registro na ordem.
Windows: o npx quebra o pipe stdio
No Windows, o npx é npx.cmd, um wrapper em lote que o Claude Code inicia sem shell. O pipe stdio de que o MCP depende nunca conecta, e o servidor reporta Connection closed. A solução documentada é envolver o comando para que o cmd o execute, ou chamar node diretamente contra o cli.js do pacote.
claude mcp add --scope user playwright -- cmd /c npx @playwright/mcp@latest{
"mcpServers": {
"playwright": {
"command": "node",
"args": ["C:\\path\\to\\node_modules\\@playwright\\mcp\\cli.js"]
}
}
}Ferramentas ausentes ou nome de pacote desatualizado
O pacote correto é @playwright/mcp. O nome antigo @modelcontextprotocol/server-playwright está obsoleto, e @executeautomation/playwright-mcp-server é um projeto comunitário separado. Se a conexão abre mas nenhuma ferramenta aparece, confirme o pacote exato que o Claude Code está iniciando, não o que você acha que digitou.
O Playwright MCP também precisa do binário do navegador. Se o servidor inicia mas uma inicialização falha, execute npx playwright install e acrescente npx playwright install-deps no Linux ou no Docker. A documentação oficial indica um requisito de Node.js que varia por página: 18 ou mais recente no README, 20 ou mais recente no guia de primeiros passos. Confira a página à sua frente e a saída de node --version.
Um servidor que morre e nunca volta
O Claude Code não reconecta servidores stdio automaticamente. Quando o subprocesso morre, o servidor é marcado como falho e você o reconecta manualmente pelo /mcp. Se um travamento de aba do navegador ou a suspensão do notebook matou seu servidor no meio da tarefa, a correção é reconectar, não reinstalar.
Quando você deve trocar o MCP pela CLI ou por um navegador real?
Mantenha o MCP quando você quiser ferramentas estruturadas dentro do loop do agente, uma ação de navegador com snapshot de retorno ou uma ferramenta sobre a qual o Claude Code consiga raciocinar pelo nome. Migre para a CLI do Playwright quando a tarefa tiver formato de shell, de script, de arquivo de saída salvo ou de execução que você quer repetir ao pé da letra sem o loop do agente.
Para a mesma classe de falha em uma sessão existente do Chrome, Chrome DevTools MCP: configuração, sessões existentes e correções explica o processo.
Depois que os servidores estão conectados, eles também custam contexto; como reduzir o uso de tokens do MCP aborda esse trade-off.
Troque para uma rota de navegador real quando o estado de login aprovado for o requisito rígido. Um perfil isolado e novo do Playwright não herda a sua sessão diária do Chrome, e nenhuma flag do MCP muda isso por conta própria.
Para um leque mais amplo de rotas de navegador que um agente pode seguir, as cinco formas de dar um navegador ao Claude Code comparam as rotas pelo custo de configuração e pelo comportamento do estado de login.
Executamos o mesmo prompt de pesquisa por duas dessas rotas em uma única máquina: o servidor Playwright MCP configurado e um Space de navegador independente controlado pela CLI do ego-browser. O prompt pedia o README do repositório, o comando de instalação, o requisito de Node.js e até três issues sobre Connection closed, npx e stdio, cada uma com seu ambiente, problema e solução. No fim, as duas execuções relataram três issues. Não relataram as mesmas três.
A rota MCP leu o repositório primeiro, confirmou o README e o requisito de Node.js 18 e então foi para a aba Issues. A partir daí, leu cada issue como um dump de DOM salvo e recuperou os campos com ferramentas de texto do shell. Na marca de três minutos e quarenta segundos, estava abrindo a segunda issue, e a execução terminou por volta de sete minutos e quinze segundos com as issues 1385, 1540 e 1611.
A rota de navegador real consultou o DOM ao vivo dentro da página em vez de despejá-lo, e abriu um segundo Space para que os resultados de busca e as páginas de issues ficassem visíveis ao mesmo tempo. Aos três minutos e três segundos, tinha um candidato confirmado, e chegou ao aviso do repositório da terceira issue aos quatro minutos e onze segundos. Relatou 658, 1540 e 1385.
A sobreposição é 1540 e 1385. A diferença importa mais do que a sobreposição: 658 é a thread que traz a única solução de configuração confirmada por vários autores do relato, e a execução MCP não a encontrou. A execução de navegador real também descartou um candidato por considerá-lo fraco demais, enquanto a execução MCP manteve uma issue que o próprio autor havia fechado como inválida para aquele repositório. Isso é uma diferença de fontes, não de velocidade, e é o motivo honesto para escolher uma rota em vez de um cronômetro.
| Observado nesta execução | Rota Playwright MCP | Rota de navegador real |
|---|---|---|
| Como a página foi lida | Snapshot salvo em arquivo e depois lido com ferramentas de texto do shell | DOM ao vivo consultado dentro da página enquanto ela permanecia aberta |
| Segunda issue aberta em | 3m 40s | 3m 03s, com um candidato confirmado |
| Terceira issue alcançada em | Ainda lendo aos 5m 45s | 4m 11s, relatório já em andamento |
| Issues relatadas | 1385, 1540, 1611 | 658, 1540, 1385 |
| Trouxe a correção de configuração que funciona | Não | Sim, issue 658 |
| Visível e interrompível durante a execução | Não, apenas atividade de ferramentas | Sim, os dois Spaces na tela, com um controle de assumir |
| Rota | O que ela consegue fazer | O que ela não pode presumir |
|---|---|---|
| Servidor MCP | Expor ferramentas nomeadas e evidências da página ao vivo ao Claude Code. | Ele não vira uma suíte de testes duradoura nem herda o estado pessoal do Chrome por padrão. |
| Playwright CLI | Executar comandos shell concisos e salvar snapshots ou arquivos de saída para leitura seletiva. | Ele não roda em um cliente sem acesso a shell e sistema de arquivos. |
| Rota de navegador real | Operar um workspace de navegador independente com estado elegível e aprovado. | Ele não oferece fixtures, asserções, mocking de rede nem traces do Playwright Test. |
Para ver a comparação completa de interface e custo de contexto, leia Playwright MCP vs CLI. Esta página continua focada na configuração do Claude Code e nas correções do Playwright.
Onde o ego (lite) se encaixa e onde não se encaixa?
O ego (lite) é uma rota de execução diferente para os trabalhos em que a conexão MCP não é o problema. Por meio do Skill ego-browser, ele controla um navegador Chromium real em um Space independente e pode reutilizar estado elegível autorizado pelo usuário, o que importa quando uma tarefa precisa de sessão autenticada, etapas visíveis ou de uma pessoa para assumir no meio da execução.
O fluxo de trabalho é uma única rodada em JavaScript, não um longo fluxo de chamadas de ferramenta MCP. Você abre um Space uma vez e depois agrupa as verificações que de outro modo rodaria uma ação de navegador por vez:
ego-browser nodejs <<'EOF'
const task = await taskSpace("article-qa");
for (const [slug, url] of Object.entries({
home: "https://lite.ego.app/",
mcpConfig: "https://lite.ego.app/article/claude-code-mcp-configuration"
})) {
const page = await task.newPage();
await page.goto(url, { waitUntil: "domcontentloaded" });
const report = await page.evaluate(() => ({
h1: document.querySelectorAll("h1").length,
horizontalOverflow: document.documentElement.scrollWidth > innerWidth
}));
console.log(slug, report);
}
await task.finish({ keep: [] });
EOFEsse padrão já roda dentro do nosso próprio pipeline de publicação. Em 10 de setembro de 2026, mantivemos oito páginas de artigo abertas em um único Space e conferimos os layouts de desktop e de celular de 390 pixels juntos: canonicals, tags de idioma, um único H1, ordem dos títulos, carregamento de imagens e texto alternativo, destinos de âncora, overflow de código e overflow horizontal. Depois clicamos em um sumário do artigo e verificamos se o título de destino entrou na viewport.
Ele não é um servidor MCP, nem um executor do Playwright Test, nem um plugin do Claude Code. Use-o quando um agente precisar de um workspace de navegador inspecionável com estado ao vivo aprovado. Mantenha o Playwright para suítes E2E com muitas asserções, mocking de rede, artefatos de trace e CI headless.
Perguntas frequentes
Como adiciono um servidor MCP ao Claude Code?
Use claude mcp add, com -- separando as flags do Claude Code do comando do servidor. Adicione --scope project ou --scope user de propósito e depois verifique com claude mcp list ou /mcp.
Onde o Claude Code armazena a configuração de MCP?
Os escopos local e user ficam em ~/.claude.json. O escopo project fica em um arquivo .mcp.json na raiz do projeto, que você pode versionar no controle de versão.
Por que o Claude Code exibe Pending approval?
A configuração de MCP com escopo project exige aprovação de confiança em sessões interativas. Abra o Claude Code no projeto confiável, revise o comando e aprove.
Um servidor de projeto pede aprovação na CI?
Não. claude -p, Agent SDK e sessões na nuvem não conseguem exibir o prompt, então carregam servidores com escopo project sem perguntar. Trate um .mcp.json versionado como uma superfície maior fora do uso interativo.
Por que o Playwright MCP falha com Connection closed no Windows?
O npx no Windows é npx.cmd, um wrapper em lote cujo pipe stdio o Claude Code não consegue usar sem um shell. Envolva o comando com cmd /c ou chame node contra o cli.js do pacote.
Qual é o nome de pacote correto do Playwright MCP?
@playwright/mcp é o pacote oficial. O nome antigo @modelcontextprotocol/server-playwright está obsoleto, e @executeautomation/playwright-mcp-server é um projeto comunitário separado.
Qual versão do Node.js o Playwright MCP precisa?
As páginas oficiais discordam: o README diz 18 ou mais recente, o guia de primeiros passos diz 20 ou mais recente. Confira node --version e a página que você está lendo de fato antes de confiar em qualquer uma das duas.
O Playwright MCP usa o meu login existente do Chrome?
Não por padrão. O estado do navegador depende do modo isolado, de um diretório user-data, do storage state ou de uma rota de navegador real que você configura separadamente.
Devo usar MCP, CLI ou um navegador real com o Claude Code?
Use MCP para ferramentas de navegador estruturadas dentro do loop do agente. Use a CLI para tarefas orientadas a shell com artefatos em arquivo. Use uma rota de navegador real quando o estado de login aprovado for o requisito.
O ego (lite) pode substituir o Playwright MCP?
Não como um substituto direto da integração MCP. O ego (lite) é um navegador Chromium separado que dá ao agente seu próprio Space isolado e herda o seu estado de login existente, então cobre as tarefas em que o servidor MCP conecta sem problemas, mas a sessão de navegador por trás dele é o obstáculo. Ele não é um servidor MCP e não substitui o Playwright MCP.
