Agent SDK で MCP をつなぐ｜外部ツール連携の設定

公開 更新 著者 永上裕之仕事の自動化
#Claude Agent SDK#MCP#外部ツール連携#AIエージェント#API連携
AIエージェントからケーブルが伸びて、いろいろな外部の道具につながっているイメージ

この記事の要点

  • MCP は AI エージェントを外部の道具やデータにつなぐ共通の規格。Agent SDK ではコードか設定ファイルでサーバーを足す
  • つなぎ方は、手元で動かす（stdio）・URL でつなぐ（HTTP・SSE）・アプリの中に作る（SDK サーバー）の3つ
  • MCP の道具は許可しないと使えない。allowedTools に mcp__サーバー名__道具名 で書くのが基本

AI エージェントに社内のデータベースやチャット、課題管理を触らせたいとき、窓口になるのが MCP（Model Context Protocol） です。CLI の Claude Code で MCP を使う方法は Claude Code の MCP で解説しました。

この記事では、公式ドキュメント「Connect to external tools with MCP」（2026年11月9日確認）にもとづいて、Agent SDK で作るアプリから MCP サーバーをつなぐ設定 を整理します。

結論：サーバーを足し、道具を許可し、状態を確かめる

MCP は、AI エージェントを外部の道具やデータにつなぐための共通の規格 です。Agent SDK では、次の3つをそろえれば使えます。

  1. サーバーを足す：呼び出しの設定（mcpServers）に書くか、プロジェクトの .mcp.json に書く
  2. 道具を許可する：許可リスト（allowedTools）に、使ってよい道具の名前を書く
  3. 状態を確かめる：会話の最初に届く init メッセージで、つながったかを見る
AIエージェントから3種類のつなぎ方で外部の道具へ線が伸びる図
AIエージェントから3種類のつなぎ方で外部の道具へ線が伸びる図（イメージ）

サーバーの足し方は2つ

足し方書く場所向いている場面
コードで足すquery の mcpServersアプリごとに使うサーバーを決めたい
設定ファイルで足すプロジェクトの直下の .mcp.jsonCLI とも同じ設定を使い回したい

.mcp.json は、設定の読み込み元に project が入っているときに読まれます。 何も指定しなければ入っていますが、読み込み元（settingSources）を自分で指定したときは、project を含めないと読まれません。

つなぎ方は3つ

サーバーの説明書きに「実行するコマンド」があれば stdio、「URL」があれば HTTP か SSE を選びます。

つなぎ方中身例
stdio同じマシンで別のプログラムとして動かし、入出力でやりとりするnpx で始めるファイル操作のサーバーなど
HTTP・SSEネットの向こうのサーバーに URL でつなぐクラウドで提供されているサーバー
SDK サーバー自分のアプリのコードの中に道具を作る社内の API を包んだ独自の道具

HTTP のうち新しい方式は type を http と書きます。自分で道具を作る方法は Agent SDK のカスタムツール で解説しています。

道具は許可しないと使えない

MCP の道具は、許可しないと AI から見えていても呼び出せません。 名前は mcp__サーバー名__道具名 の形です。サーバー名にある「.」や空白は「_」に置き換わります。

書き方意味
mcp__github__list_issuesgithub サーバーの list_issues だけ許可
mcp__github__*github サーバーの道具をすべて許可

公式は 「MCP の許可は、権限モードより許可リストで」 と勧めています。ファイル編集をまとめて許す acceptEdits では MCP の道具は許可されず、何でも許す bypassPermissions では MCP 以外の安全確認まで外れてしまうためです。権限の判定の順番は Agent SDK の権限設定 で解説しています。

道具が多いと、その説明だけで会話の容量を圧迫します。そこで SDK は、必要な道具の説明だけをその都度読み込む「道具の検索」を既定でオン にしています。

認証の渡し方

鍵やトークンは、設定に直接書かず環境変数から渡します。 stdio のサーバーには env 欄で、HTTP・SSE のサーバーには headers 欄で渡します。設定ファイルでは ${API_KEY} のように書くと、実行時に環境変数の値に置き換わります。

OAuth でログインするサーバーには注意があります。SDK はブラウザを開いてログインする流れを自分では行いません。 ログインが要るサーバーは状態が needs-auth になり、そのサーバーの道具なしで作業が続きます。自分のアプリでログインの流れを済ませ、受け取ったトークンを headers で渡す形にします。

つながったかの見方

会話の最初に届く init メッセージに、サーバーごとの状態 が入ります。

状態意味
connectedつながった
pendingまだつなぎ中、または前回の道具の一覧を使っていて最初の呼び出しでつなぐ。失敗とは限らない
failedつながらなかった
needs-authログインが要る
disabled無効にしている

使えないサーバーを見つけるときは、failed と needs-auth を見ます。 pending だけで失敗と決めつけないのがポイントです。途中で接続が切れると pending に戻って自動でつなぎ直し、5回失敗すると failed になります。

つながらない時の主な原因は、環境変数の入れ忘れ、サーバーのプログラムが入っていない、接続先の書き間違い、ネットワークの制限です。道具が見えているのに使われない時は、許可リストを確かめます。

時間と大きさの上限

データベースにつなぐ例では、公式も 読み取り専用の設定にしておくこと を勧めています。AI が書いた SQL がそのまま実行されるため、書き込みを許すかどうかは人が先に決めておきます。

まとめ

出典

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール＆コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事

Agent SDK のファイル巻き戻し｜チェックポイントの使い方2026-11-09・仕事の自動化
Claude Code SDK から Agent SDK へ｜移行の手順と注意点2026-11-09・仕事の自動化
Agent SDK の権限設定｜6段階の判定と安全な組み方2026-11-09・仕事の自動化