Developer Foundations ドメイン8: ツールと MCP（10.6%）

この章で学ぶこと: ツールの実装（ツール利用、関数呼び出し、説明文、エラー処理、クライアント側とサーバー側のツール、承認のパターン、ツールセットのベストプラクティス）、MCP サーバーの開発（作る・配備する・つなぐ、リソース・ツール・プロンプト、stdio などの通信方式、クライアントとサーバー）、エージェントのカスタマイズ（組み込みツール・カスタムツール・Skills・MCP の使い分け）。

スキル	配点	この章の節
ツールの実装（Tool Implementation）	4.4%	第1節
MCP サーバー開発（MCP Server Development）	2.1%	第2節
エージェントのカスタマイズ（Agentic Customization）	4.1%	第3節

本番の53問のうち約6問が出ます。

前の章とつながる部分:

ツール利用のループ（stop_reason: "tool_use"、tool_result） → ドメイン1 第2.2節
ツールのエラーの返し方（is_error）、pause_turn → ドメイン4
新しいモデルでのツールの強制（tool_choice）の制限 → ドメイン5 第3.3節
厳密なツール利用（strict: true）、構造化出力 → ドメイン2 第3.6節
Claude Code のスキル、プラグイン → ドメイン3、ドメイン2 第5.5節
MCP の秘密情報と信頼 → ドメイン7

1. ツールの実装（4.4%）

1.1 ツールの定義

ツール利用（関数呼び出し、function calling とも呼ぶ）では、リクエストの tools にツールを並べます。

項目	意味
`name`	ツールの名前。`^[a-zA-Z0-9_-]{1,128}$` に合うこと
`description`	何をするか、いつ使うか、どう動くかの詳しい説明
`input_schema`	入力のパラメータを決める JSON Schema
`input_examples`	（任意）ツールの使い方を見せる、スキーマに合った入力の例

1.2 ツール定義のベストプラクティス（公式）

ベストプラクティス	内容
説明をとても詳しく書く	ツールの性能に効く、いちばん大事な要素。何をするか、いつ使うか（使わないか）、各パラメータの意味、注意点と限界を書く。1つのツールにつき少なくとも3〜4文
複雑なツールには `input_examples`	入れ子のオブジェクトや形式にうるさいパラメータがあるとき
関係する操作はまとめる	`create_pr`、`review_pr`、`merge_pr` を別々に作るより、`action` パラメータを持つ1つのツールにまとめる。ツールが少ないほど選び間違いが減る
名前に意味のある接頭辞を付ける	複数のサービスにまたがるなら `github_list_prs`、`slack_send_message` のように。ツールが増えたときやツール検索で特に大事
結果は情報量の高いものだけ返す	意味があって変わらない ID（slug や UUID）を返し、次の判断に必要な項目だけを入れる。ふくらんだ結果はコンテキストを無駄にする
理由ではなく説明を求める	パラメータで「なぜ呼ぶか」を聞くなら、短い説明や根拠を求める。thinking や段階的な推論を求めると `reasoning_extraction` で拒否されることがある

「まとめる」と「分ける」: Architect Foundations の試験ガイドには、何でもする汎用のツールを目的別のツールに分ける例も出てきます。どちらも目的は同じで、「どのツールを使うべきかがあいまいにならないようにする」ことです。似た操作が別々のツールに散らばって迷うならまとめ、1つのツールの役割が広すぎて使い方がぶれるなら分けます（筆者のまとめ）。

Anthropic のエンジニアリング記事「Writing effective tools for agents」より:

ツールは多ければよいわけではない。既存のソフトウェアの機能や API をそのまま包んだだけのツールは、エージェントに合わないことがある
例: 住所録なら、全件を返す list_contacts より、search_contacts や message_contact のように、よく使う仕事に合わせたツールを作る
大量の結果を返しうるツールには、ページ分け、範囲の指定、絞り込み、切り詰めを、適切な初期値と一緒に入れる。Claude Code はツールの結果を初期設定で25,000トークンまでに制限している
ツールの説明は、新しく入ったチームメンバーに説明するつもりで書く

1.3 tool_choice

値	意味
`{"type": "auto"}`（初期値）	ツールを使うかどうかを Claude が決める
`{"type": "any"}`	必ずどれかのツールを使う
`{"type": "tool", "name": "..."}`	指定したツールを必ず使う
`{"type": "none"}`	ツールを使わない

注意: any と tool は、手動の extended thinking を使うときや、Claude Opus 5.5・Sonnet 5.5・Fable 5.1 などの新しいモデルでは使えず、エラーになります。そのときは auto と strict: true を組み合わせ、いつそのツールを使うかをプロンプトに書きます（ドメイン5）。

