MCP Agents

MCP server that enhances the Task tool with Claude Agent SDK, providing session resumption and independent agent execution.

IMPORTANT: Replaces Task Tool

When this MCP is active, it REPLACES the native Task tool. All agents defined in .claude/agents/ must be executed through run_agent, not through Task.

Why Use This Instead of Task?

Feature	Task Tool	run_agent (MCP)
Session resumption	No	Yes
Follow-up prompts	No	Yes
Independent sessions	No	Yes
Auto-compaction	No	Yes (SDK)
Summary-only returns	No	Yes

Agent Location

Agents are loaded from the same location as Claude Code's native agents:

~/.claude/agents/           ← User-level (global)
{cwd}/.claude/agents/       ← Project-level (overrides user-level)

No duplication needed. Your existing Claude Code agents work with this MCP.

Installation

cd mcp-agents
npm install
npm run build

Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "mcp-agents": {
      "command": "node",
      "args": ["/path/to/mcp-agents/dist/index.js"]
    }
  }
}

No AGENTS_DIR needed - agents are loaded from .claude/agents/ automatically.

MCP Tools

run_agent

Replaces the Task tool. Run an autonomous subagent.

// New task
run_agent(agent: "researcher", task: "Research rate limiting best practices")

// Follow-up prompt (resume session)
run_agent(agent: "researcher", task: "Focus on token bucket algorithm", resume: "session-id")

Parameters:

Name	Required	Description
agent	Yes	Agent name from .claude/agents/
task	Yes	Task prompt (or follow-up when resuming)
resume	No	Session ID for follow-up prompts
fork	No	Create independent branch

Returns:

{
  success: boolean;
  session_id: string;
  summary: string;
  artifacts?: string[];  // Files created/modified
  error?: string;        // Present on failure
}

run_agents_batch

TRUE PARALLEL execution. Runs multiple agents concurrently using Promise.all().

run_agents_batch({
  tasks: [
    { id: "research", agent: "researcher", task: "Find API docs" },
    { id: "analyze", agent: "analyzer", task: "Check patterns" },
    { id: "test", agent: "tester", task: "Run tests" }
  ]
})

Why use this?

• Multiple run_agent calls execute sequentially (Claude Code limitation)
• run_agents_batch executes ALL tasks in parallel
• Total time = longest task, not sum of all tasks

Returns:

{
  all_success: boolean;
  succeeded: number;
  failed: number;
  total_duration_ms: number;
  results: BatchTaskResult[];  // Each with id, success, session_id, summary
}

get_agent_sessions

List resumable sessions for follow-up prompts.

cancel_agent

Cancel a running agent session.

Agent Format

Same format as Claude Code agents:

---
name: my-agent
description: |
  Description of what this agent does.

  Examples:
  - <example>
    Context: When to use
    user: "Example request"
    assistant: "Example response"
    </example>
---

# System Prompt

Your agent instructions here...

Key Features

Session Resumption

1. run_agent(agent="coder", task="Implement auth module")
   → session_id: "abc123"

2. run_agent(agent="coder", task="Add password reset", resume="abc123")
   → Agent continues with full context

Multiple Agent Calls

Multiple run_agent calls in one message run in independent sessions. Each agent's failure doesn't affect others.

Note: Execution is currently sequential due to Claude Code's MCP handling. True parallel execution depends on client-side support (MCP spec 2025-11 added parallel tool calls).

Auto-Compaction

The Claude Agent SDK handles context management for long-running tasks.

Environment Inheritance

Agents inherit environment from Claude Code session (uses subscription, not API key).

How It Works

1. MCP loads agents from .claude/agents/ on each session start
2. Claude already has agent descriptions in context (from same folder)
3. Tool description says "use run_agent, not Task"
4. When run_agent is called, MCP uses Claude Agent SDK's query() function
5. Agent runs autonomously with all Claude Code tools
6. Only summary is returned (not full conversation)
7. Session can be resumed with follow-up prompts

License

MIT