# Connect your agent

> Source: https://astrallab.dev/docs/connect

Astral's MCP server is a local one: your coding agent starts `astral-mcp`, which talks to the open app. Every client below needs the same thing, the path to that binary. `astral-mcp setup` writes it for you.

## Before you start

- **Astral is open, with Developer mode and MCP turned on** (Settings → Developer). The agent talks to the running app; with Astral closed the bridge reports an error.
- **No API key and no environment variables.** The bridge authenticates with a token from the local socket at run time. `setup` only writes the binary path and an empty `args` list.
- **The binary ships inside the installer.** On macOS it is `/Applications/Astral.app/Contents/MacOS/astral-mcp`. The **Connection** card in Settings → Developer shows the exact path on your machine. The Windows and Linux install paths are not documented here, and the Windows build is not verified on a real machine.
- Developer mode is tested on macOS and Linux (X11) and compiled but not verified on Windows; see [Platforms](https://astrallab.dev/docs/platforms.md).

## The setup command

Run it with the binary's full path (it is not on your `PATH`), or add that folder to `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
```

The examples below write `astral-mcp` for short.

| Option | Effect |
| --- | --- |
| `--client` | `claude-code`, `codex`, `vscode` (also Copilot), `cursor`, `windsurf`, `antigravity`, `jetbrains`, `gemini-cli`, `orca`, or `all-detected`. Several can be separated by commas. |
| `--project [DIR]` | The project's config (the current directory by default). |
| `--global` | The user's config, for every project. It is the default when the client has a documented global file. |
| `--print` | Shows the snippet and where it goes; writes nothing. |
| `--dry-run` | Shows the diff; writes nothing. |
| `--instructions` | Also adds Astral's section to the project's `AGENTS.md` (`GEMINI.md` for Gemini CLI). |
| `--binary PATH` | Registers that `astral-mcp` instead of the one running. |
| `--list` | Lists the clients, their files and whether each is found on this machine. |

Setup merges into the file instead of overwriting it: other servers and keys are kept, only the `astral` entry changes, a file that already has it right is left alone, and an existing file is copied to `<file>.astral-backup-<timestamp>` first. A malformed file is reported with its line and column and nothing is written. `all-detected` is a heuristic: a client counts as installed if its config folder exists or its command is on `PATH`.

## By client

- [Claude Code](#claude-code)
- [Codex (CLI and IDE)](#codex)
- [VS Code and GitHub Copilot](#vscode)
- [Cursor](#cursor)
- [Windsurf](#windsurf)
- [Antigravity](#antigravity)
- [Gemini CLI](#gemini-cli)
- [JetBrains AI Assistant](#jetbrains)
- [Orca](#orca)
- [OpenCode](#opencode)
- [Any other MCP client](#any)

### Claude Code

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

Writes .mcp.json in the project. Without --project it prints the official command for the user scope instead of editing ~/.claude.json, which Claude Code rewrites on every session.

**Manual config: .mcp.json (project), or the command below for every project**

```
{
  "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
```

The path above is the macOS one; use the path of `astral-mcp` on your machine.

Claude Code asks you to approve a project server from .mcp.json the first time you start claude there.

Source: [Claude Code: MCP](https://code.claude.com/docs/en/mcp).

### Codex (CLI and IDE)

```bash
astral-mcp setup --client codex
```

Adds \[mcp\_servers.astral\] to ~/.codex/config.toml (or $CODEX\_HOME/config.toml), keeping comments and formatting. With --project it writes .codex/config.toml, which Codex only reads in trusted projects.

**Manual config: ~/.codex/config.toml**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

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

### VS Code and GitHub Copilot

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

Writes .vscode/mcp.json, read by VS Code and by Copilot's agent mode. Without --project it writes ~/.copilot/mcp-config.json (the Copilot global file, also read by GitHub Copilot CLI), which uses mcpServers instead of servers.

**Manual config: .vscode/mcp.json**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

Start the server from the CodeLens above it in the file, or from the MCP: List Servers command.

Source: [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
```

Writes ~/.cursor/mcp.json. With --project it writes .cursor/mcp.json.

**Manual config: ~/.cursor/mcp.json**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

Reload the MCP servers or restart Cursor to pick it up.

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

### Windsurf

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

Writes ~/.codeium/windsurf/mcp\_config.json. Windsurf has no per-project MCP config.

**Manual config: ~/.codeium/windsurf/mcp\_config.json**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

Reload the MCP servers or restart Windsurf. The next and insiders channels use other folders (~/.codeium/windsurf-next, ~/.codeium/windsurf-insiders) that setup does not write.

Source: [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
```

Writes ~/.gemini/config/mcp\_config.json. With --project it writes .agents/mcp\_config.json.

**Manual config: ~/.gemini/config/mcp\_config.json**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

Reload the MCP servers or restart Antigravity. Older installs used ~/.gemini/antigravity/mcp\_config.json.

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

### Gemini CLI

```bash
astral-mcp setup --client gemini-cli
```

Merges an mcpServers entry into ~/.gemini/settings.json and keeps the rest of your settings. With --project it writes .gemini/settings.json.

**Manual config: ~/.gemini/settings.json**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

Run /mcp inside gemini to check it.

Source: [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
```

JetBrains keeps MCP servers in the IDE settings, not in a documented file, so setup prints the JSON instead of writing it. In Settings | Tools | AI Assistant | Model Context Protocol (MCP), choose Add, then JSON configuration, paste it and pick the server level (global or this project).

**Manual config: IDE settings (no file)**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

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

### Orca

```bash
astral-mcp setup --client orca --print
```

Orca runs other agents (Claude Code, Codex and so on) and forwards the MCP servers registered in Settings → Integrations → MCP to them. Register the astral-mcp path there, or set up the agent you run inside Orca, for example --client claude-code --project <worktree>.

**Manual config: Orca settings (no file)**

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

The path above is the macOS one; use the path of `astral-mcp` on your machine.

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

### OpenCode

`astral-mcp setup` does not support OpenCode, so configure it by hand. OpenCode's docs describe a local server as a command it starts over stdio. Its latest docs (V2) add one from the terminal:

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

Add `--global` to make it available in every project; without it the server goes in the project's configuration. By hand, in `opencode.jsonc`:

**Manual config: opencode.jsonc (V2, latest docs)**

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

**Manual config: opencode.jsonc (V1 docs)**

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

V1 puts the server directly under `mcp`; V2 puts it under `mcp.servers`. Use the one that matches your OpenCode version.

Source: [OpenCode: MCP servers](https://opencode.ai/docs/mcp-servers/) (V2) and [the V1 page](https://opencode.ai/v1/docs/mcp-servers/). Not tested against a running OpenCode.

### Any other MCP client

Astral's server is a standard stdio MCP server. In any client that can launch one, register:

| Field | Value |
| --- | --- |
| Transport | stdio |
| Command | the path to `astral-mcp` (macOS: `/Applications/Astral.app/Contents/MacOS/astral-mcp`) |
| Arguments | none |
| Environment | none |

Most clients take that as JSON with a `command` and an `args` list, as in the snippets above. Check your client's own MCP page for the file name and the top-level key.

## Check that it works

With Astral open and Developer mode on, restart or reload the agent's MCP servers and ask:

```
List the tools you have from the Astral MCP server.
```

You should see the tools from the [tool reference](https://astrallab.dev/docs/tools.md). For a call that touches the app, ask it to run `test_list` in your project: it returns your saved tests, or an empty list. In Gemini CLI, `/mcp` shows the server and its status.

### If it does not show up

- Make sure Astral is running and Developer → MCP is on, then reload the client's MCP servers.
- Run `astral-mcp setup --list` to see where each client's file is and whether it was detected.
- Run the same command with `--dry-run` to see what would change, or `--print` for the snippet.
- Rerunning setup is safe: it changes nothing if the entry is already right.
- Add `--instructions` so the agent also gets Astral's short usage guide in `AGENTS.md`.