About nexus-mcp
nexus-mcp is an MCP server for delegating tasks to Claude Code, Codex, or Antigravity from an MCP client. It offers synchronous agent turns, resumable sessions, and permission profiles that constrain actions.
Key features
- 01Delegate tasks to three agent backends
- 02Continue or fork sessions
- 03Read-only, workspace-write, and full-access profiles
- 04Set model and timeout per turn
- 05Discover backend availability and models
Use cases
- 01Ask a coding agent to change a project
- 02Review code with read-only permissions
- 03Resume a task in an existing agent session
- 04Check installed backends before routing a task
MCP support
The MCP server exposes a `prompt` tool for running agent turns and a `nexus://backends` resource listing backend availability and model information.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEnexus-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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.