記事一覧
MCPトークン

失敗したMCPツール呼び出しはなぜトークンを食うのか:エラー文とリトライのMCP Tokenコストを2つのSDKで実測【2026年版】

MCPのツール呼び出しが失敗すると何トークン増えるのか。2026-07-28版仕様のプロトコルエラーとisErrorの違い、TypeScript SDK 1.32.2とPython SDK 2.3.0が不正な入力や例外のときに返す内容の実測、Claude Sonnet 5.5での7パターンの試算、リトライを止めるエラー文の書き方、strict tool use、リトライの上限設定をまとめました。

最終更新:2026年11月4日 / 対象:MCP仕様 2026-07-28(ツールのエラー処理)、MCP TypeScript SDK 1.32.2、MCP Python SDK 2.3.0(MCPServer)、Claude APIのツール利用とClaude Sonnet 5.5の料金

MCPのトークン消費(MCP Token)を減らす話は、たいてい成功したときの話です。ツール定義を短くする、結果を小さくする、といったものです。一方で、ツール呼び出しが失敗したときのコストはあまり語られません。失敗するとモデルのターンが1回増え、エージェントのループではそのたびにコンテキスト全体が読み直されます。

この記事では、公式のMCP SDK 2つが失敗時に実際に何をモデルへ返すのかを測り、7つの失敗パターンをClaude Sonnet 5.5の料金で計算します。そのうえで、リトライの連鎖を止めるためにサーバー側とクライアント側でできることをまとめます。

注:ここでいう「トークン」はLLMのトークン(コンテキストと課金)のことで、APIキーやOAuthのアクセストークンではありません。

結論(30秒で読める要約)

  • MCPのツール呼び出しが1回失敗すると、増えるのはエラー文だけではなく1ターン分まるごとです。 私の試算(コンテキスト30,000トークン、その後15ターン、Sonnet 5.5でキャッシュなし)では、1回目のリトライで直る失敗でも入力が約33,000トークン増えます。3回やみくもにリトライすると約98,000〜134,000トークン増えます。
  • エラー文の長さより、リトライの回数の方が効きます。 720トークンのPythonのトレースバックで3回リトライすると0.271ドル、5トークンの中身のないエラーで3回リトライしても0.198ドルでした。直し方が書かれた70トークンのエラーで1回で直れば0.068ドルです。
  • MCPの仕様も「モデルが対処できるエラー」を求めています。 2026-07-28版の仕様では、ツール実行エラーは「モデルが自分で修正するための具体的な手がかり」を含むものとされ、クライアントはそれをモデルに渡すべき(SHOULD)とされています。
  • 2つのSDKで返し方が違います。 TypeScript SDK 1.32.2は4つの不正な引数を1つのメッセージにまとめて76トークンで返しました。Python SDK 2.3.0は同じ入力にpydanticの出力を243トークン返し、通常の例外は「Error executing tool search_orders」(5トークン)だけにして中身を隠しました。
  • 対策は3つの層で行います。 次に何をすべきか(「リトライしない」も含む)を書いたエラーを返す、呼び出す前に不正な入力を防ぐ(スキーマ、Claude APIの strict: true)、エージェントのループでリトライ回数に上限を設ける、の3つです。

目次

  1. 失敗したツール呼び出しのMCP Tokenコストとは
  2. MCP仕様のプロトコルエラーとツール実行エラー
  3. 実測:TypeScript SDKとPython SDKは失敗時にモデルへ何を返すか
  4. 試算:Claude Sonnet 5.5での7つの失敗パターン
  5. リトライの連鎖を止めるエラー文の書き方
  6. そもそも不正な呼び出しをさせない
  7. 自作のエージェントでリトライに上限を設ける
  8. チェックリスト
  9. よくあるハマりどころ
  10. NodeFlareならこう解決できる
  11. よくある質問

1. 失敗したツール呼び出しのMCP Tokenコストとは

失敗したMCPツール呼び出しのトークンコストとは、その失敗によってセッションに増えるトークンの合計です。失敗した呼び出しの出力、エラーの結果、コンテキスト全体を読み直す追加のターン、そして失敗した呼び出しとエラーがその後のターンでも毎回読み直される分が含まれます。画面で目に入るのはエラー文だけですが、高くつくのは追加のターンの方です。

