MCP Agent Server

MCP エージェントサーバー

AI クライアントとインテリジェントなエージェントをシームレスに接続し、複数の AI エコシステム間で強力なクロスプラットフォーム通信を実現する、Model Context Protocol（MCP）ハブです。

概要

MCP Agent Server は、MCP 対応クライアント（Claude Desktop、VS Code、Cursor など）と特化型 AI エージェントの橋渡しをします。以下が可能になります。

• 異なる機能を持つ複数の特化型エージェントを作成、設定する
• これらのエージェントを MCP クライアントに接続する
• エージェントを組み合わせて、複雑なワークフローに対応するマスターエージェントを構成する
• MCP サーバーの高度な機能を備えた AI アプリケーションを構築する

このプロジェクトでは、mcp-ai-agent フレームワークを活用して、エージェントの作成と管理を簡素化しています。

特徴

• 複数エージェントのサポート：さまざまな特化型エージェントを作成、管理できます
• エージェントの構成：特化型エージェントを組み合わせてマスターエージェントを構成できます
• カスタムツールの統合：独自のツールを作成するか、既存の MCP サーバーを使用できます
• 事前設定済みサーバー：Sequential Thinking、Brave Search、Memory などの人気の MCP サーバーを簡単に利用できます
• AI SDK の統合：Vercel AI SDK v5 を通じて、OpenAI、Anthropic、Google（Generative AI と Vertex）、Amazon Bedrock、Azure、Cohere、Mistral、Fireworks、Groq、Perplexity、Together AI、xAI、DeepSeek、Cerebras、DeepInfra、Replicate を含む 17 以上の LLM プロバイダーをサポートします

前提条件

• Node.js（v16 以降）がインストールされていること
• 使用する AI モデルプロバイダーの API キー（OpenAI、Anthropic、Google など）
• 使用する MCP サーバー固有の API キー

インストール

オプション 1：npx を使用する（推奨）

インストールせずに、npx を使って MCP Agent Server を直接実行できます。

# Start the server with default configuration
npx mcp-agent-server

# Start with custom configuration
npx mcp-agent-server --config my-config.json

# Test an agent
npx mcp-agent-server test-agent --name "Sequential Thinker" --prompt "What is 2+2?"

オプション 2：グローバルインストール

どこからでも mcp-agent-server コマンドを使えるように、グローバルにインストールします。

npm install -g mcp-agent-server

# Then use it
mcp-agent-server --config my-config.json

オプション 3：ローカル開発

1. リポジトリをクローンします。

   git clone <repository-url>
   cd mcp-agent-server
   

2. 依存関係をインストールします。

   npm install
   

3. プロジェクトをビルドします。

   npm run build
   

設定

エージェントの設定

MCP Agent Server では、管理とデプロイを簡単にするため、JSON ベースの設定を使用するようになりました。プロジェクトのルートに my-agents-config.json という名前の独自のエージェント設定ファイルを作成できます。このファイルが存在する場合、サーバーは自動的に検出して使用します。

独自の設定を作成する手順は次のとおりです。

1. プロジェクトのルートに my-agents-config.json という新しいファイルを作成します
2. JSON 形式で、ツール、モデル、設定を含むエージェントを定義します
3. サーバーが設定を自動的に読み込み、使用します

JSON 設定スキーマ

独自のエージェント設定の例を以下に示します。

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Code Context Agent",
      "description": "Use this agent to analyze and understand code in your projects",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        {
          "prebuilt": "sequentialThinking"
        },
        {
          "mcpServers": {
            "codeContext": {
              "command": "node",
              "args": ["/path/to/code-context-mcp/dist/index.js"]
            }
          }
        }
      ]
    },
    {
      "name": "Web Search Agent",
      "description": "Use this agent to search the web",
      "systemPrompt": "Prefer to use brave search to search the web for information.",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        {
          "prebuilt": "sequentialThinking"
        },
        {
          "prebuilt": "braveSearch"
        }
      ]
    },
    {
      "name": "Master Agent",
      "description": "An agent that can manage other agents",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "agentRef": "Code Context Agent"
        },
        {
          "agentRef": "Web Search Agent"
        }
      ]
    }
  ]
}

