MCPで外部ツールに接続する

Model Context Protocol (MCP)は、AIエージェントを外部ツールやデータソースに接続するためのオープンスタンダードです。MCPを使用すると、エージェントはデータベースにクエリを実行したり、SlackやGitHubなどのAPIと統合したり、カスタムツール実装を書くことなく他のサービスに接続したりできます。

MCPサーバーは、ローカルプロセスとして実行したり、HTTP経由で接続したり、SDKアプリケーション内で直接実行したりできます。

クイックスタート

この例では、HTTP transportを使用してClaude Code documentation MCPサーバーに接続し、allowedToolsでワイルドカードを使用してサーバーからのすべてのツールを許可します。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

エージェントはドキュメントサーバーに接続し、フックに関する情報を検索して結果を返します。

MCPサーバーを追加する

MCPサーバーは、query()を呼び出す際にコード内で設定するか、SDKが自動的に読み込む.mcp.jsonファイルで設定できます。

コード内で

mcpServersオプションにMCPサーバーを直接渡します：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

設定ファイルから

プロジェクトルートに.mcp.jsonファイルを作成します。SDKはこれを自動的に読み込みます：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

MCPツールを許可する

MCPツールは、Claudeが使用する前に明示的な許可が必要です。許可がない場合、Claudeはツールが利用可能であることを認識しますが、呼び出すことはできません。

ツールの命名規則

MCPツールはmcp__<server-name>__<tool-name>という命名パターンに従います。例えば、"github"という名前のGitHubサーバーのlist_issuesツールはmcp__github__list_issuesになります。

allowedToolsでアクセスを付与する

allowedToolsを使用して、Claudeが使用できるMCPツールを指定します：

options: {
  mcpServers: { /* your servers */ },
  allowedTools: [
    "mcp__github__*",              // githubサーバーのすべてのツール
    "mcp__db__query",              // dbサーバーのqueryツールのみ
    "mcp__slack__send_message"     // slackサーバーのsend_messageのみ
  ]
}

ワイルドカード（*）を使用すると、個別にリストすることなくサーバーのすべてのツールを許可できます。

代替方法：パーミッションモードを変更する

許可するツールをリストする代わりに、パーミッションモードを変更してより広範なアクセスを付与できます：

• permissionMode: "acceptEdits"：ツールの使用を自動的に承認します（破壊的な操作にはプロンプトが表示されます）
• permissionMode: "bypassPermissions"：ファイル削除やシェルコマンドの実行などの破壊的な操作を含む、すべての安全プロンプトをスキップします。特に本番環境では注意して使用してください。このモードはTaskツールによって生成されるサブエージェントに伝播します。

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // allowedToolsは不要
}

パーミッションモードの詳細については、パーミッションを参照してください。

利用可能なツールを確認する

MCPサーバーが提供するツールを確認するには、サーバーのドキュメントを確認するか、サーバーに接続してsystem initメッセージを検査します：

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available MCP tools:", message.mcp_servers);
  }
}

トランスポートタイプ

MCPサーバーは、異なるトランスポートプロトコルを使用してエージェントと通信します。サーバーがサポートするトランスポートについては、サーバーのドキュメントを確認してください：

• ドキュメントに実行するコマンド（npx @modelcontextprotocol/server-githubなど）が記載されている場合は、stdioを使用します
• ドキュメントにURLが記載されている場合は、HTTPまたはSSEを使用します
• コード内で独自のツールを構築する場合は、SDK MCPサーバーを使用します

stdioサーバー

stdin/stdoutを介して通信するローカルプロセスです。同じマシン上で実行するMCPサーバーに使用します：

HTTP/SSEサーバー

クラウドホストされたMCPサーバーやリモートAPIにはHTTPまたはSSEを使用します：

HTTP（非ストリーミング）の場合は、代わりに"type": "http"を使用します。

SDK MCPサーバー

別のサーバープロセスを実行する代わりに、アプリケーションコード内で直接カスタムツールを定義します。実装の詳細については、カスタムツールガイドを参照してください。

MCPツール検索

多数のMCPツールが設定されている場合、ツール定義がコンテキストウィンドウのかなりの部分を消費する可能性があります。MCPツール検索は、すべてのツールをプリロードする代わりに、オンデマンドでツールを動的にロードすることでこの問題を解決します。

仕組み

ツール検索はデフォルトでautoモードで実行されます。MCPツールの説明がコンテキストウィンドウの10%以上を消費する場合にアクティブになります。トリガーされると：

1. MCPツールは事前にコンテキストにロードされるのではなく、defer_loading: trueとしてマークされます
2. Claudeは必要に応じて検索ツールを使用して関連するMCPツールを発見します
3. Claudeが実際に必要とするツールのみがコンテキストにロードされます

ツール検索にはtool_referenceブロックをサポートするモデルが必要です：Sonnet 4以降、またはOpus 4以降。Haikuモデルはツール検索をサポートしていません。

ツール検索を設定する

ENABLE_TOOL_SEARCH環境変数でツール検索の動作を制御します：

envオプションで値を設定します：

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // 5%のしきい値で有効化
  }
};

認証

ほとんどのMCPサーバーは、外部サービスにアクセスするために認証が必要です。サーバー設定で環境変数を通じて認証情報を渡します。