1.4 クライアント側のツールとサーバー側のツール

	クライアントツール	サーバーツール
実行する場所	自分のアプリ	Anthropic のインフラ
例	自分で定義したツール、Anthropic がスキーマを決めたツール（bash、text editor など）	`web_search`、`web_fetch`、`code_execution`、`tool_search`
応答	`stop_reason: "tool_use"` と `tool_use` ブロック。自分で実行して `tool_result` を返す	`server_tool_use` ブロック（ID は `srvtoolu_` で始まる）と結果のブロックが同じ応答に入る。`tool_result` を返す必要はない
長い処理	—	サーバー側のループが一時停止すると `pause_turn`。応答を会話に足して送り直す（ドメイン4）

1.5 ループを任せる: tool runner

SDK の tool runner（ベータ）は、ツールの実行、リクエストと応答のくり返し、会話の状態の管理、型の確認を自動でやってくれます。Python では @beta_tool デコレーターで、型ヒントと docstring からツールを定義できます。

人の承認、独自のログ、条件つきの実行が必要なときは、tool runner ではなく自分でループを書きます（公式の説明）。

1.6 エラー処理

ドメイン4 第2.1節のとおりです。要点だけ:

ツールの実行の失敗は tool_result に "is_error": true と、何が起きて次に何をすればよいかを書いて返す
不正な呼び出し（必須パラメータの欠けなど）は、説明を詳しくする、strict: true を使う

1.7 承認のパターン

しくみ	どう承認するか
自分で書いたループ（Messages API）	`tool_use` を受け取ったら、実行する前に人に確認する（tool runner ではなく手動のループ）
Agent SDK	権限モード（`default` なら承認のコールバックへ）、`allowed_tools` / `disallowed_tools`、ルール（例: `Bash(npm *)`）、フック（ドメイン1）
Agent SDK のカスタムツール	TypeScript では、`createSdkMcpServer()` が返す設定に、ツールごとの `permission_policy` を足して承認を求めたり止めたりできる
Claude Code	許可・確認・拒否のルール（`/permissions`）、権限モード、フック（ドメイン7）
MCP サーバー	サーバーが elicitation で利用者に追加の情報や確認を求めることができる（第2.3節）

2. MCP サーバーの開発（2.1%）

2.1 MCP のしくみ

MCP（Model Context Protocol）は、AI アプリを外部のツールやデータにつなぐための共通の仕様です。

役割	意味	例
MCP ホスト	1つ以上の MCP クライアントをまとめる AI アプリ	Claude Code、Claude Desktop
MCP クライアント	1つの MCP サーバーとの接続を保ち、そこから情報を取ってホストに渡す部品。ホストはサーバーごとに1つのクライアントを作る	—
MCP サーバー	クライアントに情報や機能を提供するプログラム	ファイル、データベース、Sentry などのサーバー

しくみの層:

データの層: JSON-RPC 2.0 にもとづく決まり。対応機能やバージョンの確認、ツール・リソース・プロンプト・通知などを定める
通信の層: どう届けるか（第2.2節）。どの通信方式でも同じ JSON-RPC 2.0 のメッセージを使う

2.2 通信方式（transport）

方式	しくみ	向いている場面
stdio	同じマシンの中で、標準入出力でプロセス同士が直接やりとりする。ネットワークのむだがない	ローカルのサーバー。ふつう1つのクライアントに対応
Streamable HTTP	クライアントからサーバーへは HTTP POST、ストリーミングには必要に応じて SSE を使う。bearer トークン、API キー、独自ヘッダーなどの HTTP の認証が使え、MCP はトークンの取得に OAuth を勧めている	リモートのサーバー。ふつう多くのクライアントに対応
SSE（古い方式）	Claude Code では非推奨。使えるなら HTTP にする	古いサーバー

2.3 サーバーが提供するもの

機能	意味	例	だれが使うかを決める
ツール（Tools）	AI アプリが呼んで操作をする関数。データベースへの書き込み、外部 API の呼び出し、ファイルの変更など	航空便を探す、メッセージを送る	モデル
リソース（Resources）	読み取り専用で情報を渡すデータ。ファイルの中身、データベースのスキーマ、API の文書など	文書を取り出す、ナレッジベースを見る	アプリ
プロンプト（Prompts）	特定のツールやリソースと一緒に使う、あらかじめ作った指示のひな形	旅行の計画、会議のまとめ	利用者

サーバーからクライアントに頼めること:

elicitation: 利用者に追加の情報や操作の確認を求める
sampling: クライアント側の AI アプリに、言語モデルの生成を頼む（サーバーが自分で LLM の SDK を持たなくてよい）
logging: デバッグや監視のためのログを送る。stdio なら stderr に書くか、OpenTelemetry を使う

ツールは tools/list で見つけ、呼び出しの決まりに従って実行されます。

2.4 作る・つなぐ

つなぐ先	方法
Claude Code	`claude mcp add --transport http <名前> <URL>`（リモート）、`claude mcp add --transport stdio <名前> -- <コマンド>`（ローカル）。Claude に頼むと、リモートの HTTP かローカルの stdio のサーバーのひな形も作ってくれる
Messages API	MCP connector（ベータ）。リクエストに `mcp_servers` と、それに合う `mcp_toolset` を `tools` に入れると、MCP クライアントを自分で作らずにリモートの MCP サーバーにつなげる。全部のツールを使う、許可リスト、拒否リスト、ツールごとの設定ができる。OAuth の bearer トークンにも対応
Agent SDK	`mcpServers` に MCP サーバーを渡す。カスタムツールは、SDK のプロセス内の MCP サーバー（Python の `@tool` と `create_sdk_mcp_server`、TypeScript の `tool()` と `createSdkMcpServer`）として作る
Managed Agents	エージェントに MCP サーバーを宣言する。認証情報はセッションごとに vault を参照して渡す

Claude Code での MCP サーバーの範囲:

範囲	読み込まれる場所	チームと共有	保存先
local	このプロジェクトだけ	しない	`~/.claude.json`
project	このプロジェクトだけ	する（バージョン管理で）	プロジェクトのルートの `.mcp.json`
user	自分の全プロジェクト	しない	`~/.claude.json`

Claude Code での使い方:

.mcp.json や ~/.claude.json では ${VAR} の環境変数展開が使える。トークンはコミットしない（ドメイン7）
リソースは、ファイルと同じように @ で参照できる
MCP のプロンプトは、/サーバー名:プロンプト名 のコマンドとして使える
接続の状態は /mcp で確認する
公式の注意: 自分で作った MCP サーバーか、信頼できる提供元のサーバーを使う。Anthropic はディレクトリに載せる前に基準で確かめるが、MCP サーバーのセキュリティ監査や管理はしない

3. エージェントのカスタマイズ（4.1%）

組み込みツール、カスタムツール、Skills、MCP の使い分けです。

方法	何をするか	向いている場面	例
組み込みツール	Claude Code / Agent SDK に最初からあるツール（Read、Edit、Write、Glob、Grep、Bash、WebSearch、WebFetch など）	ファイル、コマンド、Web など、どこでも使う基本の操作	コードを探して直す
サーバーツール（API）	Anthropic が動かすツール（`web_search`、`code_execution` など）	自分で実行の仕組みを作りたくない	最新の情報の検索
カスタムツール	自分で定義する関数（Messages API の `tools`、Agent SDK のプロセス内 MCP サーバー）	自分のアプリの中だけで使う、特定の処理	自社の在庫 API を呼ぶ
MCP サーバー	外部のサービスにつなぐ共通の仕様。接続と認証はサーバーが受け持つ	複数のアプリやチームで同じ連携を再利用したい、アプリとは別に保守したい	Slack、データベース、ブラウザの操作
Skills	指示・知識・手順・スクリプトのまとまり。必要なときだけ読み込まれる	くり返す作業の手順、チームの決まり、参考資料	コードレビューの手順、デプロイの手順、API のスタイルガイド

3.1 MCP と Skills の違い（公式）

MCP は Claude を外部のサービスにつなぐ。Skills は、Claude が知っていること（そのサービスの上手な使い方も含む）を増やす
2つは違う問題を解き、一緒に使うとよい。例: MCP でデータベースにつなぎ、スキルにチームのスキーマとクエリの書き方を入れる

3.2 Skills のしくみ（Agent Skills）

ファイルの集まり（ディレクトリ）として、指示、実行できるコード、参考資料を持つ
段階的に読み込む（progressive disclosure）:

段階	いつ読み込むか	量の目安	中身
1: メタデータ	起動時（いつも）	1スキルあたり約100トークン	frontmatter の `name` と `description`
2: 指示	スキルが使われるとき	5,000トークン未満	`SKILL.md` の本文
3: 資料とコード	必要になったとき	必要な分だけ	参考ファイル、スクリプト

Anthropic が用意したスキル（PowerPoint、Excel、Word、PDF の作業など）と、自分で作るカスタムスキルがある。カスタムスキルは Claude Code で作る、Claude API でアップロードする、claude.ai の設定で追加する、などで使える

3.3 選び方の目安