設定オプション

モデル設定

• provider：使用する AI プロバイダーです。次のプロバイダーに対応しています。
  • "openai" - OpenAI モデル（GPT-4、GPT-4o など）
  • "anthropic" - Anthropic Claude モデル
  • "google" - Google Generative AI（Gemini モデル）
  • "vertex" - Google Vertex AI
  • "bedrock" - Amazon Bedrock
  • "azure" - Azure OpenAI Service
  • "cohere" - Cohere モデル
  • "mistral" - Mistral AI モデル
  • "fireworks" - Fireworks AI
  • "groq" - Groq（超高速の推論）
  • "perplexity" - Perplexity AI
  • "togetherai" - Together AI
  • "xai" - xAI（Grok モデル）
  • "deepseek" - DeepSeek モデル
  • "cerebras" - Cerebras 推論
  • "deepinfra" - DeepInfra
  • "replicate" - Replicate（オープンソースモデル）
• model：具体的なモデル名です（例："gpt-4o-mini"、"claude-3-5-haiku-20241022"、"gemini-2.0-flash-exp"）
• apiKey：（任意）プロバイダーの API キーです。環境変数を使って設定することもできます

ツール設定の種類

1. ビルド済みサーバー（推奨）:

   {
     "prebuilt": "sequentialThinking"
   }
   

   利用可能なビルド済みサーバー: sequentialThinking、memory、braveSearch、firecrawlMcp、fetch、awsKbRetrieval、everart、fileSystem、sqlite

2. カスタム MCP サーバー:

   {
     "mcpServers": {
       "serverName": {
         "command": "node",
         "args": ["/path/to/server.js"],
         "env": {
           "API_KEY": "your-api-key"
         }
       }
     }
   }
   

3. エージェント参照（マスターエージェント向け）:

   {
     "agentRef": "Other Agent Name"
   }
   

4. インポートしたエージェント（外部エージェントファイルを使用する場合）:

   {
     "type": "import",
     "importPath": "/path/to/your/agent-file.js",
     "exportName": "createResearchAgent",
     "factoryArgs": {
       "modelProvider": "anthropic",
       "modelName": "claude-3-5-haiku-20241022",
       "includeMemory": true
     }
   }
   

   mcp-ai-agent ライブラリで作成した TypeScript/JavaScript ファイルからエージェントをインポートできます。インポートするファイルでは、次のものをエクスポートできます。

   • 事前設定済みのエージェントインスタンス
   • エージェントを作成するファクトリー関数（オプションの引数付き）
   • 複雑な初期化に対応する非同期ファクトリー関数

エージェントの選択的な公開

各エージェントの expose ブール値フィールドを使用して、MCP クライアントに公開するエージェントを制御できます。これは、他のエージェントが内部でのみ使用するヘルパーエージェントを用意したい場合に便利です。

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Web Search Helper",
      "description": "Internal web search capabilities",
      "model": { "provider": "openai", "model": "gpt-4o-mini" },
      "toolsConfigs": [{ "prebuilt": "braveSearch" }],
      "expose": false
    },
    {
      "name": "Master Assistant",
      "description": "Public-facing assistant with web search",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        { "prebuilt": "sequentialThinking" },
        { "agentRef": "Web Search Helper" }
      ],
      "expose": true
    }
  ]
}

• expose: true（デフォルト）: エージェントは MCP クライアントのツールとして利用できます
• expose: false: エージェントは他のエージェントから内部的にのみ利用できます

設定ファイルの指定

--config 引数を使用して、カスタム設定ファイルを指定できます。

# Using CLI
npm run test-agent -- --config="path/to/config.json" --name="Agent Name" --prompt="Test prompt"

# When starting the server (multiple formats supported)
node dist/index.js --config=path/to/config.json
node dist/index.js -c path/to/config.json
node dist/index.js --config path/to/config.json

次のような、必要な数の専門エージェントを追加できます。

• コード分析エージェント
• 開発環境エージェント
• ナレッジベースエージェント（Obsidian など）
• プロジェクト管理エージェント（Jira など）
• Google Drive/Workspace エージェント
• ウェブ検索エージェント
• デザインツールエージェント（Figma など）