内訳 課金の種類 何に比例して増えるか
失敗した tool_use(引数と推論) 出力 引数の大きさ、思考
エラーの結果(isError: true) 入力 エラー文の長さ
追加のモデルのターン 入力(コンテキスト全体)+出力 その時点のコンテキストの大きさ
履歴に残る失敗した呼び出しとエラー その後の毎ターンの入力 その後のターン数

Anthropicのツール利用のドキュメントには、このループがそのまま書かれています。「ツールのリクエストが不正だったりパラメータが足りなかったりすると、Claudeは修正しながら2〜3回リトライし、それでもだめならユーザーに謝ります」(原文:If a tool request is invalid or missing parameters, Claude will retry 2–3 times with corrections before apologizing to the user.)。このリトライの1回1回が、まるごと1ターンです。

2. MCP仕様のプロトコルエラーとツール実行エラー

現行のMCP仕様(2026-07-28版)は、ツールのエラーを2種類に分けています。モデルに届けることを想定しているのは、そのうちの片方だけです。

プロトコルエラー ツール実行エラー
返し方 通常のJSON-RPCエラー(例:コード -32602) isError: true のツール結果
仕様の例 存在しないツール、形式が不正なリクエスト、サーバーエラー APIの失敗、入力の検証エラー、業務ロジックのエラー
クライアントの扱い モデルに渡してもよい(MAY) 自己修正のためにモデルに渡すべき(SHOULD)
仕様の位置づけ モデルが直せる可能性は低い モデルが自分で修正し、引数を変えてリトライするための手がかり

入力の検証エラー(仕様の例では「日付の形式が違う」「値が範囲外」)は右側に入ります。2025-11-25版の変更履歴で、「入力の検証エラーは、モデルが自己修正できるよう、プロトコルエラーではなくツール実行エラーとして返す」ことが明確になりました(SEP-1303)。

トークンの観点では、ここから2つのことが言えます。

  • モデルに見えないエラーは、やみくもなリトライを生みます。 クライアントがプロトコルエラーをモデルに渡さない場合、モデルには「失敗した」ことしか分かりません。
  • モデルに見えるエラーも、何を変えればよいかが書かれていなければ役に立ちません。 「failed」とだけ返しても、モデルは当て推量で呼び直します。

3. 実測:TypeScript SDKとPython SDKは失敗時にモデルへ何を返すか

多くのMCPサーバーは自分でエラー文を書いていないので、失敗時に何が返るかは公式SDKで決まります。同じツールに同じ不正な入力を与えて、両方のSDKを試しました。

方法(2026年11月4日):制約のある4つのパラメータ(customer_id は ^cus_[a-z0-9]{8}$ に一致、status は open/shipped/cancelled のいずれか、since は日付、limit は1〜100)を持つ search_orders というツールを1つ用意しました。各SDKのクライアントからプロセス内で、①4つとも不正な引数、②正しい引数でハンドラが例外を投げる、③ツール名のつづり間違い、の3通りで呼びました。トークン数は、モデルが受け取るテキストをo200k_baseのトークナイザー(gpt-tokenizer 4.1.0)で数えたものです。Claudeのトークナイザーでは絶対値が変わるので、比で見てください。

ケース TypeScript SDK 1.32.2 Python SDK 2.3.0
不正な引数が4つ isError: true、4つの問題をすべて列挙、76トークン isError: true、4つの問題をpydanticの詳細とドキュメントのURL付きで列挙、243トークン
ハンドラが Error("upstream 500: connect ECONNREFUSED ...") を投げる isError: true、例外のメッセージ、21トークン isError: true、「Error executing tool search_orders」だけ、5トークン
存在しないツール名(search_order) isError: true、「MCP error -32602: Tool search_order not found」、12トークン isError: true、「Unknown tool: search_order」、5トークン

