Obter AX Code · GrátisDocumentação
AX Code.
pt-BR
English繁體中文简体中文日本語한국어FrançaisDeutschBahasa IndonesiaItalianoPortuguês (Brasil)РусскийEspañolTürkçeTiếng Việt
Começar

Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Integrações MCP

Status: Ativo Escopo: estado atual Última revisão: 2026-10-09 Responsável: runtime do ax-code

O AX Code pode se conectar a servidores do Model Context Protocol para ferramentas, prompts e recursos externos. O MCP é poderoso, então o AX Code trata a configuração do MCP e o conteúdo fornecido por ele como uma fronteira de confiança.

A ponte experimental do navegador é um caminho separado. Ela abre uma janela isolada do Chrome e pode chamar ferramentas que uma página registra pelo WebMCP. Ative-a pela interface de terminal; os passos e as camadas de aprovação estão na Ponte de navegador WebMCP.

Modelo de confiança

Entradas MCP vindas de fontes de configuração controladas pelo usuário são confiáveis por padrão:

  • configuração global do usuário;
  • configuração administrada;
  • AX_CODE_CONFIG explícito;
  • AX_CODE_CONFIG_CONTENT embutido;
  • acréscimos de runtime por rotas locais autorizadas do runtime.

Entradas MCP vindas de fontes compartilhadas ou descobertas na rede não são confiáveis por padrão:

  • ax-code.json do projeto;
  • configuração de worktree .ax-code;
  • configuração well-known remota.

Entradas MCP não confiáveis aparecem como needs_trust. O AX Code não inicia comandos MCP locais, não conecta URLs MCP remotas, não expõe esquemas de ferramenta MCP, não lista prompts nem recursos e não inicia o OAuth dessa entrada até que ela seja de confiança.

Comandos de confiança

Listar o status do MCP:

ax-code mcp list

Confiar na impressão digital de um servidor:

ax-code mcp trust <name>

Revogar a confiança na impressão digital atual do servidor:

ax-code mcp untrust <name>

Remover um servidor configurado da configuração do projeto atual:

ax-code mcp remove <name> --force

Acrescente --global para remover, em vez disso, da configuração global. A remoção permanece no escopo selecionado e falha se o servidor não existir ali. Omita --force para revisar o caminho de destino antes de confirmar.

A confiança fica armazenada fora do repositório e vale para o projeto atual junto com a impressão digital do servidor. Alterar configuração relevante do MCP, como comando, URL, modo OAuth, cabeçalhos ou valores explícitos de ambiente, invalida a confiança anterior.

Permissões do runtime

A confiança apenas permite que o servidor MCP participe do runtime. Chamadas individuais de ferramenta MCP ainda passam pelas permissões do AX Code.

As chaves de permissão de ferramenta MCP conservam o formato já existente <server>_<tool>. Quando o AX Code identifica um recurso estável a partir dos argumentos da ferramenta, ele pergunta com um padrão mais estreito, por exemplo:

  • url:https://api.example.com/resource
  • uri:mcp-resource
  • path:src/index.ts
  • repo:owner/name
  • db:database.table

Formatos de argumento desconhecidos perguntam sem oferecer, por padrão, uma aprovação durável e ampla.

Prompts, recursos e conteúdo

Prompts e recursos MCP são contexto não confiável. O AX Code controla, por permissões, o uso de prompts MCP e as leituras de recursos MCP, rotula o texto obtido como conteúdo MCP não confiável e trunca texto grande antes de ele entrar no contexto do modelo.

Metadados e saídas de ferramenta MCP também são limitados:

  • esquemas grandes demais são rejeitados antes de a ferramenta ser exposta;
  • descrições longas têm um teto;
  • registros stderr do MCP local são encurtados, e padrões evidentes de segredo são redigidos;
  • o conteúdo de ferramenta MCP apresentado ao modelo usa o mesmo resultado de truncamento da saída de ferramenta visível para quem usa.

MCP do Playwright para HTML e desenvolvimento web

Ao trabalhar em jogos HTML, aplicativos web ou qualquer projeto com index.html na raiz, o AX Code reconhece o projeto como web e impede que o agente abra o navegador por conta própria. Em vez disso, o agente informa as mudanças e espera que você atualize a página.

Para verificação por captura de tela, conecte o servidor MCP do Playwright:

ax-code mcp list --discover   # auto-suggests playwright in web projects

Ou acrescente-o manualmente a ax-code.json:

{
  "mcp": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--cdp-url", "http://localhost:9222"]
    }
  }
}

Modo de anexação CDP

Se o Chrome estiver em execução com --remote-debugging-port=9222, o AX Code o detecta e conecta no modo de anexação CDP. O agente pode chamar browser_screenshot para capturar a aba ao vivo, sem abrir uma janela nova nem tomar o foco.

Para iniciar o Chrome com o CDP ativado:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Alternativa sem interface

Sem uma porta CDP do Chrome aberta, @playwright/mcp inicia uma instância do Chromium sem interface. As capturas de tela ainda aparecem embutidas na TUI.

Instalação global

Se @playwright/mcp estiver instalado de forma global (npm install -g @playwright/mcp), o AX Code usa o binário playwright-mcp diretamente, em vez de executá-lo por npx, o que é mais rápido no primeiro uso.

Nota de segurança

O servidor MCP do Playwright ganha capacidade relevante sobre o navegador. Quando vem da configuração do projeto (ax-code.json), ele não é de confiança até que você a conceda de forma explícita com ax-code mcp trust playwright. Entradas da configuração global do usuário se conectam sozinhas depois da primeira aprovação.

Modo de servidor

Rotas HTTP do MCP que alteram estado exigem um cabeçalho de autorização do runtime, local ao processo, além das proteções gerais do servidor. Isso protege ações locais de controle do runtime, como adicionar, conectar, desconectar e autenticar servidores MCP. O status somente leitura do MCP continua disponível por GET /mcp.

MCP do Figma

Figma para desktop

No aplicativo Figma para desktop, abra um arquivo de design, mude para o Dev Mode e ative o servidor MCP de desktop no painel de inspeção. Abrir só o aplicativo não ativa o servidor. Veja as instruções de configuração para desktop do Figma.

Acrescente esta entrada à configuração do AX Code:

{
  "mcp": {
    "figma-desktop": {
      "type": "remote",
      "url": "http://127.0.0.1:3845/mcp",
      "allowLoopback": true,
      "oauth": false
    }
  }
}

Em uma configuração de projeto, revise a entrada e conceda confiança:

ax-code mcp trust figma-desktop

type: "remote" seleciona o transporte HTTP/SSE, inclusive servidores HTTP nesta máquina. type: "local" seleciona um subprocesso que usa stdio.

Política de MCP HTTP em loopback

allowLoopback vem como false por padrão. Defini-lo como true permite HTTP(S) em localhost, 127.0.0.1 ou [::1] apenas no esquema, no nome de host e na porta configurados. Exige uma URL de loopback sem credenciais embutidas. Entradas compartilhadas de projeto ainda exigem confiança; ativar a opção invalida a confiança concedida antes, sem essa opção.

Redirecionamentos, endpoints de mensagem SSE e pedidos de OAuth precisam permanecer nessa mesma origem. Outras portas, destinos públicos, endereços de rede privada e endpoints de metadados de nuvem continuam bloqueados. As respostas DNS de localhost precisam ser todas endereços de loopback e ficam fixadas em cada conexão. Serviços locais que dependem de um emissor OAuth externo não são suportados por esta opção. Use oauth: false para o Figma Desktop.

Se a conexão for recusada, confira se o servidor MCP de desktop está ativado e escutando na porta 3845. Passar para localhost, ou desativar só o OAuth, não habilita o acesso por loopback.

OAuth remoto do Figma (mcp.figma.com)

O endpoint hospedado do Figma é https://mcp.figma.com/mcp. O Figma exige um cliente aprovado no Catálogo MCP. Quem desenvolve clientes precisa seguir os requisitos de registro de acesso remoto do Figma.

Um registro dinâmico rejeitado não se resolve apenas com a criação de um aplicativo OAuth comum do Figma, nem com o ID e o segredo de cliente dele. Use credenciais emitidas para uma integração MCP aprovada, quando existirem. O AX Code informa a exigência do Catálogo quando o endpoint oficial rejeita o registro. O acesso por loopback não concede aprovação do servidor hospedado.

Modelo baseado em token

O modelo integrado figma executa o pacote separado figma-developer-mcp com FIGMA_API_KEY. Ele é distinto dos servidores MCP oficiais do Figma para desktop e hospedado.