重要: カスタム設定を作成または更新した後は、必ず次の操作を行ってください。

1. npm run build を実行して、プロジェクトを再ビルドします
2. 変更を適用するため、MCP クライアントを再起動します

デフォルト設定

サーバーには、次の項目を含むデフォルトの agents-config.json が用意されています。

1. Sequential Thinking Agent: 複雑な問題の解決に使用します
2. Brave Search Agent: ウェブ検索に使用します
3. Memory Agent: 情報の保存と取得に使用します
4. Master Agent: 複数のエージェントを組み合わせます

重要: エージェント設定を変更した後は、必ず次の操作を行ってください。

1. npm run build を実行して、プロジェクトを再ビルドします
2. 変更を適用するため、Claude クライアントを再起動します
3. Windows では、Claude がバックグラウンドで実行され続ける場合があるため、タスクマネージャー（Ctrl+Alt+Del）を使用して Claude を完全に終了する必要があります

エージェント設定の例

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Sequential Thinker",
      "description": "Use this agent to think sequentially and resolve complex problems",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "mcpServers": {
            "sequentialThinking": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
            }
          }
        }
      ]
    },
    {
      "name": "Claude Assistant",
      "description": "A powerful AI assistant using Claude's capabilities",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-sonnet-20241022"
      },
      "toolsConfigs": [
        {
          "mcpServers": {
            "memory": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-memory"]
            }
          }
        }
      ]
    },
    {
      "name": "Master Agent",
      "description": "An agent that can manage other agents",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "agentRef": "Sequential Thinker"
        },
        {
          "agentRef": "Memory Agent"
        },
        {
          "agentRef": "Brave Search Agent"
        }
      ]
    }
  ]
}

注: mcp-ai-agent フレームワークは、AI SDK を通じてさまざまな AI モデルをサポートしています。OpenAI、Anthropic、Google Generative AI、Mistral、Groq など、多数のプロバイダーのモデルを使用できます。サポート対象モデルとその機能の一覧については、AI SDK Providers のドキュメントを確認してください。

MCP クライアントへの接続

MCP Agent Server を MCP クライアントの設定に追加します。

Claude Desktop

claude_desktop_config.json を編集します。

npx を使用する場合（推奨）

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "npx",
      "args": ["mcp-agent-server", "--config", "/path/to/your/config.json"]
    }
  }
}

グローバルインストールを使用する場合

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "mcp-agent-server",
      "args": ["--config", "/path/to/your/config.json"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "BRAVE_API_KEY": "your-brave-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

ローカルビルドを使用する場合

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "node",
      "args": [
        "/full/path/to/mcp-agent-server/dist/index.js",
        "--config",
        "/path/to/your/config.json"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "BRAVE_API_KEY": "your-brave-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

重要: claude_desktop_config.json を変更した後は、必ず次の操作を行ってください。

1. 変更を適用するため、Claude クライアントを再起動します
2. Windows では、Claude がバックグラウンドで実行され続ける場合があるため、タスクマネージャー（Ctrl+Alt+Del）を使用して Claude を完全に終了する必要があります

VS Code / Cursor / その他の MCP クライアント

MCP サーバーを追加する手順については、各クライアントの説明に従い、次の内容を使用してください。

• コマンド: node
• 引数: ["/full/path/to/mcp-agent-server/dist/index.js"]

エージェントの使用

設定が完了すると、エージェントは MCP クライアントでツールとして表示されます。たとえば、Claude Desktop では次の手順で使用できます。

1. / を入力して、利用可能なツールを表示します
2. 設定したエージェントのいずれかを選択します
3. プロンプトに従って、コンテキストと具体的なタスクを指定します

詳細設定

カスタムツール

カスタム機能を利用するには、いくつかの方法があります。

1. 事前構築済みサーバーを使用する（推奨）：sequentialThinking、memory、braveSearch、fetch など、利用可能な事前構築済みサーバーから選択します。

2. カスタム MCP サーバーを作成する：独自の MCP サーバーを構築して統合します。

{
  "name": "Calculator Agent",
  "description": "A calculator agent with custom math operations",
  "model": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  },
  "toolsConfigs": [
    {
      "mcpServers": {
        "calculator": {
          "command": "node",
          "args": ["/path/to/your/calculator-mcp-server.js"]
        }
      }
    }
  ]
}

3. 複数の事前構築済みサーバーを組み合わせる：既存のサーバーを組み合わせて、複雑な機能を実現します。

{
  "name": "Multi-Tool Agent",
  "description": "An agent with multiple capabilities",
  "model": {
    "provider": "anthropic",
    "model": "claude-3-5-haiku-20241022"
  },
  "toolsConfigs": [
    {
      "prebuilt": "sequentialThinking"
    },
    {
      "prebuilt": "memory"
    },
    {
      "prebuilt": "fetch"
    }
  ]
}

外部エージェントのインポート

外部ファイルからエージェントをインポートできます。例については、@fkesheh/mcp-ai-agent-example/exportable-agent.ts を参照してください。

1. エージェントファイルを作成する

// my-agent.ts
import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new AIAgent({
  name: "My Custom Agent",
  description: "A custom agent",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.sequentialThinking],
});