ここから分かること:

  • どちらのSDKも、不正な引数をまとめて全部返します。 これはトークンの面で有利です。モデルは4つを1回のリトライで直せるので、1ターンに1つずつ直す必要がありません。
  • Pythonの検証エラーは3.2倍長くなります。 pydanticの型コード、入力値、項目ごとの https://errors.pydantic.dev/... へのリンクが入るためです。モデルにリンクは要りません。
  • Pythonは想定外の例外を意図的に隠します。 SDKの ToolError のdocstringには、それ以外の例外は「クラッシュとして扱われ、モデルには Error executing tool <name> だけが見える」と書かれています。内部情報の漏えいは防げますが、モデルには入力ミスなのか障害なのかが分からないので、リトライしがちです。想定している失敗は、メッセージ付きの ToolError で返しましょう。
  • 存在しないツールは、どちらのSDKでもJSON-RPCエラーではなくツール結果として返りました。 少なくともこのバージョンでは、クライアントがプロトコルエラーを渡さない設定でも、モデルには見えます。

比較のため、サーバーがそのまま返してしまいがちなものも数えました。

エラーの中身 o200kトークン
接続拒否で出たPythonのトレースバック(traceback.format_exc()、54行) 720
上流が返したインラインCSS付きのHTML「502 Bad Gateway」ページ 283
書き直した検証エラー(4項目すべて、今日の日付つき) 70
書き直した上流エラー(「今はリトライしない」つき) 27
書き直した存在しないツールのエラー(候補の提示つき) 13

4. 試算:Claude Sonnet 5.5での7つの失敗パターン

失敗のコストの大部分は、コンテキスト全体を読み直す追加のターンです。エラー文の長さは2番目の要素にすぎません。以下は実測ではなく私の計算です。

前提:失敗した時点のコンテキストC=30,000トークン(ツール定義と履歴)、1回の呼び出しの出力O=120トークン、ツール結果1件あたりの包みW=20トークン、失敗の後にR=15ターン続く、失敗した結果はすべて履歴に残る、とします。料金はAnthropicの料金ページにあるClaude Sonnet 5.5の値で、入力が100万トークンあたり2ドル、出力が10ドル、キャッシュヒットが0.10ドル、5分キャッシュの書き込みが2.50ドルです。

失敗の回数をf、エラー文の長さをEとすると:

  • 追加の入力 = f × C + (O + E + W) × (f(f+1)/2 + R × f)
  • 追加の出力 = f × O
  • キャッシュなしの料金 = 追加の入力 × 2ドル/100万 + 追加の出力 × 10ドル/100万
  • キャッシュありの料金:前の部分の読み直しと以降の読み直しは0.10ドル/100万、新しく増える (O + E + W) は1回だけ2.50ドル/100万で書き込み、出力は10ドル/100万
失敗パターン 失敗の回数(f) 追加の入力トークン 追加の出力トークン キャッシュなし キャッシュあり
Pythonのトレースバックをそのまま返し、3回やみくもにリトライ 3 133,860 360 $0.2713 $0.0232
上流のHTMLの502ページを返し、3回やみくもにリトライ 3 111,573 360 $0.2267 $0.0178
Python SDKの中身のない「Error executing tool」で3回リトライ 3 97,395 360 $0.1984 $0.0144
Python SDKのpydanticの検証エラー、1回目のリトライで修正 1 36,128 120 $0.0735 $0.0057
TypeScript SDKの検証エラー、1回目のリトライで修正 1 33,456 120 $0.0681 $0.0051
書き直した検証エラー、1回目のリトライで修正 1 33,360 120 $0.0679 $0.0050
書き直した上流エラー(「今はリトライしない」)で止まる 1 32,672 120 $0.0665 $0.0049

1行だけ手で確かめます。TypeScriptの行はf=1、E=76なので、O+E+W=216です。追加の入力は30,000+216×(1+15)=33,456。キャッシュなしの料金は33,456×2÷1,000,000+120×10÷1,000,000=0.0669+0.0012=0.0681ドルです。

