nexus-mcp
Delegates a single coding task to a Claude Code, Codex, or Antigravity agent in your project directory and returns its final answer.
Run one agent turn with
prompt— requiresbackend(claude|codex|antigravity), a taskprompt, and an absolutecwd; returns{backend, session_id, output, usage}.Continue or branch conversations: pass
session_idto resume, orfork=trueto branch it (not supported by Antigravity). Sessions are stored by the agent and survive nexus-mcp restarts.Pick the model per call via
model(id or alias); omit for the provider default.Bound the turn with
timeout(default 600s), after which the turn is cancelled.Control permissions with
profile:read_only(default: read/glob/grep plus safegit diff/log/show),workspace_write(file edits insidecwdplus sandboxed Bash), orfull_access. Out-of-profile actions are auto-denied — nobody is prompted.Discover backends via the
nexus://backendsresource, which lists each backend's installed status, models, and the install hint for missing extras.Use your existing agent auth (Claude login/
ANTHROPIC_API_KEY,codex login, orGEMINI_API_KEY/Vertex ADC) and optionally setNEXUS_CLAUDE_SETTINGS_PROFILEto control which Claude settings load.Parallelize by issuing multiple
promptcalls from the client (replacing v1'sbatch_prompt).
Integrates the Gemini CLI as a tool, allowing AI models to perform parallelized research, summarization, and content generation using Google's AI models.
Enables interaction with the OpenCode CLI to query models via Ollama and Ollama Cloud, supporting structured outputs and concurrent multi-model comparisons.
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 Agent SDK |
|
| Codex App Server |
|
| Antigravity SDK |
|
| 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.
Related MCP server: mcp-cli-catalog
Tool: prompt
Runs one agent turn and returns its final answer.
Parameter | Default | Meaning |
| required |
|
| required | Task for the agent |
| required | Absolute project directory |
|
| Permission profile (below) |
| — | Continue this conversation |
|
| Branch |
| provider default | Model id or alias |
|
| 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/Glob/Grep; |
| Plus file edits inside |
| 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 |
|
| Claude settings to load: |
Migrating from v1
v1 | v2 |
|
|
|
|
| Parallel |
|
|
|
|
|
|
| Cancel the tool call in the client |
| Removed — choose a profile instead |
Preferences, model tiers, MCP prompts | Removed |
OpenCode runners and tools | Removed |
| Removed except |
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
Available Tools
1 toolpromptPromptBDestructive
Run one turn with a coding agent and return its final answer.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path of the project directory. | |
| fork | No | Branch session_id into a new conversation instead of continuing it. | |
| model | No | Model id or alias; the provider default when omitted. | |
| prompt | Yes | Task for the agent. | |
| backend | Yes | Agent to run. | |
| profile | No | Permission profile for the agent. | read_only |
| timeout | No | Seconds before the turn is cancelled. | |
| session_id | No | Continue this conversation (from a previous result). |
Output Schema
| Name | Required | Description |
|---|---|---|
| usage | No | |
| output | Yes | |
| backend | Yes | |
| session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true. The description adds only that it runs 'one turn' and returns a 'final answer,' which is minimal behavioral context. It does not disclose side effects, permission implications, or session handling details beyond what the schema and annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded and contains no redundant or filler language. Every word contributes to the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. Annotations cover the safety profile. However, for a tool with 8 parameters and a destructive, open-world operation, the description lacks usage context and behavioral details that would help an agent invoke it correctly. It is minimally viable given the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description adds no additional semantic meaning for any parameter. Baseline 3 is appropriate when the schema carries the full descriptive burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb and resource: 'Run one turn with a coding agent and return its final answer.' It clearly states what the tool does. However, there are no sibling tools to differentiate from, and the description does not elaborate on scope or distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any preconditions or exclusions. The single sentence simply states the action without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v2.1.0- Changed
prompt1 field changed- changed
Input schema / properties / backend / enumPrevious value: -[ - "claude", - "codex" -]New value: +[ + "claude", + "codex", + "antigravity" +]
20 tool updates
v2.0.1- Removed
agent_backends - Removed
agent_cancel - Removed
agent_continue - Removed
agent_diagnose - Removed
agent_fork - Removed
agent_list - Removed
agent_respond - Removed
agent_result - Removed
agent_review - Removed
agent_start - Removed
agent_status - Removed
batch_prompt - Removed
clear_preferences - Removed
opencode_investigate - Removed
opencode_session_review - Removed
opencode_set_provider_auth - Removed
opencode_update_config - Changed
prompt30 fields changed- added
Input schema / properties / backendAdded value: +{ + "description": "Agent to run.", + "enum": [ + "claude", + "codex" + ], + "type": "string" +} - removed
Input schema / properties / cliRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "description": "CLI runner name (e.g., \"codex\"). None triggers interactive selection.", - "enum": [ - "claude", - "codex", - "opencode", - "opencode_server" - ] -} - removed
Input schema / properties / contextRemoved value: -{ - "anyOf": [ - { - "additionalProperties": true, - "type": "object" - }, - { - "type": "null" - } - ], - "default": null, - "description": "Optional context metadata" -} - added
Input schema / properties / cwdAdded value: +{ + "description": "Absolute path of the project directory.", + "type": "string" +} - removed
Input schema / properties / elicitRemoved value: -{ - "anyOf": [ - { - "type": "boolean" - }, - { - "type": "null" - } - ], - "default": null -} - removed
Input schema / properties / execution_modeRemoved value: -{ - "anyOf": [ - { - "enum": [ - "default", - "yolo" - ], - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "description": "'default' (safe) or 'yolo'. None inherits session preference." -} - added
Input schema / properties / forkAdded value: +{ + "default": false, + "description": "Branch session_id into a new conversation instead of continuing it.", + "type": "boolean" +} - removed
Input schema / properties / max_retriesRemoved value: -{ - "anyOf": [ - { - "type": "integer" - }, - { - "type": "null" - } - ], - "default": null, - "description": "Max retry attempts for transient errors (None inherits session preference)." -} - changed
Input schema / properties / model / descriptionPrevious value: -"Model name. None triggers interactive selection or uses CLI default."New value: +"Model id or alias; the provider default when omitted." - removed
Input schema / properties / output_limitRemoved value: -{ - "anyOf": [ - { - "type": "integer" - }, - { - "type": "null" - } - ], - "default": null, - "description": "Max output bytes (None inherits session preference or uses env default)." -} - added
Input schema / properties / profileAdded value: +{ + "default": "read_only", + "description": "Permission profile for the agent.", + "enum": [ + "read_only", + "workspace_write", + "full_access" + ], + "type": "string" +} - changed
Input schema / properties / prompt / descriptionPrevious value: -"Prompt text to send to the runner"New value: +"Task for the agent." - added
Input schema / properties / prompt / minLengthAdded value: +1 - removed
Input schema / properties / retry_base_delayRemoved value: -{ - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "default": null, - "description": "Base delay seconds for exponential backoff (None inherits session/config)." -} - removed
Input schema / properties / retry_max_delayRemoved value: -{ - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "default": null, - "description": "Backoff ceiling in seconds (None inherits session preference or config)." -} - added
Input schema / properties / session_idAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Continue this conversation (from a previous result)." +} - removed
Input schema / properties / timeout / anyOfRemoved value: -[ - { - "type": "integer" - }, - { - "type": "null" - } -] - changed
Input schema / properties / timeout / defaultPrevious value: -nullNew value: +600 - changed
Input schema / properties / timeout / descriptionPrevious value: -"Subprocess timeout seconds (None inherits session preference or uses env default)."New value: +"Seconds before the turn is cancelled." - added
Input schema / properties / timeout / minimumAdded value: +1 - added
Input schema / properties / timeout / typeAdded value: +"integer" - changed
Input schema / requiredPrevious value: -[ - "prompt" -]New value: +[ + "backend", + "prompt", + "cwd" +] - added
Output schema / descriptionAdded value: +"Final answer of one agent turn." - added
Output schema / properties / backendAdded value: +{ + "type": "string" +} - added
Output schema / properties / outputAdded value: +{ + "type": "string" +} - removed
Output schema / properties / resultRemoved value: -{ - "type": "string" -} - added
Output schema / properties / session_idAdded value: +{ + "type": "string" +} - added
Output schema / properties / usageAdded value: +{ + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null +} - changed
Output schema / requiredPrevious value: -[ - "result" -]New value: +[ + "backend", + "session_id", + "output" +] - removed
Output schema / x-fastmcp-wrap-resultRemoved value: -true
- Removed
set_model_tiers - Removed
set_preferences
16 tool updates
v1.1.0- Added
agent_backends - Added
agent_cancel - Added
agent_continue - Added
agent_diagnose - Added
agent_fork - Added
agent_list - Added
agent_respond - Added
agent_result - Added
agent_review - Added
agent_start - Added
agent_status - Changed
batch_prompt1 field changed- changed
Input schema / properties / max_concurrency / descriptionPrevious value: -"Max parallel runner invocations (default: 3)."New value: +"Max parallel runner invocations for this call (default: 3). The\nprocess worker maximum is 8; one call whose effective demand exceeds 8 is rejected."
- Added
opencode_investigate - Added
opencode_session_review - Added
opencode_set_provider_auth - Added
opencode_update_config
5 tool updates
v1.0.0- Changed
batch_prompt9 fields changed- added
Input schema / properties / elicitAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / max_concurrency / descriptionAdded value: +"Max parallel runner invocations (default: 3)." - added
Input schema / properties / tasks / descriptionAdded value: +"List of AgentTask objects, each with cli, prompt, and optional fields." - added
Input schema / properties / tasks / items / properties / cli / anyOfAdded value: +[ + { + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } +] - added
Input schema / properties / tasks / items / properties / cli / defaultAdded value: +null - changed
Input schema / properties / tasks / items / properties / cli / enumPrevious value: -[ - "claude", - "codex", - "gemini", - "opencode" -]New value: +[ + "claude", + "codex", + "opencode", + "opencode_server" +] - removed
Input schema / properties / tasks / items / properties / cli / minLengthRemoved value: -1 - removed
Input schema / properties / tasks / items / properties / cli / typeRemoved value: -"string" - changed
Input schema / properties / tasks / items / requiredPrevious value: -[ - "cli", - "prompt" -]New value: +[ + "prompt" +]
- Removed
get_preferences - Changed
prompt16 fields changed- added
Input schema / properties / cli / anyOfAdded value: +[ + { + "type": "string" + }, + { + "type": "null" + } +] - added
Input schema / properties / cli / defaultAdded value: +null - added
Input schema / properties / cli / descriptionAdded value: +"CLI runner name (e.g., \"codex\"). None triggers interactive selection." - changed
Input schema / properties / cli / enumPrevious value: -[ - "claude", - "codex", - "gemini", - "opencode" -]New value: +[ + "claude", + "codex", + "opencode", + "opencode_server" +] - removed
Input schema / properties / cli / typeRemoved value: -"string" - added
Input schema / properties / context / descriptionAdded value: +"Optional context metadata" - added
Input schema / properties / elicitAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / execution_mode / descriptionAdded value: +"'default' (safe) or 'yolo'. None inherits session preference." - added
Input schema / properties / max_retries / descriptionAdded value: +"Max retry attempts for transient errors (None inherits session preference)." - added
Input schema / properties / model / descriptionAdded value: +"Model name. None triggers interactive selection or uses CLI default." - added
Input schema / properties / output_limit / descriptionAdded value: +"Max output bytes (None inherits session preference or uses env default)." - added
Input schema / properties / prompt / descriptionAdded value: +"Prompt text to send to the runner" - added
Input schema / properties / retry_base_delay / descriptionAdded value: +"Base delay seconds for exponential backoff (None inherits session/config)." - added
Input schema / properties / retry_max_delay / descriptionAdded value: +"Backoff ceiling in seconds (None inherits session preference or config)." - added
Input schema / properties / timeout / descriptionAdded value: +"Subprocess timeout seconds (None inherits session preference or uses env default)." - changed
Input schema / requiredPrevious value: -[ - "cli", - "prompt" -]New value: +[ + "prompt" +]
- Added
set_model_tiers - Changed
set_preferences24 fields changed- added
Input schema / properties / clear_confirm_high_retriesAdded value: +{ + "default": false, + "type": "boolean" +} - added
Input schema / properties / clear_confirm_large_batchAdded value: +{ + "default": false, + "type": "boolean" +} - added
Input schema / properties / clear_confirm_vague_promptAdded value: +{ + "default": false, + "type": "boolean" +} - added
Input schema / properties / clear_confirm_yoloAdded value: +{ + "default": false, + "type": "boolean" +} - added
Input schema / properties / clear_elicitAdded value: +{ + "default": false, + "type": "boolean" +} - added
Input schema / properties / clear_execution_mode / descriptionAdded value: +"If True, resets execution_mode to None regardless of the\nexecution_mode argument." - added
Input schema / properties / clear_max_retries / descriptionAdded value: +"If True, resets max_retries to None regardless of the argument." - added
Input schema / properties / clear_model / descriptionAdded value: +"If True, resets model to None regardless of the model argument." - added
Input schema / properties / clear_output_limit / descriptionAdded value: +"If True, resets output_limit to None regardless of the argument." - added
Input schema / properties / clear_retry_base_delay / descriptionAdded value: +"If True, resets retry_base_delay to None." - added
Input schema / properties / clear_retry_max_delay / descriptionAdded value: +"If True, resets retry_max_delay to None." - added
Input schema / properties / clear_timeout / descriptionAdded value: +"If True, resets timeout to None regardless of the argument." - added
Input schema / properties / confirm_high_retriesAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / confirm_large_batchAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / confirm_vague_promptAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / confirm_yoloAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / elicitAdded value: +{ + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null +} - added
Input schema / properties / execution_mode / descriptionAdded value: +"Default execution mode ('default' or 'yolo').\nNone retains the current value (use clear_execution_mode=True to reset)." - added
Input schema / properties / max_retries / descriptionAdded value: +"Default max retry attempts for transient errors.\nNone retains the current value (use clear_max_retries=True to reset)." - added
Input schema / properties / model / descriptionAdded value: +"Default model name (e.g. 'gpt-5.2').\nNone retains the current value (use clear_model=True to reset)." - added
Input schema / properties / output_limit / descriptionAdded value: +"Default max output bytes per response.\nNone retains the current value (use clear_output_limit=True to reset)." - added
Input schema / properties / retry_base_delay / descriptionAdded value: +"Default base delay seconds for exponential backoff.\nNone retains the current value (use clear_retry_base_delay=True to reset)." - added
Input schema / properties / retry_max_delay / descriptionAdded value: +"Default max delay cap seconds for exponential backoff.\nNone retains the current value (use clear_retry_max_delay=True to reset)." - added
Input schema / properties / timeout / descriptionAdded value: +"Default subprocess timeout in seconds.\nNone retains the current value (use clear_timeout=True to reset)."
5 tool updates
v0.8.1- First observed
batch_prompt - First observed
clear_preferences - First observed
get_preferences - First observed
prompt - First observed
set_preferences
TDQS
Scored across 1 tool
With only a single tool, there is no possibility of confusing it with another, so misselection is impossible. However, there is no sibling tool to distinguish it from, making the dimension trivially satisfied rather than well-designed.
There is only one tool named 'prompt', a bare noun rather than a verb_noun pattern. With a single name there is nothing to be inconsistent with, but the naming itself is vague about what the tool does.
A single tool is far too thin for a server that wraps a coding agent. Core capabilities like starting a session, sending follow-ups, or checking status are absent, leaving the surface severely under-scoped.
Only one fire-and-forget turn is exposed, with no session lifecycle, multi-turn conversation, cancellation, or status operations. This leaves significant gaps for any realistic agent-driven coding workflow.
Maintenance
Related MCP Connectors
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for building and testing AI agents with multi-model experimentation and insights.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceTurns any shell command into an MCP server by defining command-line tools in simple YAML files. Enables AI agents to execute system commands, security scanners, DevOps tools, and CLI utilities directly from chat interfaces.4-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that publishes CLI tools on your machine for discoverability by LLMs7 npm1MIT
- AlicenseAqualityDmaintenanceMCP server orchestrating local CLI agents (Claude Code, OpenAI Codex, Google Gemini) for cross-validation, second opinions, and persona-driven prompting.18MIT
- AlicenseNot gradedqualityCmaintenanceUniversal MCP server that wraps any CLI tool, enabling AI assistants to run commands via natural language.1MIT