A
licenseA
qualityD
maintenanceAn MCP server that lets host-side Claude Cowork dispatch work into Claude Code running inside your devcontainer over stdio.
16
MIT
Claude Code Subagent MCP
by ltxzs
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Claude Code Subagent MCPCheck status of /home/user/project and delegate implementation of new API endpoint."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Code Subagent MCP
English | 简体中文
项目简介
Claude Code Subagent MCP 是一个用户级 stdio MCP server，让 Codex Desktop 或 Codex CLI
可以调用 Claude Code CLI 作为实现者。Codex 负责协调任务、展示 Claude 的回复，并审核目标仓库的变更。
server 将经解析、目录验证且确认为 Git 仓库的 workspacePath 用作 Git 和 Claude Code 子进程的
cwd；这只是工作目录设置，不是操作系统级文件系统沙箱。
Related MCP server: Claude MCP
工作流程
先使用状态工具检查目标工作区。
通过显式的
workspacePath将实现任务委派给 Claude Code。审核 server 返回的 Git 状态和未暂存差异摘要，再自行检查
git diff、git diff --cached，并逐个 打开git status --short列出的未跟踪文件，确认完整变更后再决定是否接受结果。
环境要求
Node.js 18 或更高版本
Git
Claude Code CLI
Codex Desktop 或 Codex CLI
安装前请检查本地环境：
node --version
git --version
claude --version本项目没有运行时 npm 依赖，因此不需要执行 npm install。
安装
Windows PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex-tools" | Out-Null
git clone https://github.com/ltxzs/claude-subagent-mcp.git "$env:USERPROFILE\.codex-tools\claude-subagent-mcp"
Set-Location "$env:USERPROFILE\.codex-tools\claude-subagent-mcp"
node --check src/server.mjs
npm testmacOS / Linux
mkdir -p ~/.codex-tools
git clone https://github.com/ltxzs/claude-subagent-mcp.git ~/.codex-tools/claude-subagent-mcp
cd ~/.codex-tools/claude-subagent-mcp
node --check src/server.mjs
npm test注册到 Codex
将相应配置添加到全局 Codex 配置文件。Windows 的配置文件是
%USERPROFILE%\.codex\config.toml；macOS 和 Linux 的配置文件是 ~/.codex/config.toml。
可参考 examples/config.example.toml 中的完整配置模板。模板中的
REPLACE_WITH_ABSOLUTE_PATH_TO_SRC_SERVER_MJS 必须替换为当前电脑上的实际路径。
args 必须写入 src/server.mjs 的实际绝对路径。不要指望 TOML 中的 %USERPROFILE% 或 ~
被展开。
Windows
[mcp_servers.claude_subagent]
command = "node"
args = ["C:\\Users\\alice\\.codex-tools\\claude-subagent-mcp\\src\\server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]
[mcp_servers.claude_subagent.env]
NODE_ENV = "production"macOS
[mcp_servers.claude_subagent]
command = "node"
args = ["/Users/alice/.codex-tools/claude-subagent-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]
[mcp_servers.claude_subagent.env]
NODE_ENV = "production"Linux
[mcp_servers.claude_subagent]
command = "node"
args = ["/home/alice/.codex-tools/claude-subagent-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]
[mcp_servers.claude_subagent.env]
NODE_ENV = "production"验证 MCP server
保存配置后重启 Codex，再确认下列两个工具可见：
claude_subagent.get_claude_subagent_status
claude_subagent.delegate_to_claude也可独立于 Codex，在项目目录向 server 进程发送 initialize JSON-RPC 请求，以验证进程本身。
这不能替代重启 Codex 和检查工具注册。响应必须包含 claude-code-subagent。
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}\n' | node src/server.mjs'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}' | node src/server.mjs使用方法
检查目标仓库
先调用 claude_subagent.get_claude_subagent_status：
{
"workspacePath": "C:\\path\\to\\repo"
}委派实现任务
再调用 claude_subagent.delegate_to_claude，传入具体实现要求：
{
"task": "实现具体需求并运行相关测试",
"workspacePath": "C:\\path\\to\\repo",
"allowDirty": false,
"timeoutMs": 1200000
}审核返回结果
Claude 返回后，server 在结构化结果的 Git 部分包含审核相关字段 statusShort、diffStat 和
diffNameOnly，分别来自 git status --short、git diff --stat 和 git diff --name-only；结果还包含
changedFiles 和 errors（可能为空），但不提供完整 diff。后两个
命令与 git diff 一样，默认只覆盖未暂存变更；暂存变更需另行检查 git diff --cached。Codex 或用户
还必须逐个打开 git status --short 列出的未跟踪文件检查其内容，确认未暂存、暂存和未跟踪变更后再决定
是否接受实现结果。
工具参数
delegate_to_claude 接受以下参数：
参数 | 要求 |
| 必填，非空字符串。 |
| 必填，非空目录路径，且必须是 Git 仓库。 |
| 可选布尔值，默认 |
| 可选的非空 Claude Code 会话 ID。 |
| 可选整数，单位为毫秒；默认 |
get_claude_subagent_status 要求传入指向 Git 仓库的非空 workspacePath。
为什么必须传 workspacePath
这是全局 MCP server，不属于任何应用仓库。显式指定 workspacePath 后，server 会解析并验证该目录，
确认它是 Git 仓库，再将其用作 Git 和 Claude Code 子进程的 cwd，避免默认在 MCP server 目录或其他
误选目录运行。这不会限制子进程对其他文件系统路径的访问，也不构成操作系统级沙箱，因此只应传入可信仓库。
工作树有未提交改动
默认 allowDirty=false。当 git status --short 非空时，委派会停止，避免 Claude Code 在未经审核的
改动上叠加修改。只有在审核过现有改动并明确接受其作为上下文后，才将 allowDirty 设为 true。
继续 Claude Code 会话
将此前 Claude Code 结果中的非空 session_id 作为 resumeSessionId 传入，即可继续该会话。server 会以
claude --resume <session_id> 调用 Claude Code。
安全说明
server 从不使用
--dangerously-skip-permissions。Claude Code 默认允许的工具仅限文件读写，以及 server 列出的常用 Git、测试和构建命令。
workspacePath只用作子进程的cwd，不是文件系统访问边界。只传入可信仓库，并保留 Claude Code 的 权限审批和人工审核。server 自身不执行 commit 或 push；附加系统提示会要求 Claude 不 commit、不 push，但默认允许的
Bash(git:*)仍可执行 Git 命令。这是行为约束，不是技术 denylist 或强制拦截。接受任何实现前，必须保留审批并检查
git status --short、git diff、git diff --cached，以及每个 未跟踪文件的内容。
常见错误排查
Git 不可用
安装 Git，并在 Codex 使用的同一终端环境中确认 git --version 成功。
Claude Code CLI 不可用
安装 Claude Code CLI，并在 Codex 使用的同一终端环境中确认 claude --version 成功。
workspacePath 不是 Git 仓库
请传入目标项目根目录，并确保在那里执行 git rev-parse --is-inside-work-tree 成功。必要时使用
git init 初始化项目。
工作树有未提交改动
检查 git status --short、适用的 git diff 和 git diff --cached，并逐个打开未跟踪文件。清理或
提交无关改动；只有在这些改动本就应作为上下文时，才明确设置 allowDirty 为 true。
Claude Code 超时
默认超时为 20 分钟。对于确定耗时较长的任务可增大 timeoutMs，或将任务拆分为更小的请求。
Codex 中看不到工具
确认全局配置使用绝对 args 路径，重启 Codex，并确认 server 名称为 claude_subagent。
开发验证
npm run check
npm test许可证
本项目采用 MIT License 授权。
Available Tools
2 toolsdelegate_to_claudeDelegate Implementation To Claude CodeA
Run Claude Code CLI in the explicit workspacePath so Claude implements changes while Codex receives Claude output, git status, diff stat, changed files, stderr, and raw output tail for review.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Implementation task to pass to Claude Code. | |
| timeoutMs | No | Claude Code execution timeout in milliseconds. Defaults to 1200000. | |
| allowDirty | No | When false, refuse to run Claude if git status --short is non-empty. | |
| workspacePath | Yes | Absolute or resolvable path to the target Git repository. Required; the MCP server directory is never used as a default workspace. | |
| resumeSessionId | No | Optional Claude Code session id passed with --resume. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| git | Yes | |
| error | No | |
| claude | Yes | |
| gitAvailable | No | |
| workspacePath | Yes | |
| claudeAvailable | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as non-read-only and non-idempotent. The description adds value by disclosing that this executes an external CLI, mutates the workspace ('Claude implements changes'), and returns a bundle of review signals. It does not cover failure modes or side effects such as a dirty working tree, but the allowDirty parameter in the schema covers that boundary.
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, front-loaded sentence that packs the core behavior and output artifacts with no filler. The enumeration of returned items is long but each item is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not detail return types, and it already lists the key delivered artifacts. It omits explicit sibling routing and some edge-case behavior, but annotations and a fully covered schema fill most gaps, making the description adequate for a tool of this complexity.
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 parameters are already documented in the input schema. The description reinforces workspacePath ('explicit workspacePath') and the task concept, but does not add new meaning about parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — run Claude Code CLI in an explicit workspacePath — and names the resource (the target Git repository). It also explains the result: Claude implements changes while Codex receives output, git status, diff stat, changed files, stderr, and raw output tail for review, which clearly distinguishes it from the sibling status tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes the intended context: delegate implementation work to Claude Code and get review artifacts back to Codex. It does not explicitly name get_claude_subagent_status or state when not to use this tool, but the context is clear enough for an agent to route appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_claude_subagent_statusGet Claude Subagent StatusARead-onlyIdempotent
Check workspace git status, diff stat, changed files, and whether git and Claude Code CLI are available before delegating work.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspacePath | Yes | Absolute or resolvable path to the target Git repository. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| git | Yes | |
| error | No | |
| claude | Yes | |
| gitAvailable | No | |
| workspacePath | Yes | |
| claudeAvailable | No |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real behavioral context beyond them — it enumerates exactly what the tool inspects (git status, diff stat, changed files, CLI availability) — which clarifies this is an environment-readiness check, not a literal 'subagent status' report.
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?
A single sentence that front-loads the primary action and then lists the exact checks performed. Every phrase earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only tool with one parameter, rich annotations, and an existing output schema, the description covers the essentials: what it checks, why it exists (pre-delegation readiness), and its safety profile. Nothing an agent needs to select and invoke it correctly is missing.
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% (workspacePath is documented as 'Absolute or resolvable path to the target Git repository'), so the baseline of 3 applies. The description only loosely echoes the parameter via the word 'workspace' and adds no syntax, format, or usage nuance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Check workspace git status, diff stat, changed files') and adds a precise scope: availability of git and Claude Code CLI. The closing phrase 'before delegating work' positions it distinctly from its sibling delegate_to_claude, so an agent can tell which one to select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool applies ('before delegating work'), which effectively signals a preflight check on the workspace before using the sibling. It does not, however, explicitly name delegate_to_claude as the alternative or state a when-not-to-use condition, so it stops one step short of fully explicit routing.
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.
2 tool updates
v1.0.0- First observed
delegate_to_claude - First observed
get_claude_subagent_status
TDQS
A4.1/5.0
Scored across 2 tools
Disambiguation5/5
The two tools have completely distinct purposes: one is a status/inspection tool, the other is an action/delegation tool. There is no overlap or ambiguity between them.
Naming Consistency5/5
Both tools follow a consistent verb_noun snake_case pattern (get_ and delegate_to_). The naming is clear and predictable.
Tool Count3/5
With only two tools, the server feels very minimal. While the narrow scope is somewhat defensible, a typical agent would likely expect additional management tools, making this borderline.
Completeness2/5
The server provides status checking and delegation, but lacks operations for managing subagents (e.g., listing active sessions, canceling tasks, retrieving historical results). This creates a significant gap for any non-trivial workflow.
Maintenance
ActivityStale
ResponsivenessNo issues
Related MCP Connectors
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA cross-platform desktop MCP server that allows Codex and other MCP clients to execute tasks via the Claude Agent SDK, providing tools for code generation, file editing, and task management with session continuation.14MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that bridges Claude Desktop with Claude Code, allowing users to delegate tasks to Claude Code directly from Claude Desktop conversations, supporting both synchronous and background execution with session reuse.2 npmMIT
- AlicenseAqualityBmaintenanceAn MCP server that lets Claude Code delegate durable background tasks, reasoning profiles, thread resumption, and native image generation to your local Codex CLI.101MIT