# Conecte seu agente

> Fonte: https://astrallab.dev/pt/docs/connect

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](https://astrallab.dev/pt/docs/platforms.md).

## 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`:

```bash
"/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.

| Opção | Efeito |
| --- | --- |
| `--client` | `claude-code`, `codex`, `vscode` (também Copilot), `cursor`, `windsurf`, `antigravity`, `jetbrains`, `gemini-cli`, `orca` ou `all-detected`. Vários podem ser separados por vírgulas. |
| `--project [DIR]` | A configuração do projeto (por padrão, o diretório atual). |
| `--global` | A configuração do usuário, para todos os projetos. É o padrão quando o cliente tem um arquivo global documentado. |
| `--print` | Mostra o trecho e onde ele entra; não escreve nada. |
| `--dry-run` | Mostra o diff; não escreve nada. |
| `--instructions` | Também adiciona a seção do Astral ao `AGENTS.md` do projeto (`GEMINI.md` para o Gemini CLI). |
| `--binary PATH` | Registra esse `astral-mcp` em vez do que está em execução. |
| `--list` | Lista os clientes, seus arquivos e se cada um foi encontrado nesta máquina. |

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](#claude-code)
- [Codex (CLI e IDE)](#codex)
- [VS Code e GitHub Copilot](#vscode)
- [Cursor](#cursor)
- [Windsurf](#windsurf)
- [Antigravity](#antigravity)
- [Gemini CLI](#gemini-cli)
- [JetBrains AI Assistant](#jetbrains)
- [Orca](#orca)
- [OpenCode](#opencode)
- [Qualquer outro cliente MCP](#any)

### Claude Code

```bash
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.

**Configuração manual: .mcp.json (projeto), ou o comando abaixo para todos os projetos**

```
{
  "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 caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

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](https://code.claude.com/docs/en/mcp).

### Codex (CLI e IDE)

```bash
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.

**Configuração manual: ~/.codex/config.toml**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

Fonte: [Codex: MCP](https://developers.openai.com/codex/mcp).

### VS Code e GitHub Copilot

```bash
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.

**Configuração manual: .vscode/mcp.json**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

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

Fonte: [VS Code: MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration), [VS Code: Add MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

### Cursor

```bash
astral-mcp setup --client cursor
```

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

**Configuração manual: ~/.cursor/mcp.json**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

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

Fonte: [Cursor: MCP](https://cursor.com/docs/mcp).

### Windsurf

```bash
astral-mcp setup --client windsurf
```

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

**Configuração manual: ~/.codeium/windsurf/mcp\_config.json**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

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](https://docs.devin.ai/cli/reference/configuration/read-config-from), [VS Code: MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

### Antigravity

```bash
astral-mcp setup --client antigravity
```

Escreve ~/.gemini/config/mcp\_config.json. Com --project, escreve .agents/mcp\_config.json.

**Configuração manual: ~/.gemini/config/mcp\_config.json**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

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

Fonte: [Antigravity: MCP](https://antigravity.google/docs/mcp).

### Gemini CLI

```bash
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.

**Configuração manual: ~/.gemini/settings.json**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

Execute /mcp dentro do gemini para verificar.

Fonte: [Gemini CLI: MCP servers](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md), [Gemini CLI: configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md).

### JetBrains AI Assistant

```bash
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).

**Configuração manual: configurações da IDE (sem arquivo)**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

Fonte: [JetBrains: AI Assistant MCP](https://www.jetbrains.com/help/ai-assistant/mcp.html).

### Orca

```bash
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>.

**Configuração manual: configurações do Orca (sem arquivo)**

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

O caminho acima é o do macOS; use o caminho do `astral-mcp` na sua máquina.

Fonte: [Orca docs](https://www.onorca.dev/docs/cli/skills).

### 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:

```bash
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`:

**Configuração manual: opencode.jsonc (V2, documentação mais recente)**

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

**Configuração manual: opencode.jsonc (documentação V1)**

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

A V1 coloca o servidor diretamente em `mcp`; a V2 o coloca em `mcp.servers`. Use a que corresponde à sua versão do OpenCode.

Fonte: [OpenCode: MCP servers](https://opencode.ai/docs/mcp-servers/) (V2) e [a página da V1](https://opencode.ai/v1/docs/mcp-servers/). 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:

| Campo | Valor |
| --- | --- |
| Transporte | stdio |
| Comando | o caminho do `astral-mcp` (macOS: `/Applications/Astral.app/Contents/MacOS/astral-mcp`) |
| Argumentos | nenhum |
| Ambiente | nenhum |

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](https://astrallab.dev/pt/docs/tools.md). 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`.