MCPサーバーのinstructionsとは?ツール検索で毎回読まれるMCPトークンと4,096文字の切り捨て、書き方を実測で解説【2026-07-28仕様】
MCPサーバーのinstructionsとは何か、2026-07-28仕様での場所(server/discover)、対応クライアント、トークン消費を解説。12ツールのサーバーで120対728トークンを実測し、Claude Codeの4,096文字の切り捨てを検証。Sonnet 5.5でのコスト試算、書き方のテンプレート、SDKのコード付き。
最終更新:2026年11月14日 / 対象:MCP仕様 2026-07-28(
server/discover)と 2025-11-25(initialize)、Claude CodeのMCPドキュメント(ツール検索・説明文の文字数上限)、MCP Python SDK 2.3.0、MCP TypeScript SDK 1.32.2、Claude Sonnet 5.5の料金、o200k_baseトークナイザー(gpt-tokenizer)
MCPサーバーの instructions(サーバー指示文)は、ツールが1つも読み込まれる前にサーバーがモデルへ渡せる唯一のテキストです。Claude Codeでツール検索が既定になった今、MCPのトークン消費の中で instructions が占める割合は、多くのサーバー作者が思っているより大きくなっています。この記事では、現行仕様で instructions がどこにあるか、どのクライアントが使うと明記しているか、何トークンかかるか、そしてツール検索の役に立つ書き方を、サンプルサーバーでの実測値と計算方法つきで解説します。
この記事の「トークン」はLLMのトークン(コンテキストと課金)のことで、APIキーやOAuthのアクセストークンのことではありません。
結論(30秒で読める要約)
- instructions は、サーバーがクライアントに渡す任意の自然文のガイドです。2026-07-28仕様では
server/discoverの結果に、2025-11-25以前はinitializeの結果に含まれます。 - ツール検索が有効なら、最初に払うトークンの大半は instructionsになります。Claude Codeのドキュメントには「セッション開始時に読み込まれるのはツール名とサーバーの instructions だけ」とあります。12ツールのサンプルサーバーでは、ツール名が124トークン、ツール定義の全体が1,426トークンでした(o200k_base)。
- 書き方で10倍近く変わります。 要点だけの551文字は120トークン、READMEを貼った3,079文字は728トークンで、ツール検索で節約したはずのツール定義の半分に相当しました。
- Claude Codeは4,096文字で切ります。 4,755文字の instructions で試すと、末尾に置いた「このサーバーを使う場面」の節がまるごと消えました。ツール検索にとって一番大事な部分です。
- クライアントの対応はまちまちです。使い方を明記しているのはClaude Codeだけで、VS Codeは対応機能として名前を挙げるのみ、Claude APIのMCPコネクタはツール呼び出しだけに対応しています。ツールを正しく呼ぶのに必要な情報は、instructions だけに書かないでください。
- 書くのは3つです。扱うタスクの種類、いつツールを検索すべきか、主な機能。インストール手順・認証・変更履歴・パラメータの説明は入れません。
目次
- MCPサーバーの instructions とは
- instructions の場所:2025-11-25と2026-07-28の違い
- instructions を使うクライアント
- 実測:instructions のトークン消費
- 4,096文字での切り捨てを試す
- Claude Sonnet 5.5でのコスト試算
- ツール検索に効く instructions の書き方
- Python・TypeScript SDKでの設定方法(動作確認済み)
- チェックリスト
- よくあるハマりどころ
- NodeFlareならこう解決できる
- FAQ
1. MCPサーバーの instructions とは
MCPサーバーの instructions とは、サーバー全体の使い方を説明するために、サーバーがクライアントへ返す任意の文字列です。2026-07-28仕様では「このサーバーを効果的に使う方法についての、LLM向けの任意の自然文ガイド(Optional natural-language guidance for LLMs on how to use this server effectively)」と定義されています。
ツールの説明文(description)は1ツールずつの説明です。instructions はサーバー全体の説明で、どの分野を扱うか、ツール同士がどう関係するか、モデルがいつそのツールを使うべきかを伝えます。このテキストをどう扱うかはクライアントが決めます。システムプロンプトに入れることも、ユーザーに表示することも、無視することもできます。
トークン消費の面で instructions が重要なのはこのためです。クライアントがプロンプトに入れる場合、instructions はセッション中のすべてのリクエストで入力トークンになります。遅延読み込みされないツール定義と同じ扱いです。
2. instructions の場所:2025-11-25と2026-07-28の違い
2026-07-28仕様でセッションのハンドシェイクがなくなったため、フィールドの置き場所が変わりました。中身と目的は同じです。
| 仕様のバージョン | instructions の場所 |
クライアントが受け取るタイミング |
|---|---|---|
| 2025-11-25以前(2026-07-28仕様では「レガシー」) | InitializeResult |
initialize ハンドシェイクで1回 |
| 2026-07-28 | server/discover の DiscoverResult |
クライアントが server/discover を呼んだとき。レスポンスはキャッシュに対応(仕様の例に ttlMs と cacheScope がある) |
2026-07-28仕様の server/discover のページから、押さえておきたい点が2つあります。
- サーバーは
server/discoverを実装しなければなりません(MUST)。ただし、クライアントが呼ぶかどうかは任意です。いきなりツールを呼ぶクライアントは、instructions を一度も受け取りません。 - stdioでは、新旧両方のサーバーに対応するクライアントは、最初に
server/discoverを送るべき(SHOULD)とされています。つまり instructions を受け取る可能性が一番高いのはstdioのクライアントです。
instructions は「クライアントが取りに来るかもしれないヒント」であって、必ずプロンプトに入るものではない、というのが実務上の結論です。
3. instructions を使うクライアント
instructions の扱いをドキュメントに書いているのはClaude Codeだけです。2026年11月14日時点で、各社の公式ドキュメントに書かれている内容をまとめます。
| クライアント・API | instructions についての記述 | トークン消費への影響 |
|---|---|---|
| Claude Code | 「セッション開始時に読み込まれるのはツール名とサーバーの instructions だけ」。instructions は「ツールをいつ検索すべきかをClaudeが理解する助けになる」。4,096文字で切り捨て | 毎リクエスト最初から読み込まれる(明記あり) |
| VS Code(Copilotのエージェントモード) | MCPの拡張機能ガイドの「VS Codeが対応するMCP機能」に「Server instructions」とあるだけで、詳細の説明はない | 対応はしているが、挙動は書かれていない |
| Claude APIのMCPコネクタ | 「現在対応しているのはツール呼び出しのみ」 | instructions を使うという記述はない |
| Cursor | MCPのドキュメントに記述なし | 不明 |
| OpenAI Responses API(MCPツール) | MCPのガイドに記述は見つからなかった | 不明 |
ここから言えることは2つです。Claude Codeのユーザー向けには、instructions はツール検索の精度を上げる一番安い手段です。一方で、必須のことを instructions だけに書いてはいけません。たとえば「confirm=true が必要」なら、どのクライアントでも送られるそのツールの説明文かスキーマに書きます。
4. 実測:instructions のトークン消費
サンプルサーバーでは、要点だけの instructions は120トークン、READMEを貼ったものは728トークンでした。ツール名12個は124トークンです。
計測方法(2026年11月14日):MCP TypeScript SDK 1.32.2で12ツールの「acme-orders」サーバー(注文・返金・返品・配送・顧客・在庫)を作り、インメモリ接続でツール一覧を取得して、各ツールの {name, description, input_schema} をo200k_baseでトークン化しました。ツール名はClaude Codeの mcp__server__tool 形式で1行に1つ並べて数え、起動時に読み込まれる量の近似としています。そのうえで instructions を3種類書いて、同じ方法で数えました。o200k_baseはClaudeのトークナイザーではないため、相対的な大きさとして読んでください。
| 最初に読み込まれるテキスト | 文字数 | トークン数(o200k_base) |
|---|---|---|
ツール名12個(mcp__acme-orders__…) |
— | 124 |
| ツール定義12個の全体 | — | 1,426 |
| instructions B:要点だけの3部構成(7章) | 551 | 120 |
| instructions C:READMEを貼ったもの(概要・インストール・認証・ツール一覧・使用例・レート制限・変更履歴・サポート) | 3,079 | 728 |
| instructions D:Cにパラメータ一覧と末尾の「このサーバーを使う場面」を足したもの | 4,755 | 1,126(先頭4,096文字では982) |
数字から分かること:
- ツール検索下では、instructions がほかの読み込み分を上回り得るということです。ツール名と要点だけの instructions で244トークン、ツール名とREADMEで852トークンでした。後者は、ツール検索で節約するはずだった1,426トークンの60%にあたります。
- READMEの内容の大半はモデルの役に立たないということです。インストール手順、APIキーの設定、変更履歴、問い合わせ先は、サーバーを設定する人間向けの情報で、モデルはセッション中にそれを使えません。
- instructions に書いたツール一覧は二重払いになります。Cは各ツールの用途を1行ずつ書いていますが、同じ内容はツールが読み込まれたときに説明文としても届きます。
大事なのは絶対値より比率です。ツールが60個あるサーバーならツール名のトークンは増えますが、同じREADMEは毎リクエスト700トークン以上かかり続けます。
5. 4,096文字での切り捨てを試す
Claude Codeは4,096文字を超える instructions を切り捨て、最後に書いた部分から消えていきます。Claude Codeのドキュメントには「上限を超えたツール説明文やサーバーの instructions は切り捨てられ、Claudeには切れ目より前のテキストしか見えない」とあります。「サーバーの instructions と、最初から読み込まれるツールの説明文」の上限は4,096文字で、v2.1.296より前は2,048文字でした。
instructions D では、多くのREADMEと同じ並びで、パラメータ一覧の後ろ、つまり末尾に「このサーバーを使う場面」の節(「注文番号や返金について聞かれたらこのツールを検索する…」)を置きました。この節は4,176文字目から始まります。4,096文字の切れ目はパラメータ一覧の途中にあたり、Claudeには設定とリファレンスの982トークンだけが届いて、使う場面の説明は1文字も届かない計算です。
| バージョン | 切れ目 | Claudeに見える範囲 |
|---|---|---|
| Claude Code v2.1.296以降 | 4,096文字 | 冒頭からパラメータ一覧の途中まで |
| Claude Code v2.1.296より前 | 2,048文字 | 冒頭からツール一覧の途中まで |
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192 |
8,192文字 | 全文。ただし設定はユーザーごとで、検索で読み込むツール説明文の上限(16,384文字)も下がる |
対策は上限を上げることではなく、並び順です。検索のきっかけになる説明を先頭に置き、全体を2,048文字より十分短くすれば、古いバージョンでも切れません。CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH を決めるのはユーザーで、サーバー作者ではありません。
なお、Anthropicが api.anthropic.com で提供している一部のMCPサーバーは全文がClaudeに届くとドキュメントにあるため、それらとの挙動の違いは比較の対象にしないでください。
6. Claude Sonnet 5.5でのコスト試算
1セッションあたりの instructions のコストは小さく、効いてくるのはチーム全体・サーバーの数で掛け算したときです。料金はAnthropicの料金ページにあるClaude Sonnet 5.5の値で、入力100万トークンあたり2ドル、5分キャッシュの書き込み2.50ドル、キャッシュヒット0.10ドルです。
前提:Claude Codeの1セッションを40リクエスト、1,000セッション分で計算します。最初に読み込むトークンは4章の「ツール名+instructions」(ツール検索あり)。「キャッシュあり」はセッションごとに1回書き込み、残り39リクエストはキャッシュから読む想定です。メッセージ、ツール結果、読み込んだツール、Claude自身のシステムプロンプトはどの行も同じなので除いています。
| 構成 | 1リクエストのトークン | 200Kウィンドウに占める割合 | 1,000セッション(キャッシュなし) | 1,000セッション(キャッシュあり) |
|---|---|---|---|---|
| A. ツール名のみ、instructions なし | 124 | 0.06% | $9.92 | $0.79 |
| B. ツール名+要点だけの instructions | 244 | 0.12% | $19.52 | $1.56 |
| C. ツール名+README型の instructions | 852 | 0.43% | $68.16 | $5.45 |
| D. ツール名+上限超えの instructions(残る部分) | 1,106 | 0.55% | $88.48 | $7.08 |
| E. ツール検索なし:ツール定義の全体+要点だけの instructions | 1,546 | 0.77% | $123.68 | $9.89 |
Cの行を手で検算すると、852 × 40 × 1,000 = 34,080,000トークン、34.08M × $2 ÷ 1M = $68.16です。キャッシュありは、1セッションあたり書き込み852 × $2.50/M = $0.00213と、ヒット39 × 852 × $0.10/M = $0.00332の合計$0.00545で、1,000セッションで$5.45になります。
読み方:
- この金額はサーバー1つあたりです。8つのサーバーを入れていて、どれもREADMEを instructions にしていれば、最初のメッセージの前に数千トークンの設定説明を抱えることになります。
- キャッシュで下がるのは料金で、コンテキストは減りません。 Cはどのリクエストでも同じだけウィンドウを占めます。また、デプロイで instructions の1語を変えるだけで、キャッシュされた先頭部分が無効になります。
- 本当のコストは精度です。Dは一番高いのに、肝心の部分が切れているため、ツール検索の助けにはほとんどなりません。
7. ツール検索に効く instructions の書き方
instructions は、モデルを正しいサーバーへ導く案内として、600文字以内で、検索のきっかけになる言葉を先頭に書きます。Claude Codeのドキュメントは次の3点を書くよう勧めています。扱うタスクの種類、Claudeがいつツールを検索すべきか、サーバーの主な機能です。
4章の instructions B(551文字、120トークン)がその例です。
Acme Orders: read and update orders, refunds and shipments in the Acme store.
Search these tools when the user asks about an order number (like A-12345), a customer's purchase history, a refund or return, a delivery or tracking number, or stock for a SKU.
Key capabilities: find orders by number, email or date range; issue full or partial refunds (needs confirm=true); create return labels; check stock per warehouse.
Not for: catalog edits or marketing emails (use the catalog server).
Results are paged (limit 20); pass fields to get fewer columns.
英語で書いているのは、英語のほうがトークンが少ないためです。日本語のユーザーが多いなら、「注文番号、返金、配送状況」のようなキーワードを1行足して、実際の質問で検索されるか試してください。
何をどこに書くか:
| 内容 | instructions | ツールの説明文・スキーマ | READMEだけ |
|---|---|---|---|
| 扱う分野とタスクの種類 | 書く | — | — |
| ユーザーが実際に使う言葉(注文番号、返金、追跡番号) | 先頭に書く | 説明文の冒頭にも書く | — |
| 対象外の範囲(「〇〇には使わない」、代わりのサーバー) | 書く | — | — |
| ツールをまたぐ流れ(検索してから取得) | 1行だけ | — | — |
必須パラメータや安全のためのフラグ(confirm=true) |
触れてもよい | 必ず書く | — |
| パラメータの説明 | 書かない | 書く | — |
| インストール、APIキー、環境変数 | 書かない | 書かない | 書く |
| 変更履歴、バージョン、問い合わせ先 | 書かない | 書かない | 書く |
| レート制限やリトライの挙動 | 書かない | モデルが対応する必要がある場合だけ | 書く |
計測から導いたルールは3つです。
- 検索される言葉を先に書く。 ツール検索はモデルの検索語とツールを照合し、instructions はモデルに「いつ探すか」を伝えます。ユーザーが実際に入力する名詞を最初の2行に入れてください。
- 全ツールを列挙しない。 ツール名は最初から読み込まれ、説明文はツールと一緒に読み込まれます。分野を1文で書くほうが、ツール一覧より安く、内容も古くなりません。
- デプロイをまたいで同じ文面にする。 プロンプトに instructions を入れるクライアントでは、キャッシュされる先頭部分に含まれます。バージョン番号や日付を入れると、リリースのたびにキャッシュが外れます。
8. Python・TypeScript SDKでの設定方法(動作確認済み)
どちらの公式SDKも、コンストラクタのオプションで instructions を渡せます。クライアント側からも、サーバーが送った内容を取得できます。2026年11月14日に、同じプロセス内でクライアントを接続して動作を確認しました。
Python(MCP Python SDK 2.3.0、MCPServer):
from mcp.server.mcpserver import MCPServer
INSTRUCTIONS = (
"Acme Orders: read and update orders, refunds and shipments in the Acme store.\n"
"Search these tools when the user asks about an order number, a refund or return, "
"a delivery or tracking number, or stock for a SKU."
)
server = MCPServer("acme-orders", instructions=INSTRUCTIONS)
@server.tool()
def get_order(order_id: str) -> str:
"""Get one order with line items, payments and fulfillments."""
...
SDKのプロセス内クライアント(async with Client(server) as c:)で、c.instructions に上の文字列が入っていました。
TypeScript(MCP TypeScript SDK 1.32.2):
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer(
{ name: "acme-orders", version: "1.0.0" },
{
instructions:
"Acme Orders: read and update orders, refunds and shipments in the Acme store. " +
"Search these tools when the user asks about an order number, a refund or return, " +
"a delivery or tracking number, or stock for a SKU.",
},
);
クライアント側では、connect() の後に client.getInstructions() で同じ文字列が返りました。
公開前に、4章と同じ方法で文字数とトークン数を確認できます。
// node count-instructions.mjs (事前に npm i gpt-tokenizer)
import { encode } from "gpt-tokenizer/encoding/o200k_base";
const text = process.env.MCP_INSTRUCTIONS ?? "";
console.log({ chars: text.length, tokens: encode(text).length,
overClaudeCodeLimit: text.length > 4096, overOldLimit: text.length > 2048 });
9. チェックリスト
- [ ] 扱うタスクの種類、ツールを検索すべき場面、主な機能が書かれている
- [ ] ユーザーが入力する言葉(注文番号、返金、追跡番号など)が最初の2行にある
- [ ] 全体が2,048文字未満で、できれば600文字以内
- [ ] インストール手順、認証、変更履歴、バージョン番号、問い合わせ先が入っていない
- [ ] ツールの全一覧やパラメータの説明が入っていない
- [ ] ツールを正しく呼ぶのに必要な情報は、そのツールの説明文かスキーマにもある
- [ ] デプロイのたびに文面が変わらず、プロンプトキャッシュが効く
- [ ] 8章のスクリプトで、編集の前後に計測した
- [ ] Claude Codeで、実際のユーザーの質問を使ってツール検索の挙動を確認した
10. よくあるハマりどころ
| 症状 | 原因 | 対処 |
|---|---|---|
| Claude Codeがツールを検索してくれない | 使う場面の説明がない、または4,096文字の切れ目より後ろにある | 「このツールを検索する場面」を最初の数行に書く |
| ツールの少ないサーバーを1つ足しただけで、最初のコンテキストが増えた | READMEを instructions に貼っている |
設定の説明はREADMEへ移し、案内だけを残す |
| リリースのたびにキャッシュヒット率が下がる | instructions にバージョンや日付が入っている | 文面を固定する |
| VS Codeなどで必須フラグが無視される | instructions にしか書いていない | ツールの説明文とスキーマに書く |
| Claude APIで instructions が効かない | MCPコネクタはツール呼び出しにしか対応していない | 自分のシステムプロンプトかツールの説明文に書く |
| Claude Codeのバージョンによって挙動が違う | v2.1.296より前は上限が2,048文字 | 2,048文字未満に収める |
| 他人のサーバーの instructions でモデルの挙動がおかしくなる | instructions もツール説明文と同じく、サーバーから届く信頼できないテキスト | 導入前に中身を確認する |
最後の行について補足します。instructions はツール説明文と同じ経路でモデルに届くため、悪意のあるサーバーや乗っ取られたサーバーはプロンプトインジェクションに使えます。サーバーを導入する前の確認では instructions も読んでください(MCPのツールポイズニング対策を参照)。
11. NodeFlareならこう解決できる
NodeFlareはMCPに特化したホスティングで、GitHubリポジトリのMCPサーバーを認証つきのHTTPSエンドポイントとして動かします。プロキシにはトークン消費を抑える4つのスイッチがサーバーごとにあり、どれもサーバーのコードを変えずに使えます。この記事で挙げた課題に当てはめると、次のとおりです。
課題1:ツール検索のないクライアントでは、全ツール定義を毎回払う(6章のE)。instructions が役に立つのは、ツールを遅延読み込みするクライアントだけです。tool_search_mode を有効にすると、NodeFlareが tools/list を search_tools(query) と call_tool(name, args) の2つのメタツールにまとめるため、サーバーのツールがいくつあっても最初のコストはほぼ一定になり、どのクライアントでも使えます。検索は既定では字句検索で、GEMINI_API_KEY を設定するとセマンティック検索になり、失敗したときは字句検索に戻ります。7章のようにキーワードを先頭に置いた説明文は、どちらの検索にも効きます。
課題2:instructions で説明しようとしている複数手順の流れ(Cの「search_orders の後に get_shipment を呼ぶ」など)。Code Execution(tool_code_mode)を有効にすると、サーバーは run_code と search_tools を公開します。モデルは tools.NAME(args) を呼ぶJavaScriptを書き、たとえば「注文を検索し、3件を読み、それぞれの配送状況を確認する」までを1回のコード実行にまとめ、NodeFlareがサンドボックスで実行します。会話に戻るのはスクリプトが返した結果だけなので、途中の一覧はコンテキストに入りません。実行は隔離されたDenoのサブプロセスで行われ、ファイルシステム・環境変数・プロセスの起動は使えず、ネットワークはプロキシのコールバック先に限られます。既定値はタイムアウト600秒(変更可)、1回の実行で最大50回のツール呼び出し、V8ヒープ128MBで、ツール呼び出しのたびに権限が確認されます。
課題3:instructions やツール一覧に、呼び出し元が使えないツールが含まれる。返金の権限がないサポート用エージェントにも、create_refund とそのスキーマが見えてしまいます。tool_list_filter_by_scope を有効にすると、tools/list は呼び出し元のNodeFlareの認証情報で呼べるツールだけを返します(スキーマはそのまま)。instructions を分野単位の説明(7章)にしておけば、絞り込まれたどの一覧に対しても内容が正しいままです。
課題4:instructions から移したパラメータの説明で、ツール説明文が長くなる。7章のとおりパラメータの説明をツール説明文に移したときは、tool_schema_slim が500文字を超えるツール説明文を切り詰めます(UTF-8で文字が壊れないように切り、ツール名と入力スキーマは変えません)。対象はツール説明文で、サーバーの instructions ではないため、instructions は自分で短く保ってください。
NodeFlareはこれらのスイッチによる削減率を公表していません。4章と8章のスクリプトで、自分のサーバーで計測してください。
最小の始め方:
- NodeFlareのダッシュボードで、MCPサーバーのGitHub URLを貼ります。ランタイム、トランスポート、起動コマンドは自動で検出・入力されます。
- デプロイして、
tool_code_modeを有効にします(必要に応じてtool_search_modeやtool_list_filter_by_scopeも)。 - クライアントに
https://<your-server>.nodeflare.tech/mcpとAuthorization: Bearer <NodeFlareのAPIキー>を設定します。
MCPサーバー1つまで無料で試せます(Freeプラン:サーバー1つ、月30 GB時間のコンピュート)。→ nodeflare.techで始める
12. FAQ
MCPサーバーの instructions とは何ですか?
サーバー全体の使い方を伝えるために、サーバーがクライアントへ返す任意のテキストです。2026-07-28仕様では「このサーバーを効果的に使う方法についての、LLM向けの任意の自然文ガイド」と定義されています。モデルのコンテキストに入れるかどうかはクライアントが決めます。
2026-07-28仕様では instructions はどこにありますか?
initialize ハンドシェイクに代わる server/discover の結果に含まれます。2025-11-25以前の仕様では InitializeResult にあります。クライアントは server/discover を呼ばなくてもよいため、instructions を受け取らない場合もあります。
MCPサーバーの instructions はトークンを消費しますか?
プロンプトに入れるクライアントでは、セッション中の毎リクエストで消費します。サンプルサーバーでは、要点だけの instructions が120トークン、READMEを貼ったものが728トークンでした(o200k_base)。同じサーバーのツール名12個は124トークンです。
Claude CodeはMCPサーバーの instructions を読み込みますか?
読み込みます。ドキュメントには、ツール検索では「セッション開始時に読み込まれるのはツール名とサーバーの instructions だけ」とあり、instructions はClaudeがツールを検索すべき場面を理解する助けになると書かれています。
Claude Codeで instructions は何文字まで書けますか?
v2.1.296以降は4,096文字、それより前は2,048文字です。上限を超えた部分は切り捨てられ、Claudeには届きません。ユーザーは CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH で上限を変えられますが、サーバー作者は変えられません。
instructions には何を書けばよいですか?
サーバーが扱うタスクの種類、モデルがツールを検索すべき場面、主な機能の3つです。ユーザーが実際に使う言葉を先頭近くに置きます。近い分野を別のサーバーが扱う場合は、対象外の範囲も書きます。
instructions に書かないほうがよいことは何ですか?
インストール手順、認証、環境変数、変更履歴、バージョン番号、問い合わせ先、ツールの全一覧、パラメータの説明です。毎リクエストでトークンを消費するうえ、モデルはそれを使えません。
すべてのMCPクライアントが instructions を使いますか?
少なくともドキュメント上はそうではありません。Claude Codeは挙動を明記し、VS Codeは対応機能として名前を挙げるだけで、Claude APIのMCPコネクタはツール呼び出しにしか対応していません。CursorとOpenAIのMCPドキュメントには記述が見つかりませんでした。
instructions とツールの説明文はどう使い分けますか?
役割が違うので両方使います。instructions はモデルをサーバーへ導き、説明文は各ツールを説明します。ツールを正しく呼ぶために必要な情報は、どのクライアントでも送られる説明文かスキーマに書きます。
PythonやTypeScriptのSDKで instructions を設定するには?
Python SDK 2.3.0では MCPServer に instructions= を渡します。TypeScript SDK 1.32.2では new McpServer(...) の2つ目の引数に { instructions } を渡します。クライアント側では、Pythonは instructions、TypeScriptは getInstructions() で取得できます。
この記事の「MCPトークン」はAPIトークンのことですか?
違います。この記事が扱うのは、コンテキストウィンドウと課金の単位であるLLMのトークンです。MCPサーバーのAPIキーやOAuthのアクセストークンは、セキュリティの話題です。
まとめ
MCPサーバーの instructions は、クライアントが毎リクエストに読み込むことがある、サーバー単位の短い案内です。ツール検索のもとでは、Claude Codeで最初に払うコストの大部分を占めます。案内として書けば120トークン、READMEを貼れば728トークンで、ツール名12個の124トークンと比べると差は明らかです。Claude Codeは4,096文字(古いバージョンは2,048文字)で切るため、検索のきっかけになる言葉を先頭に置き、全体を短く保ってください。設定手順や変更履歴、パラメータの説明は入れず、ツールに必要な情報はそのツールの説明文に書きます。すべてのクライアントが instructions を使うわけではないからです。ツール定義そのものを削る方法はツール定義の監査とスリム化、クライアントごとのツールの読み込み方はMCPツールはいくつまで?で解説しています。