環境変数で認証情報を渡す

envフィールドを使用して、APIキー、トークン、その他の認証情報をMCPサーバーに渡します：

デバッグログを含む完全な動作例については、リポジトリからイシューを一覧表示するを参照してください。

リモートサーバー用のHTTPヘッダー

HTTPおよびSSEサーバーの場合、サーバー設定で直接認証ヘッダーを渡します：

OAuth2認証

MCP仕様はOAuth 2.1をサポートしています。SDKはOAuthフローを自動的に処理しませんが、アプリケーションでOAuthフローを完了した後、ヘッダー経由でアクセストークンを渡すことができます：

// アプリでOAuthフローを完了した後
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
  mcpServers: {
    "oauth-api": {
      type: "http",
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: `Bearer ${accessToken}`
      }
    }
  },
  allowedTools: ["mcp__oauth-api__*"]
};

例

リポジトリからイシューを一覧表示する

この例では、GitHub MCPサーバーに接続して最近のイシューを一覧表示します。この例には、MCP接続とツール呼び出しを確認するためのデバッグログが含まれています。

実行する前に、repoスコープを持つGitHubパーソナルアクセストークンを作成し、環境変数として設定してください：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List the 3 most recent issues in anthropics/claude-code",
  options: {
    mcpServers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
})) {
  // MCPサーバーが正常に接続されたことを確認
  if (message.type === "system" && message.subtype === "init") {
    console.log("MCP servers:", message.mcp_servers);
  }

  // ClaudeがMCPツールを呼び出した時にログ出力
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
        console.log("MCP tool called:", block.name);
      }
    }
  }

  // 最終結果を出力
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

データベースにクエリを実行する

この例では、Postgres MCPサーバーを使用してデータベースにクエリを実行します。接続文字列はサーバーへの引数として渡されます。エージェントは自動的にデータベーススキーマを検出し、SQLクエリを作成して結果を返します：

import { query } from "@anthropic-ai/claude-agent-sdk";

// 環境変数からの接続文字列
const connectionString = process.env.DATABASE_URL;

for await (const message of query({
  // 自然言語クエリ - ClaudeがSQLを作成
  prompt: "How many users signed up last week? Break it down by day.",
  options: {
    mcpServers: {
      "postgres": {
        command: "npx",
        // 接続文字列をサーバーへの引数として渡す
        args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
      }
    },
    // 読み取りクエリのみ許可、書き込みは不可
    allowedTools: ["mcp__postgres__query"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

エラーハンドリング

MCPサーバーは様々な理由で接続に失敗する可能性があります：サーバープロセスがインストールされていない、認証情報が無効、またはリモートサーバーに到達できないなどです。

SDKは各クエリの開始時にサブタイプinitのsystemメッセージを発行します。このメッセージには各MCPサーバーの接続ステータスが含まれています。エージェントが作業を開始する前に接続の失敗を検出するには、statusフィールドを確認してください：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );

    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }

  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed");
  }
}

トラブルシューティング

サーバーが「failed」ステータスを表示する

initメッセージを確認して、どのサーバーが接続に失敗したかを確認します：

if (message.type === "system" && message.subtype === "init") {
  for (const server of message.mcp_servers) {
    if (server.status === "failed") {
      console.error(`Server ${server.name} failed to connect`);
    }
  }
}

一般的な原因：

• 環境変数の欠落：必要なトークンと認証情報が設定されていることを確認してください。stdioサーバーの場合、envフィールドがサーバーの期待するものと一致していることを確認してください。
• サーバーがインストールされていない：npxコマンドの場合、パッケージが存在し、Node.jsがPATHに含まれていることを確認してください。
• 無効な接続文字列：データベースサーバーの場合、接続文字列の形式とデータベースにアクセスできることを確認してください。
• ネットワークの問題：リモートHTTP/SSEサーバーの場合、URLに到達可能であり、ファイアウォールが接続を許可していることを確認してください。

ツールが呼び出されない

Claudeがツールを認識しているが使用しない場合、allowedToolsまたはパーミッションモードの変更で許可を付与しているか確認してください：

options: {
  mcpServers: { /* your servers */ },
  allowedTools: ["mcp__servername__*"]  // Claudeがツールを使用するために必要
}

接続タイムアウト

MCP SDKにはサーバー接続のデフォルトタイムアウトが60秒あります。サーバーの起動にそれ以上の時間がかかる場合、接続は失敗します。起動に時間がかかるサーバーの場合は、以下を検討してください：

• 利用可能であれば、より軽量なサーバーを使用する
• エージェントを開始する前にサーバーをウォームアップする
• サーバーログで初期化が遅い原因を確認する

関連リソース

• カスタムツールガイド：SDKアプリケーション内でインプロセスで実行される独自のMCPサーバーを構築する
• パーミッション：allowedToolsとdisallowedToolsでエージェントが使用できるMCPツールを制御する
• TypeScript SDKリファレンス：MCP設定オプションを含む完全なAPIリファレンス
• Python SDKリファレンス：MCP設定オプションを含む完全なAPIリファレンス
• MCPサーバーディレクトリ：データベース、API、その他の利用可能なMCPサーバーを閲覧する