Nexus Mcp

nexus-mcp

MCP server that delegates tasks to coding agents — Claude Code via the Claude Agent SDK, 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

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:

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

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