Delegate tasks to coding agents (Claude, Codex, Antigravity) from any MCP client
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.
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.
promptRuns 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.
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.
nexus://backendsJSON 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).
| 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. |
| 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 |
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 .
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx nexus-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-j7an-nexus-mcp": {
"command": "uvx",
"args": [
"nexus-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencenexus-mcppypiio.github.j7an/nexus-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.