Skip to main content
Glama

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.

Related MCP server: mcp-cli-catalog

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

Available Tools

1 tool
promptPromptB
Destructive

Run one turn with a coding agent and return its final answer.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdYesAbsolute path of the project directory.
forkNoBranch session_id into a new conversation instead of continuing it.
modelNoModel id or alias; the provider default when omitted.
promptYesTask for the agent.
backendYesAgent to run.
profileNoPermission profile for the agent.read_only
timeoutNoSeconds before the turn is cancelled.
session_idNoContinue this conversation (from a previous result).

Output Schema

ParametersJSON Schema
NameRequiredDescription
usageNo
outputYes
backendYes
session_idYes

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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. 1 tool updatev2.1.0
    • Changedprompt1 field changed
      • changedInput schema / properties / backend / enum
        Previous value: -[
        -  "claude",
        -  "codex"
        -]New value: +[
        +  "claude",
        +  "codex",
        +  "antigravity"
        +]
  2. 20 tool updatesv2.0.1
    • Removedagent_backends
    • Removedagent_cancel
    • Removedagent_continue
    • Removedagent_diagnose
    • Removedagent_fork
    • Removedagent_list
    • Removedagent_respond
    • Removedagent_result
    • Removedagent_review
    • Removedagent_start
    • Removedagent_status
    • Removedbatch_prompt
    • Removedclear_preferences
    • Removedopencode_investigate
    • Removedopencode_session_review
    • Removedopencode_set_provider_auth
    • Removedopencode_update_config
    • Changedprompt30 fields changed
      • addedInput schema / properties / backend
        Added value: +{
        +  "description": "Agent to run.",
        +  "enum": [
        +    "claude",
        +    "codex"
        +  ],
        +  "type": "string"
        +}
      • removedInput schema / properties / cli
        Removed 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"
        -  ]
        -}
      • removedInput schema / properties / context
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "additionalProperties": true,
        -      "type": "object"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null,
        -  "description": "Optional context metadata"
        -}
      • addedInput schema / properties / cwd
        Added value: +{
        +  "description": "Absolute path of the project directory.",
        +  "type": "string"
        +}
      • removedInput schema / properties / elicit
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "type": "boolean"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null
        -}
      • removedInput schema / properties / execution_mode
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "enum": [
        -        "default",
        -        "yolo"
        -      ],
        -      "type": "string"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null,
        -  "description": "'default' (safe) or 'yolo'. None inherits session preference."
        -}
      • addedInput schema / properties / fork
        Added value: +{
        +  "default": false,
        +  "description": "Branch session_id into a new conversation instead of continuing it.",
        +  "type": "boolean"
        +}
      • removedInput schema / properties / max_retries
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "type": "integer"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null,
        -  "description": "Max retry attempts for transient errors (None inherits session preference)."
        -}
      • changedInput schema / properties / model / description
        Previous value: -"Model name. None triggers interactive selection or uses CLI default."New value: +"Model id or alias; the provider default when omitted."
      • removedInput schema / properties / output_limit
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "type": "integer"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null,
        -  "description": "Max output bytes (None inherits session preference or uses env default)."
        -}
      • addedInput schema / properties / profile
        Added value: +{
        +  "default": "read_only",
        +  "description": "Permission profile for the agent.",
        +  "enum": [
        +    "read_only",
        +    "workspace_write",
        +    "full_access"
        +  ],
        +  "type": "string"
        +}
      • changedInput schema / properties / prompt / description
        Previous value: -"Prompt text to send to the runner"New value: +"Task for the agent."
      • addedInput schema / properties / prompt / minLength
        Added value: +1
      • removedInput schema / properties / retry_base_delay
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "type": "number"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null,
        -  "description": "Base delay seconds for exponential backoff (None inherits session/config)."
        -}
      • removedInput schema / properties / retry_max_delay
        Removed value: -{
        -  "anyOf": [
        -    {
        -      "type": "number"
        -    },
        -    {
        -      "type": "null"
        -    }
        -  ],
        -  "default": null,
        -  "description": "Backoff ceiling in seconds (None inherits session preference or config)."
        -}
      • addedInput schema / properties / session_id
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "string"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "description": "Continue this conversation (from a previous result)."
        +}
      • removedInput schema / properties / timeout / anyOf
        Removed value: -[
        -  {
        -    "type": "integer"
        -  },
        -  {
        -    "type": "null"
        -  }
        -]
      • changedInput schema / properties / timeout / default
        Previous value: -nullNew value: +600
      • changedInput schema / properties / timeout / description
        Previous value: -"Subprocess timeout seconds (None inherits session preference or uses env default)."New value: +"Seconds before the turn is cancelled."
      • addedInput schema / properties / timeout / minimum
        Added value: +1
      • addedInput schema / properties / timeout / type
        Added value: +"integer"
      • changedInput schema / required
        Previous value: -[
        -  "prompt"
        -]New value: +[
        +  "backend",
        +  "prompt",
        +  "cwd"
        +]
      • addedOutput schema / description
        Added value: +"Final answer of one agent turn."
      • addedOutput schema / properties / backend
        Added value: +{
        +  "type": "string"
        +}
      • addedOutput schema / properties / output
        Added value: +{
        +  "type": "string"
        +}
      • removedOutput schema / properties / result
        Removed value: -{
        -  "type": "string"
        -}
      • addedOutput schema / properties / session_id
        Added value: +{
        +  "type": "string"
        +}
      • addedOutput schema / properties / usage
        Added value: +{
        +  "anyOf": [
        +    {
        +      "additionalProperties": true,
        +      "type": "object"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • changedOutput schema / required
        Previous value: -[
        -  "result"
        -]New value: +[
        +  "backend",
        +  "session_id",
        +  "output"
        +]
      • removedOutput schema / x-fastmcp-wrap-result
        Removed value: -true
    • Removedset_model_tiers
    • Removedset_preferences
  3. 16 tool updatesv1.1.0
    • Addedagent_backends
    • Addedagent_cancel
    • Addedagent_continue
    • Addedagent_diagnose
    • Addedagent_fork
    • Addedagent_list
    • Addedagent_respond
    • Addedagent_result
    • Addedagent_review
    • Addedagent_start
    • Addedagent_status
    • Changedbatch_prompt1 field changed
      • changedInput schema / properties / max_concurrency / description
        Previous 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."
    • Addedopencode_investigate
    • Addedopencode_session_review
    • Addedopencode_set_provider_auth
    • Addedopencode_update_config
  4. 5 tool updatesv1.0.0
    • Changedbatch_prompt9 fields changed
      • addedInput schema / properties / elicit
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / max_concurrency / description
        Added value: +"Max parallel runner invocations (default: 3)."
      • addedInput schema / properties / tasks / description
        Added value: +"List of AgentTask objects, each with cli, prompt, and optional fields."
      • addedInput schema / properties / tasks / items / properties / cli / anyOf
        Added value: +[
        +  {
        +    "minLength": 1,
        +    "type": "string"
        +  },
        +  {
        +    "type": "null"
        +  }
        +]
      • addedInput schema / properties / tasks / items / properties / cli / default
        Added value: +null
      • changedInput schema / properties / tasks / items / properties / cli / enum
        Previous value: -[
        -  "claude",
        -  "codex",
        -  "gemini",
        -  "opencode"
        -]New value: +[
        +  "claude",
        +  "codex",
        +  "opencode",
        +  "opencode_server"
        +]
      • removedInput schema / properties / tasks / items / properties / cli / minLength
        Removed value: -1
      • removedInput schema / properties / tasks / items / properties / cli / type
        Removed value: -"string"
      • changedInput schema / properties / tasks / items / required
        Previous value: -[
        -  "cli",
        -  "prompt"
        -]New value: +[
        +  "prompt"
        +]
    • Removedget_preferences
    • Changedprompt16 fields changed
      • addedInput schema / properties / cli / anyOf
        Added value: +[
        +  {
        +    "type": "string"
        +  },
        +  {
        +    "type": "null"
        +  }
        +]
      • addedInput schema / properties / cli / default
        Added value: +null
      • addedInput schema / properties / cli / description
        Added value: +"CLI runner name (e.g., \"codex\"). None triggers interactive selection."
      • changedInput schema / properties / cli / enum
        Previous value: -[
        -  "claude",
        -  "codex",
        -  "gemini",
        -  "opencode"
        -]New value: +[
        +  "claude",
        +  "codex",
        +  "opencode",
        +  "opencode_server"
        +]
      • removedInput schema / properties / cli / type
        Removed value: -"string"
      • addedInput schema / properties / context / description
        Added value: +"Optional context metadata"
      • addedInput schema / properties / elicit
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / execution_mode / description
        Added value: +"'default' (safe) or 'yolo'. None inherits session preference."
      • addedInput schema / properties / max_retries / description
        Added value: +"Max retry attempts for transient errors (None inherits session preference)."
      • addedInput schema / properties / model / description
        Added value: +"Model name. None triggers interactive selection or uses CLI default."
      • addedInput schema / properties / output_limit / description
        Added value: +"Max output bytes (None inherits session preference or uses env default)."
      • addedInput schema / properties / prompt / description
        Added value: +"Prompt text to send to the runner"
      • addedInput schema / properties / retry_base_delay / description
        Added value: +"Base delay seconds for exponential backoff (None inherits session/config)."
      • addedInput schema / properties / retry_max_delay / description
        Added value: +"Backoff ceiling in seconds (None inherits session preference or config)."
      • addedInput schema / properties / timeout / description
        Added value: +"Subprocess timeout seconds (None inherits session preference or uses env default)."
      • changedInput schema / required
        Previous value: -[
        -  "cli",
        -  "prompt"
        -]New value: +[
        +  "prompt"
        +]
    • Addedset_model_tiers
    • Changedset_preferences24 fields changed
      • addedInput schema / properties / clear_confirm_high_retries
        Added value: +{
        +  "default": false,
        +  "type": "boolean"
        +}
      • addedInput schema / properties / clear_confirm_large_batch
        Added value: +{
        +  "default": false,
        +  "type": "boolean"
        +}
      • addedInput schema / properties / clear_confirm_vague_prompt
        Added value: +{
        +  "default": false,
        +  "type": "boolean"
        +}
      • addedInput schema / properties / clear_confirm_yolo
        Added value: +{
        +  "default": false,
        +  "type": "boolean"
        +}
      • addedInput schema / properties / clear_elicit
        Added value: +{
        +  "default": false,
        +  "type": "boolean"
        +}
      • addedInput schema / properties / clear_execution_mode / description
        Added value: +"If True, resets execution_mode to None regardless of the\nexecution_mode argument."
      • addedInput schema / properties / clear_max_retries / description
        Added value: +"If True, resets max_retries to None regardless of the argument."
      • addedInput schema / properties / clear_model / description
        Added value: +"If True, resets model to None regardless of the model argument."
      • addedInput schema / properties / clear_output_limit / description
        Added value: +"If True, resets output_limit to None regardless of the argument."
      • addedInput schema / properties / clear_retry_base_delay / description
        Added value: +"If True, resets retry_base_delay to None."
      • addedInput schema / properties / clear_retry_max_delay / description
        Added value: +"If True, resets retry_max_delay to None."
      • addedInput schema / properties / clear_timeout / description
        Added value: +"If True, resets timeout to None regardless of the argument."
      • addedInput schema / properties / confirm_high_retries
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / confirm_large_batch
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / confirm_vague_prompt
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / confirm_yolo
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / elicit
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "boolean"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null
        +}
      • addedInput schema / properties / execution_mode / description
        Added value: +"Default execution mode ('default' or 'yolo').\nNone retains the current value (use clear_execution_mode=True to reset)."
      • addedInput schema / properties / max_retries / description
        Added value: +"Default max retry attempts for transient errors.\nNone retains the current value (use clear_max_retries=True to reset)."
      • addedInput schema / properties / model / description
        Added value: +"Default model name (e.g. 'gpt-5.2').\nNone retains the current value (use clear_model=True to reset)."
      • addedInput schema / properties / output_limit / description
        Added value: +"Default max output bytes per response.\nNone retains the current value (use clear_output_limit=True to reset)."
      • addedInput schema / properties / retry_base_delay / description
        Added value: +"Default base delay seconds for exponential backoff.\nNone retains the current value (use clear_retry_base_delay=True to reset)."
      • addedInput schema / properties / retry_max_delay / description
        Added value: +"Default max delay cap seconds for exponential backoff.\nNone retains the current value (use clear_retry_max_delay=True to reset)."
      • addedInput schema / properties / timeout / description
        Added value: +"Default subprocess timeout in seconds.\nNone retains the current value (use clear_timeout=True to reset)."
  5. 5 tool updatesv0.8.1
    • First observedbatch_prompt
    • First observedclear_preferences
    • First observedget_preferences
    • First observedprompt
    • First observedset_preferences

TDQS

B3/5.0

Scored across 1 tool

Disambiguation4/5

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.

Naming Consistency3/5

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.

Tool Count2/5

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.

Completeness2/5

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

ActivityActive
ResponsivenessSlow

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Turns 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
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that publishes CLI tools on your machine for discoverability by LLMs
    7 npm
    1
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Universal MCP server that wraps any CLI tool, enabling AI assistants to run commands via natural language.
    1
    MIT