nexus-mcp
MCP server that delegates tasks to coding agents — Claude Code via the Claude Agent SDK and Codex via the Codex App Server — 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) |
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
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).
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 or codex |
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), so a session_id keeps working after nexus-mcp
restarts.
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.
Resource: nexus://backends
JSON list of {name, installed, models, hint}; hint gives the install command for a
missing extra. Codex lists its models; Claude reports null (any id or alias the CLI accepts).
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
Release files for nexus-mcp 2.0.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.0.0.tar.gz | 130.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nexus_mcp-2.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 146.3 kB
Release files / nexus_mcp-2.0.0.tar.gz
| Download URL | nexus_mcp-2.0.0.tar.gz |
|---|---|
| Size | 130.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e855fa145371ea8586a4d4eb5300109cff70a5e0938f52408f96d05a9f7ec063
|
|
BLAKE2b-256 checksum How to use checksums |
4a20052fc0aa83f7f5b2e60a2e693bb43c83e94aa489d7b048ac864478b733e7
|
| 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 Sep 26, 2026.
Transparency logRelease files / nexus_mcp-2.0.0-py3-none-any.whl
| Download URL | nexus_mcp-2.0.0-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
abd963509f8957237da9ff68a53d27d75722c20637d96f957a47f0fbfb9a5e01
|
|
BLAKE2b-256 checksum How to use checksums |
dd6bdee62561018ae9ff4c846e704322e7411f835b19c78dcd14fc5564bd815f
|
| 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 Sep 26, 2026.
Transparency log
