Sub Agents MCP

🚀 Sub - Agents MCP Server

Claude Codeスタイルのサブエージェントを、MCP互換のあらゆるツールに導入できます。このMCPサーバーを使うと、マークダウンファイルでタスク固有のAIエージェント（「テスト作成者」や「コードレビュアー」など）を定義し、Cursor CLI、Claude Code CLI、またはGemini CLIバックエンドを介して実行することができます。

🚀 クイックスタート

1. 最初のエージェントを作成する

エージェント用のフォルダを作成し、code - reviewer.md を追加します。

# Code Reviewer

You are a specialized AI assistant that reviews code.
Focus on:
- Finding bugs and potential issues
- Suggesting improvements
- Checking code quality

2. 実行エンジンをインストールする

使用するツールに基づいて1つ選択します。

Cursorユーザー向け：

# Install Cursor CLI (includes cursor - agent)
curl https://cursor.com/install - fsS | bash

# Authenticate (required before first use)
cursor - agent login

Claude Codeユーザー向け：

# Option 1: Native install (recommended)
curl - fsSL https://claude.ai/install.sh | bash

# Option 2: NPM (requires Node.js 18+)
npm install -g @anthropic-ai/claude-code

注：Claude Codeは claude CLIコマンドをインストールします。

Gemini CLIユーザー向け：

# Install Gemini CLI
npm install -g @google/gemini-cli

# Authenticate via browser (required before first use)
gemini

注：Gemini CLIはOAuth認証を使用します。一度 gemini を実行して、ブラウザ経由で認証してください。

3. MCPを設定する

MCP設定ファイルに以下を追加します。

Cursor： ~/.cursor/mcp.json Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "sub - agents": {
      "command": "npx",
      "args": ["-y", "sub - agents - mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/your/agents - folder",
        "AGENT_TYPE": "cursor"  // or "claude" or "gemini"
      }
    }
  }
}

重要： 絶対パスのみを使用してください。

• ✅ /Users/john/Documents/my - agents (Mac/Linux)
• ✅ C:\\Users\\john\\Documents\\my - agents (Windows)
• ❌ ./agents または ~/agents は機能しません

IDEを再起動すると、使用可能になります。

4. シェルコマンドを実行する際の「Permission Denied」エラーを修正する

サブエージェントがシェルコマンドを実行する際に、権限エラーで失敗することがあります。これは、サブエージェントが対話型の権限プロンプトに応答できないためです。

推奨アプローチ：

1. サブエージェントに処理させたいタスクでCLIツールを直接実行します。

   # For Cursor users
   cursor - agent
   
   # For Claude Code users
   claude
   
   # For Gemini CLI users
   gemini
   

2. コマンドを許可するように求められた場合（例：「Add Shell(cd), Shell(make) to allowlist?」）、承認します。

3. これにより設定ファイルが自動的に更新され、MCPサブエージェントを介して呼び出されたときにこれらのコマンドが機能するようになります。

手動設定（代替案）：

権限を手動で設定する場合は、以下を編集します。

• Cursor： <project>/.cursor/cli.json または ~/.cursor/cli - config.json
• Claude Code： .claude/settings.json または .claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Shell(cd)",
      "Shell(make)",
      "Shell(git)"
    ]
  }
}

注：エージェントはしばしば cd /path && make build のようなワンライナーとしてコマンドを実行するため、コマンドのすべての部分を許可する必要があります。

✨ 主な機能

Claude Codeは強力なサブエージェントワークフローを提供しますが、それは自身の環境に限定されています。このMCPサーバーにより、そのワークフローがポータブルになり、MCP互換のあらゆるツール（Cursor、Claude Desktop、Windsurfなど）が同じエージェントを使用できるようになります。

具体的な利点：

• 再利用可能なエージェントを一度定義し、複数のツールで使用できます。
• IDEの選択に関係なく、チーム内でエージェント定義を共有できます。
• 任意のMCPクライアントからCursor CLI、Claude Code CLI、またはGemini CLIの機能を利用できます。

