Conecte seu agente

O servidor MCP do Astral é local: seu agente de programação inicia o astral-mcp, que conversa com o app aberto. Todos os clientes abaixo precisam da mesma coisa, o caminho desse binário. O astral-mcp setup o escreve para você.

Antes de começar

• O Astral está aberto, com o Developer mode e o MCP ativados (Settings → Developer). O agente conversa com o app em execução; com o Astral fechado, a ponte informa um erro.
• Sem chave de API e sem variáveis de ambiente. A ponte se autentica em tempo de execução com um token do socket local. O setup só escreve o caminho do binário e uma lista args vazia.
• O binário vem dentro do instalador. No macOS, é /Applications/Astral.app/Contents/MacOS/astral-mcp. O cartão Connection em Settings → Developer mostra o caminho exato na sua máquina. Os caminhos de instalação do Windows e do Linux não estão documentados aqui, e a versão para Windows não está verificada em uma máquina real.
• O modo desenvolvedor é testado no macOS e no Linux (X11) e compilado, mas não verificado, no Windows; veja Plataformas.

O comando setup

Execute-o com o caminho completo do binário (ele não está no seu PATH), ou adicione essa pasta ao PATH:

"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client <name> [--project [DIR] | --global] [--print] [--dry-run] [--instructions] [--binary PATH]
"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client all-detected --dry-run
"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --list

Nos exemplos abaixo, escreve-se astral-mcp por brevidade.

O setup mescla as alterações no arquivo em vez de sobrescrevê-lo: os outros servidores e chaves são preservados, só a entrada astral muda, um arquivo que já a tem correta não é tocado, e um arquivo existente é copiado antes para <arquivo>.astral-backup-<timestamp>. Um arquivo malformado é reportado com a linha e a coluna e nada é escrito. all-detected é uma heurística: um cliente conta como instalado se a sua pasta de configuração existe ou se o seu comando está no PATH.

Por cliente

• Claude Code
• Codex (CLI e IDE)
• VS Code e GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• Gemini CLI
• JetBrains AI Assistant
• Orca
• OpenCode
• Qualquer outro cliente MCP

Claude Code

astral-mcp setup --client claude-code --project .

Escreve .mcp.json no projeto. Sem --project, imprime o comando oficial para o escopo de usuário em vez de editar ~/.claude.json, que o Claude Code reescreve a cada sessão.