こんなとき	選ぶもの
社内の REST API を、複数の Claude アプリで共有し、アプリとは別に保守したい	MCP サーバー
1つのアプリの中だけで、決まった計算や処理を呼びたい	カスタムツール
ファイルの読み書き、検索、コマンドの実行	組み込みツール
手順や決まりをくり返し使いたい（毎回プロンプトに書きたくない）	Skills
標準的なサービス（課題管理など）とつなぎたい	既存の信頼できる MCP サーバーを先に探す
まとめて配りたい（スキル、フック、サブエージェント、MCP サーバー）	プラグイン（ドメイン2 第5.5節）

組み込みツールでは、どんな社内 API にも届くわけではありません。社内のシステムにつなぐには、カスタムツールか MCP サーバーが必要です。

4. 試験に向けたまとめ

問われ方	考え方
ツールの選び間違い	説明を詳しくする（3〜4文以上）、名前に接頭辞、重なりをなくす
ツールが多すぎる	関係する操作をまとめる。よく使う仕事に合わせたツールにする
ツールの結果が大きすぎる	必要な項目だけ、ページ分けや絞り込み
必ずツールを使わせたい	`any` / `tool`。ただし新しいモデルでは `auto` + `strict` + プロンプト
web_search の結果の扱い	サーバーツール。`tool_result` を返さなくてよい。`pause_turn` に注意
ループを自動にしたい	tool runner。承認が必要なら手動のループ
ローカルの MCP サーバー	stdio
リモートの MCP サーバー	Streamable HTTP（認証は OAuth が勧められる）
ツール・リソース・プロンプト	モデルが呼ぶ操作 / アプリが渡す読み取り専用のデータ / 利用者が選ぶひな形
チームで共有する MCP の設定	`.mcp.json`（project の範囲）、トークンは `${VAR}`
API から MCP サーバーを使う	MCP connector（`mcp_servers` と `mcp_toolset`）
複数アプリで再利用する社内連携	MCP サーバー
くり返す手順の知識	Skills

5. 用語集

用語	意味
関数呼び出し（function calling）	ツール利用の別名
クライアントツール / サーバーツール	自分のアプリで動くツール / Anthropic で動くツール
tool runner	SDK がツールのループを自動でやるしくみ
MCP ホスト / クライアント / サーバー	AI アプリ / 1つのサーバーとの接続 / 機能を提供するプログラム
stdio / Streamable HTTP	ローカルの標準入出力 / リモートの HTTP
elicitation	MCP サーバーが利用者に追加の情報や確認を求めること
progressive disclosure	必要な分だけ段階的に読み込むこと

出典

Define tools（Claude Platform Docs）: ツールの項目、定義のベストプラクティス、ツールの強制とその制限
Tool use overview（Claude Platform Docs）: クライアントツールとサーバーツール、tool_choice の初期値
Server tools（Claude Platform Docs）: server_tool_use、pause_turn
Tool runner (SDK)（Claude Platform Docs）: 自動のループ、@beta_tool、手動のループを使う場面
MCP connector（Claude Platform Docs）: mcp_servers と mcp_toolset、許可・拒否リスト、OAuth、Managed Agents の vault
Agent Skills（Claude Platform Docs）: 段階的な読み込み、用意されたスキルとカスタムスキル
Connect Claude Code to tools via MCP（Claude Code Docs）: claude mcp add、通信方式、範囲、${VAR}、リソースとプロンプトの使い方
Give Claude custom tools（Claude Code Docs、Agent SDK）: プロセス内の MCP サーバー、@tool / tool()、permission_policy
Extend Claude Code（Claude Code Docs）: CLAUDE.md・Skills・サブエージェント・MCP・フック・プラグインの使い分け、MCP と Skill の違い
Security（Claude Code Docs）: 信頼できる MCP サーバーを使う
Writing effective tools for AI agents（Anthropic Engineering）: ツールを増やしすぎない、search_contacts の例、結果の制限（25,000トークン）
MCP architecture overview（modelcontextprotocol.io） / Understanding MCP servers（modelcontextprotocol.io）: ホスト・クライアント・サーバー、JSON-RPC 2.0、stdio と Streamable HTTP、ツール・リソース・プロンプト、elicitation・sampling・logging

第2.1〜2.3節の一部は、MCP の公式サイト（modelcontextprotocol.io）にもとづきます。このサイトは MCP プロジェクトの公式の文書ですが、anthropic.com や claude.com のドメインではありません。第3.3節の選び方の表は、公式の説明を組み合わせたまとめです。内容は上の出典を要約・言い換えたものです（ライセンスに配慮して書き直しています）。