読み方:

  • 効いているのはリトライの回数です。 f × Cの項は、追加のターン1回につき30,000トークンです。3回リトライする行は、エラー文の長さに関係なく、1回で直る行のおよそ3〜4倍になります。
  • 短いエラーが良いエラーとは限りません。 5トークンの中身のないエラーは1回あたりは安いものの、やみくもなリトライを招きます。この試算では、1回で直る70トークンのエラーの2.9倍かかりました。
  • 長いセッションでは、エラー文の長さも効いてきます。 トレースバックの行が中身のないエラーの行より0.073ドル高いのは、715トークン多い分がその後の15ターンで読み直されるからです。ターン数や失敗の回数が増えるほど、差は広がります。
  • キャッシュで料金は下がっても、傾向は変わりません。 キャッシュありでも、トレースバックで3回リトライする行は、書き直したエラーの行の4.6倍です。また、キャッシュはコンテキストの空きには効かないので、失敗した呼び出しは場所を取り続けます。
  • 規模で見ると: 10回に1回のセッションでこうした失敗が1回起きるとすると、10,000セッションで1,000回です。トレースバックとやみくもなリトライなら約271ドル、ループを止めるエラーなら約67ドルです(いずれもキャッシュなし)。

5. リトライの連鎖を止めるエラー文の書き方

MCPのエラー文は、モデルに次の3つのどれをすべきかを伝えるものにします。引数を直す、先に別のものを呼ぶ、止める、の3つです。Anthropicのツール利用のドキュメントも、「failed」のような汎用のエラーではなく、何が起きたかと次に何を試すべきかを書くよう勧めています。エージェント向けのツール設計についてのエンジニアリング記事でも、エラーの応答は、意味の分からないエラーコードやトレースバックではなく、具体的で対処できる改善点を伝えるべきだとしています。

エラーの種類 書くこと 例
引数の誤り 不正な項目すべて、期待する形式、受け取った値、モデルが知らない情報(今日の日付など) since must be YYYY-MM-DD (got "last week"; today is 2026-11-04)
前提が足りない 先に使うべきツールや入力 No customer cus_abcd1234. Call find_customer with an email or name first.
上流の一時的な障害 一時的であること、今リトライすべきか Orders API is temporarily unavailable (HTTP 502). Do not retry now; tell the user and try again in about 30 seconds.
権限・上限 リトライしても無駄であること This key cannot call delete_order. Do not retry; ask the user to grant access.
想定外のバグ 短いメッセージと「止める」指示。スタックトレースはログへ search_orders failed for an unexpected reason. Do not retry; report it to the user.

例文を英語のままにしているのは、モデルへの指示はツールの説明と同じ言語で揃える方が扱いやすいためです。日本語で書いても構いません。

TypeScript(MCP TypeScript SDK 1.32.2)。生の例外をそのまま流さず、自分で書いたテキストに isError: true を付けて返します。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "orders", version: "1.0.0" });
const fail = (text: string) => ({ content: [{ type: "text" as const, text }], isError: true });

// fetchOrders と UpstreamError は自分のAPIクライアントのコード
server.registerTool("search_orders", {
  description: "Search a customer's orders created on or after `since` (YYYY-MM-DD).",
  inputSchema: {
    customer_id: z.string().regex(/^cus_[a-z0-9]{8}$/),
    since: z.string().date(),
  },
}, async ({ customer_id, since }) => {
  try {
    const orders = await fetchOrders(customer_id, since);
    return { content: [{ type: "text", text: JSON.stringify(orders) }] };
  } catch (err) {
    if (err instanceof UpstreamError && err.status >= 500) {
      return fail(`Orders API is temporarily unavailable (HTTP ${err.status}). ` +
                  "Do not retry now; tell the user and try again in about 30 seconds.");
    }
    if (err instanceof UpstreamError && err.status === 404) {
      return fail(`No customer ${customer_id}. Call find_customer with an email or name first.`);
    }
    console.error(err); // 詳細はモデルではなくログへ
    return fail("search_orders failed for an unexpected reason. Do not retry; report it to the user.");
  }
});

Python(MCP Python SDK 2.3.0。FastMCP は MCPServer に名前が変わりました)。想定している失敗は ToolError で投げます。メッセージは「Error executing tool search_orders: 」の後ろに付いて、is_error=True でモデルに届きます。