2. JavaScript にビルドする

npx tsc  # Creates my-agent.js in dist/ folder

3. 設定で使用する

{
  "type": "import",
  "importPath": "/full/path/to/dist/my-agent.js",
  "exportName": "myAgent"
}

重要：コンパイル済みの .js ファイルには、必ず絶対パスを使用してください。

MCP サーバーの使用

mcp-ai-agent フレームワークは、さまざまな MCP サーバーに対応しています。

• Sequential Thinking：複雑な問題を分解するためのサーバー
• Memory：情報を永続的に保存するためのサーバー
• Brave Search：ウェブ検索用のサーバー
• その他多数…

トラブルシューティング

• エージェントの初期化に失敗する場合は、MCP サーバーが正しく設定されていることを確認してください
• 「npx」コマンドを使用する場合、必要に応じて完全なパスが指定されていることを確認してください
• 必要な API キーがすべて環境で利用可能であることを確認してください
• MCP クライアントが MCP Agent Server を使用するよう正しく設定されていることを確認してください

開発

1. TypeScript ファイルを変更します
2. npm run build で再ビルドします
3. MCP クライアントを再起動して変更を読み込みます

CLI の使用方法

MCP Agent Server には、エージェントを操作するためのコマンドラインインターフェース（CLI）が用意されています。

エージェントのテスト

MCP クライアントに接続せずに、コマンドラインから個々のエージェントを直接テストできます。デバッグに役立ちます。

npx を使用する（推奨）

npx mcp-agent-server test-agent --config="/path/to/config.json" --name="Agent Name" --prompt="Your test prompt" --context="Optional context"

たとえば、Brave Search Agent をテストするには、次のようにします。

npx mcp-agent-server test-agent --config="./agents-config.json" --name="Brave Search" --prompt="What is the capital of France?" --context="I need geographical information"

または、複数の特化型エージェントを組み合わせた Master Agent をテストします。

npx mcp-agent-server test-agent --config="./my-agents-config.json" --name="Master Agent" --prompt="Store this information: Claude is an AI assistant by Anthropic" --context="I need to test the memory capabilities"

注：--config が指定されていない場合、サーバーは現在のディレクトリにある agents-config.json または my-agents-config.json を検索します。

ローカル開発環境を使用する

npm run test-agent -- --config="path/to/config.json" --name="Agent Name" --prompt="Your test prompt" --context="Optional context"

または、コマンドを直接実行します。

node dist/cli.js test-agent --config="./agents-config.json" --name="Sequential Thinker" --prompt="How would I approach solving a complex math problem?"

テストコマンドは次の処理を行います。

1. 指定された名前でエージェントを検索する
2. エージェントを初期化する
3. プロンプトとコンテキストを送信する
4. エージェントの応答を表示する

次の用途に役立ちます。

• 新しいエージェント設定のテスト
• エージェントの問題のデバッグ
• MCP クライアントに接続する前の、エージェント機能の検証

無効なエージェント名を指定すると、テストコマンドは利用可能なすべてのエージェントを一覧表示します。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。