claude-subagent-mcp

An MCP server that runs a scoped Claude Code session on your Claude subscription. Cursor, or any other MCP client, can hand it a bounded task. The work is billed to that subscription, not to Cursor model credits.

Why this exists

Cursor's model picker and Claude Code are separate bills. Choosing Opus, Sonnet, or another Claude model inside Cursor spends Cursor's third-party model allowance (or an Anthropic API key). A Claude Pro, Max, Team, or Enterprise seat cannot be attached to that picker. Anthropic ties that subscription to Claude's own apps, including the Claude Code CLI and the Claude Code extension.

That split shows up when Cursor credits for other models run out and Claude Code still has room. The useful shape is to keep the Cursor agent on an included Cursor model, and send one bounded slice to Claude Code: read a file and list the failure paths, review a diff, or edit a single directory. This server is that handoff. It starts the official claude binary, so the subscription login stays inside Claude Code.

It is not a way to put a Claude subscription behind Cursor's own model picker.

Related MCP server: pokeclaw

What a call can do

run_claude_subagent starts one non-interactive Claude Code session.

The child does not see the parent chat. Put the task, the file paths, and the limits in prompt. Pass cwd as the absolute workspace root. edit and shell require cwd, and that directory cannot be / or your home directory. paths for those modes must be directories you name. In read mode, a file path allows that file's directory, because the file tools are scoped to directories.

A headless run cannot show a permission dialog. Read mode denies anything that would have prompted, except web search and fetch, which are pre-approved. Edit mode auto-approves file edits inside cwd and the extra directories in paths. Shell mode also runs Bash, so one approved call can execute commands, including commands that read files outside the workspace or reach the network. Every mode can search the web and fetch a page. A fetch can include text from the workspace in the request. MCP tools are not offered in any mode. The session skips personal and project Claude Code customizations (hooks, skills, MCP servers, and saved allow rules). The Claude login is still used.

opus is sent as Claude Opus 5.5. The bare opus alias in Claude Code can land on an older Opus. sonnet, haiku, and fable are pinned the same way:

Full ids (claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, claude-fable-5-1) are accepted too. Your plan has to include the model. If it does not, Claude Code returns an error and this server passes that error back.

Each call returns the result text, a session_id, the model that ran, and an estimated cost. Pass that session_id as resume to continue the same session. max_budget_usd stops the run at an estimated spend from 0.25 to 8 (default 1.5 for read, 4 for edit and shell). timeout_sec is the wall clock limit from 30 to 300 (default 180).

While the session runs, the server sends a progress update every 15 seconds. Clients such as Cursor reset their idle timer on that update, so a quiet review can finish instead of being dropped at 2 minutes. The prompt is passed after --, so a task that starts with dashes is text, not a Claude Code flag. If the caller cancels, the Claude process and anything it started in that process group are stopped. If a leftover process still holds the output pipe, the call ends anyway.

The parent approves this one MCP call. After the process starts, Cursor does not see each file read or edit. Those follow the fence above.

Setup

You need:

• Node.js 20 or newer

• Claude Code 2.1.259 or newer on your PATH (claude --version)

• A Claude subscription that includes Claude Code, already logged in

Install Claude Code, then log in once in a terminal and confirm the subscription login:

claude
claude auth status

authMethod should be claude.ai. If ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN is set in the environment, Claude Code bills the Anthropic API instead of the subscription. This server removes those two variables for the child process. Other API-key settings are left alone.

On macOS, Homebrew installs a current Claude Code binary:

brew install --cask claude-code@latest

Other systems: follow the Claude Code install instructions at code.claude.com.

Clone this repo and install its dependencies:

git clone https://github.com/claude-abounegm/claude-subagent-mcp.git
cd claude-subagent-mcp
npm install

npm test runs the unit tests. They do not call Claude.

Cursor

Add this to ~/.cursor/mcp.json. Use the absolute path of server.mjs from the clone. If Cursor cannot find node (common with nvm when Cursor is opened from the dock), use the absolute path of node as command too.

{
  "mcpServers": {
    "claude-subagent": {
      "command": "node",
      "args": ["/absolute/path/to/claude-subagent-mcp/server.mjs"]
    }
  }
}

Reload MCP servers. The tool name is run_claude_subagent.

Optional environment variables, set on that MCP entry:

Any other MCP client

The server speaks MCP over stdio. Point the client at:

node /absolute/path/to/claude-subagent-mcp/server.mjs

Example

A read-only handoff from the parent agent:

{
  "prompt": "Read src/api.ts and list the failure paths. Do not edit files.",
  "cwd": "/absolute/path/to/the/workspace",
  "mode": "read",
  "model": "opus",
  "max_budget_usd": 1.5
}

Use mode: "edit" when that slice is supposed to change files without running commands. Use mode: "shell" when it needs Bash. The parent approves that choice once, and the commands then run without another prompt.

License

MIT