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
1 maintainer
Metadata
1 maintainer
Release files for nexus-mcp 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nexus_mcp-2.1.0.tar.gz | 156.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nexus_mcp-2.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 175.2 kB
Release files / nexus_mcp-2.1.0.tar.gz
| Download URL | nexus_mcp-2.1.0.tar.gz |
|---|---|
| Size | 156.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59cf8d5a93d89de2c9f41755ab282e80300bbf523f3830c02c41c83d2b6fd8ae
|
|
BLAKE2b-256 checksum How to use checksums |
b05931ddcce3a6139a327a1a6ad0de44805fbb5211bb72bf75c70deab979b84e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / nexus_mcp-2.1.0-py3-none-any.whl
| Download URL | nexus_mcp-2.1.0-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eb3867e3e68d11b49cabaa50a40b7fb76cdb40b452ba5c9ccb875222f3199d8f
|
|
BLAKE2b-256 checksum How to use checksums |
a25dd9092e014c2998c591d1f164898e6f9f64975f96945753c9d42f749d08a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency log