from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("orders")

# call_orders_api と UpstreamDown は自分のAPIクライアントのコード
@mcp.tool()
def search_orders(customer_id: str, since: str) -> str:
    """Search a customer's orders created on or after `since` (YYYY-MM-DD)."""
    try:
        return call_orders_api(customer_id, since)
    except UpstreamDown:
        raise ToolError(
            "Orders API is temporarily unavailable (HTTP 502). "
            "Do not retry now; tell the user and try again in about 30 seconds."
        )

どちらも各SDKのクライアントから実際に呼び、上のメッセージが isError 付きで返ることを確かめました。

6. そもそも不正な呼び出しをさせない

一番安い失敗は、起きない失敗です。サーバー側から順に4つの手があります。

  • ルールをスキーマに持たせる。 inputSchema にパターン、列挙値、最小・最大を書いておけば、呼び出す前にクライアントやモデルが制約を知ることができます。説明文にも形式(「YYYY-MM-DD」など)を短く書きます。制約を残したまま定義を削る方法は、ツール定義の棚卸しの記事で扱っています。
  • 意味が一つに決まるなら、モデルが送りがちな形を受け入れる。 モデルが何度も "limit": "10" と送ってくるなら、数字の文字列を数値に変換する方が、エラーで1ターン使うより安く済みます。
  • APIを自分で呼ぶ部分ではstrict tool useを使う。 Claude APIでは、ツール定義に strict: true を付けると、Claudeのツール入力がJSON Schemaに必ず一致するようになります。自作のエージェントがMCPのツールをClaude APIのツール定義として渡す場合に使えます。存在しない顧客IDのような意味の誤りは防げません。どのスキーマ機能に対応しているかは、strict tool useのドキュメントで確認してください。
  • 呼び出し元が使えないツールは見せない。 認証情報で呼べないツールが一覧にあると、権限エラーを誘うだけです。その呼び出し元向けの tools/list から外します。

7. 自作のエージェントでリトライに上限を設ける

エージェントのループを自分で書いているなら、ツールごとに連続した失敗の回数を数え、しつこいエラーでセッションを使い切らないようにします。次のスケッチは失敗を数え、2回目からは結果のテキストを「止める」指示に置き換えます。

MAX_FAILS_PER_TOOL = 2
fails: dict[str, int] = {}

def to_tool_result(tool_use_id: str, name: str, mcp_result) -> dict:
    text = "".join(c.text for c in mcp_result.content if c.type == "text")
    if mcp_result.is_error:
        fails[name] = fails.get(name, 0) + 1
        if fails[name] >= MAX_FAILS_PER_TOOL:
            text = (f"{name} has failed {fails[name]} times in this session. "
                    "Do not call it again; explain the problem to the user.")
        text = text[:1000]  # エラーでコンテキストをあふれさせない
    else:
        fails[name] = 0
    return {"type": "tool_result", "tool_use_id": tool_use_id,
            "content": text, "is_error": bool(mcp_result.is_error)}

クライアント側では、ほかに2つの設定が同じように効きます。1つはツール結果ごとのサイズの上限です(Anthropicの記事には、Claude Codeではツールの応答を既定で25,000トークンに制限しているとあります)。もう1つは、ツール一覧を変えずに保ち、追加のターンでもプロンプトキャッシュに当たるようにすることです。成功したときの結果が大きい場合は、MCPツールの応答を小さくする方法を参照してください。

8. チェックリスト

  • [ ] 入力の検証エラーを、JSON-RPCエラーではなく isError: true の結果で返している
  • [ ] 検証エラーは、不正な項目すべてを期待する形式つきでまとめて返している
  • [ ] 一時的な障害では今リトライすべきかを書き、権限・上限のエラーでは「リトライしない」と書いている
  • [ ] スタックトレース、HTMLページ、上流の生のレスポンスをモデルに返していない
  • [ ] Pythonのサーバーでは、想定している失敗を通常の例外ではなく ToolError で返している
  • [ ] スキーマにパターン、列挙値、範囲を書き、説明文には形式を短く書いている
  • [ ] 自作のエージェントがClaude APIを直接呼ぶ部分では strict: true を付けている
  • [ ] エージェントのループで、ツールごとの連続失敗に上限を設け、エラー文を切り詰めている
  • [ ] 呼び出しごとにツール名、結果、エラー文を記録し、失敗の多いツールを見直している