{
  "mcpServers": {
    "astral": {
      "type": "stdio",
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

# user scope, every project:
claude mcp add --scope user astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp

O Claude Code pede que você aprove um servidor de projeto vindo do .mcp.json na primeira vez que você inicia o claude ali.

Fonte: Claude Code: MCP.

Codex (CLI e IDE)

astral-mcp setup --client codex

Adiciona [mcp_servers.astral] a ~/.codex/config.toml (ou $CODEX_HOME/config.toml), preservando comentários e formatação. Com --project, escreve .codex/config.toml, que o Codex só lê em projetos confiáveis.

[mcp_servers.astral]
command = "/Applications/Astral.app/Contents/MacOS/astral-mcp"
args = []

Fonte: Codex: MCP.

VS Code e GitHub Copilot

astral-mcp setup --client vscode --project .

Escreve .vscode/mcp.json, lido pelo VS Code e pelo modo agente do Copilot. Sem --project, escreve ~/.copilot/mcp-config.json (o arquivo global do Copilot, também lido pelo GitHub Copilot CLI), que usa mcpServers em vez de servers.

{
  "servers": {
    "astral": {
      "type": "stdio",
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Inicie o servidor pelo CodeLens acima dele no arquivo, ou pelo comando MCP: List Servers.

Fonte: VS Code: MCP configuration reference, VS Code: Add MCP servers.

Cursor

astral-mcp setup --client cursor

Escreve ~/.cursor/mcp.json. Com --project, escreve .cursor/mcp.json.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Recarregue os servidores MCP ou reinicie o Cursor para que ele o reconheça.

Fonte: Cursor: MCP.

Windsurf

astral-mcp setup --client windsurf

Escreve ~/.codeium/windsurf/mcp_config.json. O Windsurf não tem configuração MCP por projeto.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Recarregue os servidores MCP ou reinicie o Windsurf. Os canais next e insiders usam outras pastas (~/.codeium/windsurf-next, ~/.codeium/windsurf-insiders) nas quais o setup não escreve.

Fonte: Devin CLI: configuration import, VS Code: MCP configuration reference.

Antigravity

astral-mcp setup --client antigravity

Escreve ~/.gemini/config/mcp_config.json. Com --project, escreve .agents/mcp_config.json.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Recarregue os servidores MCP ou reinicie o Antigravity. Instalações antigas usavam ~/.gemini/antigravity/mcp_config.json.

Fonte: Antigravity: MCP.

Gemini CLI

astral-mcp setup --client gemini-cli

Mescla uma entrada mcpServers em ~/.gemini/settings.json e mantém o restante das suas configurações. Com --project, escreve .gemini/settings.json.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Execute /mcp dentro do gemini para verificar.

Fonte: Gemini CLI: MCP servers, Gemini CLI: configuration.

JetBrains AI Assistant

astral-mcp setup --client jetbrains --print

A JetBrains guarda os servidores MCP nas configurações da IDE, e não em um arquivo documentado, então o setup imprime o JSON em vez de escrevê-lo. Em Settings | Tools | AI Assistant | Model Context Protocol (MCP), escolha Add, depois JSON configuration, cole o JSON e escolha o nível do servidor (global ou este projeto).

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Fonte: JetBrains: AI Assistant MCP.

Orca

astral-mcp setup --client orca --print

O Orca executa outros agentes (Claude Code, Codex etc.) e repassa a eles os servidores MCP registrados em Settings → Integrations → MCP. Registre ali o caminho do astral-mcp, ou configure o agente que você executa dentro do Orca, por exemplo --client claude-code --project <worktree>.

# Settings → Integrations → MCP → command:
/Applications/Astral.app/Contents/MacOS/astral-mcp

Fonte: Orca docs.

OpenCode

O astral-mcp setup não oferece suporte ao OpenCode, então configure-o manualmente. A documentação do OpenCode descreve um servidor local como um comando que ele inicia via stdio. Sua documentação mais recente (V2) adiciona um pelo terminal:

opencode mcp add astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp
opencode mcp list

Acrescente --global para disponibilizá-lo em todos os projetos; sem ele, o servidor vai para a configuração do projeto. Manualmente, em opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "astral": {
        "type": "local",
        "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"]
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "astral": {
      "type": "local",
      "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"],
      "enabled": true
    }
  }
}

Fonte: OpenCode: MCP servers (V2) e a página da V1. Não testado com um OpenCode em execução.

Qualquer outro cliente MCP

O servidor do Astral é um servidor MCP stdio padrão. Em qualquer cliente que consiga iniciar um, registre:

A maioria dos clientes aceita isso como JSON com um command e uma lista args, como nos trechos acima. Consulte a página de MCP do seu cliente para saber o nome do arquivo e a chave de nível superior.

Verifique se funciona

Com o Astral aberto e o modo desenvolvedor ativado, reinicie ou recarregue os servidores MCP do agente e pergunte:

Liste as ferramentas que você tem do servidor MCP do Astral.

Você deve ver as ferramentas da referência de ferramentas. Para uma chamada que toque o app, peça que ele execute test_list no seu projeto: ele retorna seus testes salvos, ou uma lista vazia. No Gemini CLI, /mcp mostra o servidor e o seu status.

Se ele não aparecer

• Confirme que o Astral está em execução e que Developer → MCP está ativado, e então recarregue os servidores MCP do cliente.
• Execute astral-mcp setup --list para ver onde está o arquivo de cada cliente e se ele foi detectado.
• Execute o mesmo comando com --dry-run para ver o que mudaria, ou com --print para ver o trecho.
• Executar o setup de novo é seguro: ele não altera nada se a entrada já estiver correta.
• Acrescente --instructions para que o agente receba também o guia de uso curto do Astral em AGENTS.md.