SpyBara
Go Premium

agent-sdk/mcp.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

79 added, 27 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

MCP を使用して外部ツールに接続する

MCP サーバーを設定してエージェントを外部ツールで拡張します。トランスポートタイプ、大規模なツールセット向けのツール検索、認証、エラーハンドリングについて説明します。

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

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

クイックスタート

この例は、HTTP トランスポートを使用して Claude Code ドキュメンテーション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);
}
}

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

MCP サーバーを追加する

query() を呼び出すときにコード内で MCP サーバーを設定するか、settingSources経由で読み込まれる .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 ファイルを作成します。project 設定ソースが有効な場合、ファイルが取得されます。これはデフォルトの query() オプションの場合です。settingSources を明示的に設定する場合は、このファイルを読み込むために "project" を含めます：

{
  "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 ツールを指定します：

const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: [
      "mcp__github__*", // All tools from the github server
      "mcp__db__query", // Only the query tool from db server
      "mcp__slack__send_message" // Only send_message from slack server
    ]
  }
};

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

利用可能なツールを検出する

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 サーバーに使用します：

const _ = {
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: process.env.GITHUB_TOKEN
}
}
},
allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]
}
};

HTTP/SSE サーバー

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

const _ = {
options: {
mcpServers: {
"remote-api": {
type: "sse",
url: "https://api.example.com/mcp/sse",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__remote-api__*"]
}
};

ストリーミング可能な HTTP トランスポートの場合は、代わりに "type": "http" を使用します。.mcp.json およびその他の JSON 設定ファイルでは、"streamable-http" は "http" のエイリアスとして受け入れられます。プログラマティック mcpServers オプションは "http" のみを受け入れます。

SDK MCP サーバー

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

多くの MCP ツールを設定している場合、ツール定義はコンテキストウィンドウの大部分を消費する可能性があります。ツール検索は、コンテキストからツール定義を保留し、各ターンで Claude が必要とするツールのみを読み込むことでこれを解決します。

ツール検索はデフォルトで有効になっています。設定オプションと詳細については、ツール検索を参照してください。

カスタム SDK ツールでのベストプラクティスとツール検索の使用を含む詳細については、ツール検索ガイドを参照してください。

認証

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

環境変数を通じて認証情報を渡す

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

const _ = {
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: process.env.GITHUB_TOKEN
}
}
},
allowedTools: ["mcp__github__list_issues"]
}
};

デバッグログを含む完全な動作例については、リポジトリからの問題のリストを参照してください。

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

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

const _ = {
options: {
mcpServers: {
"secure-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__secure-api__*"]
}
};

OAuth2 認証

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

// After completing OAuth flow in your app
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"]
}
})) {
// Verify MCP server connected successfully
if (message.type === "system" && message.subtype === "init") {
console.log("MCP servers:", message.mcp_servers);
}

// Log when Claude calls an MCP tool
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
console.log("MCP tool called:", block.name);
}
}
}

// Print the final result
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

データベースをクエリする

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

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

// Connection string from environment variable
const connectionString = process.env.DATABASE_URL;

for await (const message of query({
// Natural language query - Claude writes the SQL
prompt: "How many users signed up last week? Break it down by day.",
options: {
mcpServers: {
postgres: {
command: "npx",
// Pass connection string as argument to the server
args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
}
},
// Allow only read queries, not writes
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");
}
}

トラブルシューティング

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

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 で許可を付与していることを確認します：

const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
  }
};

接続タイムアウト

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

  • 利用可能な場合は、より軽量なサーバーを使用する
  • エージェントを開始する前にサーバーをプリウォーミングする
  • 遅い初期化の原因についてサーバーログを確認する