9. よくあるハマりどころ

症状 原因 対処
同じツールを同じ引数で3回呼ぶ エラーに何を変えるべきかが書かれていない、または中身がない 直すべき点か「リトライしない」を書く
障害中もモデルが呼び続ける 一時的な障害が引数の誤りと区別できない 一時的であることと、いつリトライすべきかを書く
エラー1回で数百トークン増える トレースバックやHTMLページをそのまま返している 詳細はサーバーのログに残し、返すのは1〜2文にする
Pythonのサーバーが常に「Error executing tool X」と返す SDKが通常の例外をクラッシュとして扱っている 対処方法を書いた ToolError を投げる
検証エラーを1ターンに1項目ずつ直している サーバーが最初の不正な項目で止まっている すべて検証し、問題をまとめて返す
「permission denied」の呼び出しが続く 使えない呼び出し元にもツールが見えている 呼び出し元の権限で tools/list を絞る
セッションが長くなるほどリトライが高くつく 追加のターンのたびにコンテキスト全体を読み直す リトライに上限を設け、コンテキストを小さく保ってキャッシュさせる

10. NodeFlareならこう解決できる

NodeFlareは、GitHubのリポジトリからMCPサーバーをホスティングし、サーバーごとの4つのトークン設定をプロキシ側で適用します。サーバーのコードを変える必要はありません。ここまでの課題にどう対応するかを順に説明します。

課題1:リトライのたびにモデルのターンが1回増える(4章)

Code Execution(tool_code_mode)を有効にします。サーバーは run_code と search_tools を公開し、モデルは tools.* を呼ぶJavaScriptを書き、NodeFlareがそれをサンドボックスで実行します。NodeFlareのドキュメントによると、ツールのエラーはモデルが同じ実行の中でcatchしてリトライできるようラップされ、最後の戻り値だけが run_code の結果として返ります。つまり、待ってから呼び直す、引数を直して呼び直す、といったリトライが、モデルのターンではなくコードの中で済みます。

実行はそれぞれ隔離されたDenoのサブプロセスで行われ、ファイルシステム・環境変数・サブプロセスの生成はなく、ネットワークはプロキシのコールバック先に限られます。既定ではタイムアウト600秒、1回の実行あたり最大50回のツール呼び出し、V8ヒープ128MBです。

例(4章の前提での私の計算で、NodeFlareの計測値ではありません):120トークンの呼び出しの代わりにモデルが300トークンのコードを書き、その中で3回の失敗を吸収した場合、追加のターンはゼロです。増えるのは出力約180トークンと、長くなったコードをその後15ターンで読み直す入力約2,700トークンで、3回のリトライのターンにかかる97,000〜134,000トークンと比べてずっと少なくなります。ただし、モデルがリトライや代替の処理をコードに書いた場合に限るので、使うモデルが何を生成するかは確かめてください。Code Executionがどんな場面で得になるかは、MCPのCode Executionと直接のツール呼び出しの比較で詳しく扱っています。

課題2:リトライのたびに大きなコンテキストを読み直す(4章のf × Cの項)

tool_search_mode を有効にすると、tools/list が search_tools(query) と call_tool(name, args) の2つのメタツールにまとめられ、ツールが増えてもCのうちツール定義の分は小さいままです。検索は既定では字句一致で、GEMINI_API_KEY を設定すると意味検索になり、埋め込みに失敗したときは字句検索に戻ります。あわせて tool_schema_slim を使うと、500文字を超える説明文を切り詰めます(名前と入力スキーマはそのままです)。Cが小さくなれば、残るリトライも1回ずつ安くなります。

課題3:呼び出し元が使えないツールを呼んでしまう(6章・9章)

