Connect your agent

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.

The setup command

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

The examples below write astral-mcp for short.

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
• Codex (CLI and IDE)
• VS Code and GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• Gemini CLI
• JetBrains AI Assistant
• Orca
• OpenCode
• Any other MCP client

Claude Code

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.

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

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

Source: Claude Code: MCP.

Codex (CLI and IDE)

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.

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

Source: Codex: MCP.

VS Code and GitHub Copilot

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.

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

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

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

Cursor

astral-mcp setup --client cursor

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

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

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

Source: Cursor: MCP.

Windsurf

astral-mcp setup --client windsurf

Writes ~/.codeium/windsurf/mcp_config.json. Windsurf has no per-project MCP config.

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

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, VS Code: MCP configuration reference.

Antigravity

astral-mcp setup --client antigravity

Writes ~/.gemini/config/mcp_config.json. With --project it writes .agents/mcp_config.json.

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

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

Source: Antigravity: MCP.

Gemini CLI

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.

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

Run /mcp inside gemini to check it.

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

JetBrains AI Assistant

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

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

Source: JetBrains: AI Assistant MCP.

Orca

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

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

Source: Orca docs.

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:

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:

{
  "$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
    }
  }
}

Source: OpenCode: MCP servers (V2) and the V1 page. 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:

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