→ 詳細を読む

💻 使用例

AIにエージェントを使用するように指示するだけです。

"Use the code - reviewer agent to check my UserService class"

"Use the test - writer agent to create unit tests for the auth module"

"Use the doc - writer agent to add JSDoc comments to all public methods"

AIは自動的に専用のエージェントを呼び出し、結果を返します。

📚 ドキュメント

エージェントの例

エージェントフォルダ内の各 .md または .txt ファイルがエージェントになります。ファイル名がエージェント名になります（例： test - writer.md → "test - writer"）。

テスト作成者

test - writer.md

# Test Writer
You specialize in writing comprehensive unit tests.
- Cover edge cases
- Follow project testing patterns
- Ensure good coverage

SQLエキスパート

sql - expert.md

# SQL Expert
You're a database specialist who helps with queries.
- Optimize for performance
- Suggest proper indexes
- Help with complex JOINs

セキュリティチェッカー

security - checker.md

# Security Checker
You focus on finding security vulnerabilities.
- Check for SQL injection risks
- Identify authentication issues
- Find potential data leaks

設定リファレンス

必須環境変数

AGENTS_DIR エージェントフォルダへのパス。絶対パスである必要があります。

AGENT_TYPE 使用する実行エンジン：

• "cursor" - cursor - agent CLIを使用します。
• "claude" - claude CLIを使用します。
• "gemini" - gemini CLIを使用します。

オプション設定

EXECUTION_TIMEOUT_MS エージェントがタイムアウトするまでの実行時間（デフォルト：5分、最大：10分）

タイムアウトを設定した例：

{
  "mcpServers": {
    "sub - agents": {
      "command": "npx",
      "args": ["-y", "sub - agents - mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/agents",
        "AGENT_TYPE": "cursor",
        "EXECUTION_TIMEOUT_MS": "600000"
      }
    }
  }
}

セキュリティに関する注意

エージェントはプロジェクトディレクトリにアクセスできます。信頼できるソースからのエージェント定義のみを使用してください。

セッション管理

セッション管理により、サブエージェントが以前の実行を記憶できるようになります。これは、エージェントが以前の作業を基に構築したり、複数回の呼び出しでコンテキストを維持したい場合に役立ちます。

セッションが重要な理由

デフォルトでは、各サブエージェントの実行はコンテキストなしで開始されます。セッションを有効にすると：

• エージェントは以前の作業を参照できます。
• デバッグ用の実行履歴が得られます。
• 関連するタスクがコンテキストを共有します。

セッションの有効化

MCP設定に以下の環境変数を追加します。

{
  "mcpServers": {
    "sub - agents": {
      "command": "npx",
      "args": ["-y", "sub - agents - mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/agents",
        "AGENT_TYPE": "cursor",
        "SESSION_ENABLED": "true",
        "SESSION_DIR": "/absolute/path/to/session - storage",
        "SESSION_RETENTION_DAYS": "1"
      }
    }
  }
}

設定オプション：

• SESSION_ENABLED - セッション管理を有効にするには "true" に設定します（デフォルト： false）
• SESSION_DIR - セッションファイルを保存する場所（デフォルト：現在の作業ディレクトリの .mcp - sessions）
• SESSION_RETENTION_DAYS - セッションファイルを最終更新日から何日間保持するか（デフォルト：1）

セキュリティ上の考慮事項： セッションファイルには実行履歴が含まれ、機密情報が含まれる場合があります。 SESSION_DIR には絶対パスを使用してください。

セッションを使用するタイミング

セッションは以下の場合に適しています。

• 反復開発：「以前の調査結果に基づいて、今度は問題を修正してください」
• 多段階ワークフロー：複雑なタスクを小さなサブエージェント呼び出しに分割する
• デバッグ：正確に実行された内容と返された結果を確認する

ただし、セッションには追加のストレージと処理オーバーヘッドが必要です。