tool_list_filter_by_scope を有効にし、エージェントごとに tools:call:search_orders のようなスコープを付けたAPIキーを渡します。tools/list はそのキーで呼べるツールだけを、スキーマはそのままで返します。スコープ外の呼び出しが来た場合は、プロキシがJSON-RPCエラーで拒否し、サーバーには届きません。Code Executionの中からの呼び出しも、1回ごとに再確認されます。

課題4:どのツールが失敗しているか分からない(チェックリスト)

ログ画面には、リクエストごとに tool_name、outcome(ok、scope_denied、rate_limited など)、http_status、duration_ms、error_message が記録されます。引数の値は記録されません。ツールと結果で並べれば、先に書き直すべきエラー文が分かります(保存期間はFreeが7日、ProとTeamが30日)。呼び出しごとに何を記録すべきかは、MCPの監査ログを参照してください。

NodeFlareは固定の削減率を公表していません。各設定の前後で、自分のセッションを測って比べてください。

最小の始め方:

  1. nodeflare.techにサインインし、MCPサーバーのGitHub URLを入力します。ランタイム、トランスポート、起動コマンドは自動で判定・入力されます。
  2. デプロイしたら tool_code_mode を有効にします(必要に応じて tool_list_filter_by_scope や tool_search_mode も)。
  3. MCPクライアントにサーバーのURLとAPIキーを設定します。クライアントごとの書き方はリモートMCPクライアント設定の早見表を参照してください。

MCPサーバー1つまでは無料で試せます(Freeプラン:1サーバー、月30 GB-hoursのコンピュート)。→ nodeflare.techで始める

11. よくある質問

失敗したMCPツール呼び出しもトークンを消費しますか?

消費します。失敗した呼び出しの引数は出力トークン、エラーは入力トークンになり、リトライはコンテキスト全体を読み直す追加のターンになります。コンテキスト30,000トークンでの私の試算では、1回目のリトライで直る失敗1回で入力が約33,000トークン増えました。

MCPサーバーはエラーをどう返すべきですか?

入力の検証、APIの失敗、業務ロジックのエラーは、isError: true のツール結果として返し、モデルに見えるようにします。2026-07-28版の仕様では、JSON-RPCのプロトコルエラーは存在しないツール、不正な形式のリクエスト、サーバーエラー用で、クライアントはそれをモデルに渡してもよい(MAY)とされているだけです。

MCPの isError とJSON-RPCエラーの違いは?

isError: true は通常の結果の中でツール実行エラーを示すもので、クライアントは自己修正のためにモデルへ渡すべき(SHOULD)とされています。JSON-RPCエラーはリクエスト自体が失敗したことを示し、モデルに見せないクライアントもあります。トークンの面では、モデルに見えないエラーはやみくもなリトライにつながりがちです。

Claudeは失敗したツール呼び出しを何回リトライしますか?

Anthropicのツール利用のドキュメントには、リクエストが不正だったりパラメータが足りなかったりすると、Claudeは修正しながら2〜3回リトライしてからユーザーに謝る、と書かれています。リトライのたびにモデルのターンが増えるので、1回で直るエラーを返せば1〜2ターン分を節約できます。

PythonのMCPサーバーが「Error executing tool」としか返さないのはなぜ?

MCP Python SDK 2.xでは、ToolError(とSDKのいくつかの型)以外の例外はクラッシュとして扱われ、モデルには「Error executing tool <name>」しか見えません。想定している失敗は、対処方法を書いた ToolError("...") で投げてください。トレースバックはサーバーのログに残ります。

MCPツールからスタックトレースを返してもいいですか?

返さない方がよいです。私の計測では、54行のPythonのトレースバック1つで720トークンあり、それがその後のターンでも毎回コンテキストに残ります。サーバーのログに記録し、モデルには次に何をすべきかを1〜2文で返してください。

プロンプトキャッシュを使えばリトライのコストはゼロになりますか?

なりません。Claude Sonnet 5.5ではキャッシュヒットが100万トークンあたり2ドルではなく0.10ドルなので、読み直しのコストは大きく下がりますが、出力と新しく増えた部分は通常どおり課金されます。私の試算では、キャッシュありでもトレースバックで3回リトライするケースは、対処方法を書いたエラーのケースの4.6倍で、失敗した呼び出しはコンテキストの場所も取り続けます。

