nexus-mcp

# nexus-mcp
<!-- mcp-name: io.github.j7an/nexus-mcp -->

MCP server that delegates tasks to coding agents — [Claude Code](https://code.claude.com)
via the Claude Agent SDK, [Codex](https://developers.openai.com/codex) via the Codex App Server,
and Antigravity via the Antigravity SDK — from any MCP client.

## Install

Backends are optional extras; install the ones you use.

| Extra | Backend | Adds |
|---|---|---|
| `claude` | Claude Agent SDK | `claude-agent-sdk` (bundles the Claude Code CLI, ~100 MB) |
| `codex` | Codex App Server | `openai-codex` (bundles the Codex CLI, ~120–150 MB) |
| `antigravity` | Antigravity SDK | `google-antigravity` (bundles the Antigravity Go harness, ~40 MB) |
| `all` | every backend | |

```bash
uvx --with 'nexus-mcp[all]' nexus-mcp          # run directly
pip install 'nexus-mcp[claude]'                 # or install
pip install 'nexus-mcp[codex]'                  # Codex only
pip install 'nexus-mcp[antigravity]'
```

Claude Code MCP config:

```json
{ "mcpServers": { "nexus": { "command": "uvx", "args": ["--with", "nexus-mcp[all]", "nexus-mcp"] } } }
```

Authentication is the agent's own: log in with `claude`, or set `ANTHROPIC_API_KEY`; for Codex,
log in with `codex login` (credentials in `~/.codex` are shared). Antigravity uses `GEMINI_API_KEY`,
or Vertex AI with `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`, and
`GOOGLE_CLOUD_LOCATION`, authenticated through Application Default Credentials (ADC). It does not
use Google-account login.

**Windows:** recent `claude-agent-sdk` releases ship no Windows wheel with a bundled CLI;
install Claude Code so `claude` is on `PATH`.

## Tool: `prompt`

Runs one agent turn and returns its final answer.

| Parameter | Default | Meaning |
|---|---|---|
| `backend` | required | `claude`, `codex`, or `antigravity` |
| `prompt` | required | Task for the agent |
| `cwd` | required | Absolute project directory |
| `profile` | `read_only` | Permission profile (below) |
| `session_id` | — | Continue this conversation |
| `fork` | `false` | Branch `session_id` into a new conversation |
| `model` | provider default | Model id or alias |
| `timeout` | `600` | Seconds before the turn is cancelled |

Returns `{backend, session_id, output, usage}`. Conversations are stored by the agent itself
(`~/.claude/projects`, `$CODEX_HOME/sessions`, `~/.nexus-mcp/antigravity`), so a `session_id` keeps
working after nexus-mcp restarts. Antigravity does not support `fork=true`.

### Permission profiles

Actions outside the chosen profile are denied automatically — nobody is prompted.

| Profile | Allows |
|---|---|
| `read_only` | Read/Glob/Grep; `git diff`/`log`/`show` with `--no-ext-diff --no-textconv` |
| `workspace_write` | Plus file edits inside `cwd` and Bash inside the OS sandbox |
| `full_access` | Everything |

Codex enforces profiles with its OS sandbox (`read-only`, `workspace-write`, `danger-full-access`)
and never asks for approval.

Antigravity enforces workspace containment in its harness and uses the OS sandbox for commands.
`workspace_write` fails if that sandbox is unavailable.

## Resource: `nexus://backends`

JSON list of `{name, installed, models, hint}`; `hint` gives the install command for a
missing extra. Codex lists its models; Claude and Antigravity report `null` (Antigravity does not
provide a model list).

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `NEXUS_CLAUDE_SETTINGS_PROFILE` | `isolated` | Claude settings to load: `isolated` (none), `project` (project `.claude/`), `inherit` (all, including user settings). Profiles still bound every tool call. |

## Migrating from v1

| v1 | v2 |
|---|---|
| `prompt(cli="codex")` (`codex exec`) | `prompt(backend="codex", cwd=…)` (App Server) |
| `prompt(cli=…, execution_mode="yolo")` | `prompt(backend=…, profile="full_access", cwd=…)` |
| `batch_prompt` | Parallel `prompt` calls from the client |
| `agent_start` / `agent_status` / `agent_result` | `prompt` (synchronous) |
| `agent_continue` / `agent_fork` | `prompt(session_id=…)` / `prompt(session_id=…, fork=true)` |
| `agent_review` | `prompt(profile="read_only", prompt="Review …")` |
| `agent_cancel` | Cancel the tool call in the client |
| `agent_respond`, elicitation | Removed — choose a profile instead |
| Preferences, model tiers, MCP prompts | Removed |
| OpenCode runners and tools | Removed |
| `NEXUS_*` variables | Removed except `NEXUS_CLAUDE_SETTINGS_PROFILE` |

## Development

```bash
uv sync --all-extras --all-groups
uv run pytest                    # unit + e2e
uv run pytest -m integration     # real CLI (slow, makes model calls)
uv run mypy src/nexus_mcp && uv run ruff check . && uv run ruff format --check .
```

## License

MIT