セッションの継続性のしくみ

セッションが有効になっている場合、MCP応答には session_id フィールドが含まれます。同じセッションを継続するには、次のリクエストでこのIDを返します。

重要： AIアシスタントは、後続のリクエストで明示的に session_id を含める必要があります。一部のアシスタントは自動的にこれを行う場合がありますが、保証されていません。信頼性の高いセッションの継続性を確保するには、プロンプトまたはプロジェクトルールに明示的な指示を追加してください。

プロンプトの指示の例：

When using sub - agents with sessions enabled, always include the session_id
from the previous response in your next request to maintain context.

プロジェクトルールの例（例： AGENTS.md）：

# Sub - Agent Session Guidelines

When calling the same sub - agent multiple times:
1. Extract the session_id from the MCP response
2. Pass it as a parameter in subsequent calls
3. This preserves context between executions

トラブルシューティング

タイムアウトエラーまたは認証失敗

Cursor CLIを使用している場合： cursor - agent login を実行して認証します。セッションは期限切れになる可能性があるため、認証エラーが表示された場合は、このコマンドを再度実行してください。

インストールを確認します。

which cursor - agent

Claude Codeを使用している場合： CLIが正しくインストールされ、アクセス可能であることを確認してください。

エージェントが見つからない

以下を確認してください。

• AGENTS_DIR が正しいディレクトリを指していること（絶対パスを使用）
• エージェントファイルが .md または .txt 拡張子を持っていること
• ファイル名がハイフンまたはアンダースコアを使用していること（スペースは使用しない）

その他の実行エラー

1. AGENT_TYPE が正しく設定されていることを確認します（cursor、claude、または gemini）
2. 選択したCLIツールがインストールされ、アクセス可能であることを確認します。
3. MCP設定ですべての環境変数が設定されていることを再度確認します。

設計理念

独立したコンテキストが重要な理由

すべてのサブエージェントは新しいコンテキストで開始されます。これにより、各呼び出しにはいくらかの起動オーバーヘッドがありますが、すべてのタスクが独立して実行され、以前の実行からの残りの状態がないことが保証されます。

コンテキストの分離

• 各エージェントは、そのタスクに関連する情報のみを受け取ります。
• 実行間でコンテキストが漏れることはありません。
• メインエージェントは集中して軽量になります。

精度と信頼性

• サブエージェントは、干渉なしに単一の目標に特化できます。
• 関係のないコンテキストによる混乱のリスクが低くなります。
• 複雑な多段階ワークフローでより一貫した結果が得られます。

スケーラビリティ

• 大きなタスクを安全に小さなサブタスクに分割できます。
• 各サブエージェントは独自のトークン制限内で動作します。
• メインエージェントはグローバルなコンテキスト制限に達することなく調整できます。

起動オーバーヘッドは意図的なトレードオフです。システムは、生の実行速度よりも明確さと精度を重視しています。

動作原理

このMCPサーバーは、AIツールとサポートされている実行エンジン（Cursor CLI、Claude Code CLI、またはGemini CLI）の間の橋渡し役として機能します。

フロー：

1. クライアント（Cursor、Claude Desktopなど）でMCPサーバーを設定します。
2. クライアントは起動時に自動的に sub - agents - mcp をバックグラウンドプロセスとして起動します。
3. メインAIアシスタントがサブエージェントを必要とするとき、MCPツール呼び出しを行います。
4. MCPサーバーはエージェント定義（マークダウンファイル）を読み取り、選択したCLI（cursor - agent、claude、または gemini）を呼び出します。
5. 実行エンジンはエージェントを実行し、結果をMCPサーバーを介してストリーミングで返します。
6. メインアシスタントは結果を受け取り、作業を続行します。

このアーキテクチャにより、MCP互換のあらゆるツールが、ネイティブサポートがなくても、専用のサブエージェントの恩恵を受けることができます。

📄 ライセンス

MIT

AI-to-AI collaboration through Model Context Protocol