strict tool useでMCPの検証エラーはなくなりますか?

Claude APIで strict: true を付けると、ツール入力がJSON Schemaに必ず一致するので、パラメータの不足や型の不一致はなくなります。自作のエージェントがAPIにツール定義を渡す場合に使えるもので、存在しないIDのような意味の誤りは防げません。

障害中にエージェントがツールをリトライし続けるのを止めるには?

エラー文に「一時的に使えない、今はリトライしない、30秒ほどしてからもう一度」と書きます。自作のエージェントなら、ツールごとに連続した失敗を数え、2回を超えたら結果を「呼ぶのをやめてユーザーに説明する」指示に置き換えます。

ここでいう「MCP Token」はAPIトークンのことですか?

違います。この記事で扱うのは、MCPのツール呼び出しとエラーがコンテキストと料金で消費するLLMのトークンです。MCPサーバーのAPIキーやOAuthのアクセストークンはセキュリティの話題として別に扱っています。

まとめ

MCPのエラーのトークンコストは、エラー文そのものより、それが引き起こすターンで決まります。リトライのたびにコンテキスト全体が読み直されるので、3回やみくもにリトライすると、1回で直る分かりやすいエラーの3〜4倍かかります。長いトレースバックやHTMLページは、その後のターンでもさらに上乗せされます。MCPの仕様はすでに正しい方向を示していて、検証や実行の失敗は、対処方法を書いた isError: true の結果で返すことになっています。使っているSDKが何を返すかを確かめ(TypeScript 1.32.2は不正な項目を76トークンでまとめて返し、Python 2.3.0は ToolError を使わないと通常の例外を隠します)、リトライすべきでないときはそう伝え、スキーマとstrict tool useで不正な呼び出しを防ぎ、エージェントのループでリトライに上限を設けましょう。

参考資料

NodeFlareドキュメント ・ NodeFlareの料金

NodeFlare

MCP専用ホスティングサービス

GitHubにあるMCPを簡単デプロイ・簡単運用で最適化
無料で始める

他の記事

MCPトークン2026年11月17日

ツール引数は出力トークン:MCPのトークン消費で見落とされる「書く側」のコスト(write_fileとedit_fileを実測・2026年版)

MCPのツール引数は出力トークンで、単価は入力の5倍、キャッシュも効きません。公式Filesystemサーバーで1行の変更がwrite_file 5,549トークン対edit_file 49トークンになった実測、Sonnet 5.5・Opus 5.5・Fable 5.2での料金試算、ツール間の書き写し、max_tokensでの中断、書き直しの損益分岐、置換ツールのコードまで。

MCPセキュリティ2026年11月17日

MCPのきめ細かな認可:スコープでは防げないBOLAを、オブジェクト・引数・項目単位のチェックで止める【MCP Security 2026】

ツール単位のスコープでは防げない、MCPツールのオブジェクト・引数・項目単位の認可を解説。仕様の「スコープだけで十分とみなすのは誤り」、公式Python SDKを含む2026年のCVE3件、チェックの置き場所、8つのルール、検証済みPythonコード(スコープのみ4/14、多層14/14)とCedarポリシー(12/12)。

MCPホスティング2026年11月17日

Hugging Face SpacesはまだMCP Hostingに無料で使える?Gradioのmcp_server=Trueを2026年の有料化後に検証(Gradio 6.32)

2026年のHugging Face SpacesでのMCP Hosting。新規のGradio SpaceはZeroGPU以外PROが必要、無料ハードウェアは48時間でスリープ、Gradioのキューは既定で1件ずつ。Gradio 6.32で検証した /gradio_api/mcp/ の使い方、188 MB・1回約60 msの実測、Space名の接頭辞、ZeroGPUの上限、費用、Claude Code・Cursorの接続を解説。

失敗したMCPツール呼び出しはなぜトークンを食うのか:エラー文とリトライのMCP Tokenコストを2つのSDKで実測【2026年版】 | Blog | Nodeflare