MCP Appsのトークン消費:モデルが読むデータとUIだけに渡すデータの分け方【MCP Token・2026年実測】
MCP Appsでモデルに届くデータとUIだけに届くデータを整理。content・structuredContent・_metaのホスト別の扱い(仕様・ChatGPT・Claude)、visibility ["app"]のapp-onlyツール、updateModelContextとsendMessageの違い、50件のダッシュボードの実測とSonnet 5.5での費用試算、型チェック済みのTypeScript例。
最終更新:2026年11月6日 / 対象:MCP Apps拡張(SEP-1865、安定版仕様 2026-01-26)、
@modelcontextprotocol/ext-apps2.0.4、@modelcontextprotocol/server2.4.0、OpenAI Apps SDKリファレンス、ClaudeのMCP Appsドキュメント、Claude Sonnet 5.5の料金
MCP Appsを使うと、ツールはテキストを返すだけでなく、チャットの中に操作できるUI(View)を表示できます。そこで出てくるのが、MCPのトークン消費(MCP Token)に関する新しい疑問です。1つのツール結果がモデルとiframeの両方に渡るとき、モデルが実際に読むのはどの部分なのか。答えはフィールドごとに違い、しかも1つのフィールドはホストによって扱いが分かれます。この記事では、仕様と各ホストのドキュメントをもとに「モデルに届くもの」と「UIだけに届くもの」を整理し、ダッシュボード用ツール1つを4通りの形で実測して、Claude Sonnet 5.5での費用差を試算します。
※ここでいう「トークン」はLLMのトークン(コンテキストと課金)のことで、APIキーやOAuthのアクセストークンではありません。
結論(30秒で読める要約)
contentは必ずモデルに届きます。MCP Appsの仕様はcontentを「モデルのコンテキストとテキストのみのホスト向けの表現」と定義し、UIがあっても意味のあるcontentを返すことをMUSTとしています。- ホストで扱いが分かれるのは
structuredContentです。MCP Appsの仕様は「UI描画向けのデータで、モデルのコンテキストには追加しない」と書き、OpenAI Apps SDKは逆に「モデルとコンポーネントの両方に渡す」と書いています。ClaudeのMCP Appsドキュメントには記載がありません。 _metaはどちらでもモデルに見えません。仕様は「モデルのコンテキスト向けではない」、OpenAIは「コンポーネントにだけ渡し、モデルからは隠す」としています。UIでしか使わない大きなデータはここに置きます。- UI専用ツール(app-only)は、MCP Apps対応ホストではモデルのトークンを使いません。
_meta.ui.visibility: ["app"]を付けたツールは、ホストがエージェントのツール一覧に入れてはいけない(MUST NOT)と決まっています。ただしMCP Apps非対応のホストはこの指定を読まないので、対応クライアントのときだけ登録します。 - 実測では、50件の注文データが2,578トークン、モデル向けの要約が37トークンでした(o200k_base)。16ターンのセッションをSonnet 5.5で試算すると、データを
contentに入れて補助ツール4つをモデルに見せる形は0.0945ドル、データを_metaに移して補助ツールをapp-onlyにする形は、仕様どおりのホストで0.0034ドル、ChatGPTで0.0045ドルでした。 - UIの状態を伝えるには
sendMessageではなくupdateModelContextを使います。コンテキスト更新は上書きされ、モデルの応答も起こしません。フィルター変更10回をメッセージで送ると0.456ドル、コンテキスト更新なら最後の250トークンが1回届くだけです。
目次
- MCP Appsのトークン消費とは
- ツール結果のどのフィールドがモデルに届くか(ホスト別)
- 実測:ダッシュボード用ツール1つを4通りの形で
- Claude Sonnet 5.5でのコスト試算
- app-onlyツールでUI用の補助ツールをツール一覧から外す
- updateModelContextとsendMessageの違い
- 実装例(TypeScript、型チェック済み)
- チェックリスト
- よくあるハマりどころ
- NodeFlareならこう解決できる
- FAQ
1. MCP Appsのトークン消費とは
MCP Appsのトークン消費とは、UI付きのMCPツールが扱うデータのうち、モデルのコンテキストに入る分のことです。具体的には、モデルに渡るツール定義、ホストがモデルに転送するツール結果の一部、そしてViewがあとからモデルに送り返すコンテキストの3つです。HTMLテンプレート、UI専用のフィールド、app-onlyツールの結果など、Viewだけが受け取るデータはモデルのトークンを使いません。
MCP AppsはMCPの公式拡張です(SEP-1865、拡張ID io.modelcontextprotocol/ui)。仕様は2026年1月から「Stable(2026-01-26)」になっています。ツールは _meta.ui.resourceUri で ui:// リソースを指定し、ホストはそのHTMLを resources/read で取得してサンドボックス化したiframeに表示します。ツール結果は ui/notifications/tool-result でViewに渡されます。
トークンが流れうる経路は5つあり、モデルに届くのはその一部です。
| 経路 | 受け取る側 | モデルのトークンを使うか |
|---|---|---|
tools/list のツール定義のうち、visibilityに "model" を含むもの |
モデル(ツール一覧として) | 使う(毎ターン) |
visibility: ["app"] のツール定義 |
Viewのみ | MCP Apps対応ホストでは使わない |
ui:// のHTMLテンプレート |
ホストとView。仕様では「ホストはツール実行前の接続時にUIテンプレートを受け取る」 | 使わない。ツール結果ではなく resources/read で取得される |
ツール結果(content・structuredContent・_meta) |
フィールドごとに異なる(2章) | フィールドとホストによる |
Viewからの ui/update-model-context と ui/message |
以降のターンのモデル | 使う |
2. ツール結果のどのフィールドがモデルに届くか(ホスト別)
3つのフィールドの役割は文書化されており、仕様とChatGPTで食い違うのは structuredContent だけです。2026年11月6日時点の記述を並べます(引用は要旨の日本語訳)。
| フィールド | MCP Apps仕様(2026-01-26) | OpenAI Apps SDKリファレンス | ClaudeのMCP Appsドキュメント |
|---|---|---|---|
content |
モデルのコンテキストと、テキストのみのホスト向けの表現 | モデルとコンポーネントの両方に渡す | 記載なし |
structuredContent |
UI描画向けに最適化した構造化データ(モデルのコンテキストには追加しない) | モデルとコンポーネントの両方に渡す。「フィールドは簡潔に。モデルはそのまま読む」とも書かれている | 記載なし |
_meta |
タイムスタンプやバージョン情報などの追加情報で、モデルのコンテキスト向けではない | コンポーネントにだけ渡し、モデルからは隠す | 記載なし |
実務での読み方は次のとおりです。
- 厳しいほうの解釈に合わせて設計します。どのホストでも同じサーバーを使うなら、
structuredContentはモデルに読まれる前提で、モデルに役立つ小さな要約だけを入れます。かさばるデータは_metaに移します。 - 仕様の「モデルのコンテキストに追加しない」はMUSTではありません。データ受け渡しの節にある説明で、ホストに
structuredContentを捨てさせる規範的なルールはありません。対象のホストで確かめてください。 _metaは秘密の保管場所ではありません。OpenAIのガイドは「_metaはモデルから隠れるものとして扱い、認可や安全な保管の代わりにはしないこと」と書いています。Viewからも、Viewを調べる人からも読めます。- テキストのみのホストには
contentしか見えません。content単体で意味が通る必要があるのはこのためです。MCP Apps非対応のホストでは、ユーザーにもそれ以外は表示されません。
3. 実測:ダッシュボード用ツール1つを4通りの形で
モデルに見せるツール show_orders_dashboard を1つと、UI用の補助ツール4つ(orders_page、orders_sort_filter、orders_export_csv、orders_refresh)を持つ小さなMCP Appサーバーを作りました。ダッシュボードには50件の注文データが必要ですが、モデルに必要なのは件数と売上だけです。
方法(2026年11月6日):@modelcontextprotocol/ext-apps 2.0.4 の registerAppTool と @modelcontextprotocol/server 2.4.0 でサーバーを書き、tsc --strict で型チェックしたうえで、@modelcontextprotocol/client から InMemoryTransport 経由でツール一覧の取得と呼び出しを行いました。トークン数は o200k_base(gpt-tokenizer 4.1.0)で、空白なしのJSONを数えています。ツール定義はClaude APIのツール形式が受け取る name・description・input schema の3つで数えました。Claudeのトークナイザーでは絶対値が変わるので、比率で読んでください。
| データ | トークン数(o200k_base) |
|---|---|
| 注文50件、空白なしJSON | 2,578 |
| 同じデータ、整形済みJSON(2スペースのインデント) | 3,977 |
content の要約(「50 orders in the last 30 days (open 17, shipped 17, cancelled 16); revenue USD 24425.00. The dashboard is shown to the user.」) |
37 |
小さな structuredContent(days・total_orders・counts・revenue_usd) |
34 |
show_orders_dashboard の定義 |
67 |
| 補助ツール4つの定義 | 306(1つあたり44〜130) |
| 5つの定義をまとめたツール一覧 | 375 |
補助ツールを visibility: ["app"] にした後の、モデルに見える一覧 |
69 |
50件のデータの置き場所は4通り考えられます。1回の呼び出しでモデルが読むトークン数は次のとおりです。
| 置き方 | 仕様どおりのホスト | ChatGPT |
|---|---|---|
A. データを content に入れる(UI用に分けない) |
2,578 | 2,578 |
B. 要約は content、データは structuredContent |
37 | 2,615 |
C. 要約は content、小さな structuredContent、データは _meta |
37 | 71 |
D. Cと同じで、データはViewがapp-onlyの orders_page で取得 |
37 | 71 |
数字から分かること:
- このツールでは分け方だけで約70倍の差が出ます。データ2,578トークンに対し、要約は37トークンです。
- Bは落とし穴です。仕様の書き方に沿った自然な形に見えますが、
structuredContentをモデルに渡すホストでは全件をモデルが読みます。 - 整形済みJSONは同じデータで54%多くなります(3,977対2,578)。モデルに届く部分は空白なしにします。
- Dはツール結果そのものも小さくできます。最初の表示には1ページ分だけを載せ、残りはViewが必要なときに取りにいくので、モデルのターンは発生しません。
4. Claude Sonnet 5.5でのコスト試算
データはコンテキストに残っている限り毎ターン読まれ、補助ツールの定義はセッションの毎ターン送られます。以下は筆者の計算で、どのホストの請求額を計測したものでもありません。
前提:ダッシュボード用ツールを1回呼び、その後15ターン続くので結果は16回読まれる。ツール一覧も16ターンすべてで送られる。料金はAnthropicの料金ページにあるClaude Sonnet 5.5の入力100万トークンあたり2ドル(この表ではキャッシュなし)。
計算式:トークン数 =(モデルが読む結果のトークン数 + モデルに見えるツール定義のトークン数)× 16、費用 = トークン数 × 2ドル ÷ 1,000,000
| 設計 | モデルが読む結果 | 1ターンあたりの定義 | セッションの入力トークン | 1セッションの費用 | 1万セッション |
|---|---|---|---|---|---|
A. データを content、補助ツールもモデルに見せる |
2,578 | 375 | 47,248 | 0.0945ドル | 945ドル |
BをChatGPTで(structuredContent が読まれる)、補助ツールはapp-only |
2,615 | 69 | 42,944 | 0.0859ドル | 859ドル |
| BまたはCを仕様どおりのホストで、補助ツールはapp-only | 37 | 69 | 1,696 | 0.0034ドル | 34ドル |
| CをChatGPTで、補助ツールはapp-only | 71 | 69 | 2,240 | 0.0045ドル | 45ドル |
1行だけ手で確かめます。ChatGPTでのCは(37 + 34 + 69)× 16 = 2,240トークンで、2,240 × 2 ÷ 1,000,000 = 0.00448ドルです。
読み取れること:
- データをモデルの目から外すことが一番効きます。AはCの約28倍(仕様どおりのホスト)、約21倍(ChatGPT)です。
- Bで節約できるのは、ホストが仕様どおりに動く場合だけです。ChatGPTではAの91%かかります。
- プロンプトキャッシュは値段を下げますが、場所は空きません。Sonnet 5.5のキャッシュヒットは100万トークンあたり0.10ドルなので読み直しは安くなりますが、2,578トークンのデータは毎ターン、コンテキストウィンドウを占め続けます。
- Appが育つほどツール一覧が効いてきます。ここでは補助ツール4つで1ターン306トークンでした。並べ替え・絞り込み・書き出しの補助ツールが十数個ある実際のダッシュボードなら、これが全セッションの毎ターンにかかります。
5. app-onlyツールでUI用の補助ツールをツール一覧から外す
ページ送り、並べ替え、再読み込み、書き出しボタンのように、モデルが呼ぶ必要のないツールには visibility: ["app"] を付けます。仕様ではこのフィールドを「このツールにアクセスできるのは誰か。既定値は ["model", "app"]」と定義し、ホストに次のルールを課しています。
- visibilityに
"model"を含まないツール(例:visibility: ["app"])は、エージェントのツール一覧に入れてはならない(MUST NOT) - visibilityに
"app"を含まないツールへのアプリからのtools/callは拒否しなければならない(MUST)
MCP Appsの概要ページは、トークン面の理由をそのまま書いています。app-onlyツールは「エージェントのコンテキストを散らかすべきでないUI操作に向いている。モデルはこれらのツールを見ず、Viewが呼ぶためだけに存在する」。OpenAIのリファレンスも同じ _meta.ui.visibility に対応しており、独自の openai/widgetAccessible と openai/visibility は互換用のフィールドと位置づけています。標準のキーを使いましょう。
注意点は、MCP Apps非対応のホストです。テキストのみのクライアントは _meta.ui を読まないので、app-onlyツールもほかのツールと同じように一覧に並べます。モデルは見えもしないボタンの定義に毎ターン払い、勝手に呼ぶこともあります。補助ツールは、クライアントの対応を確認してから登録します。ext-apps SDKにはそのための getUiCapability があります。
import { McpServer } from "@modelcontextprotocol/server";
import { registerAppTool, getUiCapability, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";
const server = new McpServer({ name: "orders-dashboard", version: "1.0.0" });
server.server.oninitialized = () => {
const ui = getUiCapability(server.server.getClientCapabilities());
if (!ui?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) return; // テキストのみのホストではapp-onlyツールを登録しない
registerAppTool(server, "orders_page", {
description: "Fetch one page of orders for the dashboard table.",
inputSchema: z.object({ cursor: z.string().optional() }),
_meta: { ui: { resourceUri: "ui://orders/dashboard.html", visibility: ["app"] } },
}, async () => ({ content: [{ type: "text", text: "ok" }] }));
};
SDK自身の getUiCapability の例に沿った書き方で、ext-apps 2.0.4 と server 2.4.0 で型チェックが通ります。呼び出し元ごとにツールを絞り込めるプロキシやゲートウェイを使っている場合は、それもテキストのみのクライアントから補助ツールを隠すもう1つの方法になります(10章)。
6. updateModelContextとsendMessageの違い
ユーザーがViewを操作したとき、その状態をモデルに伝えるには ui/update-model-context を使い、すぐに返事が必要なときだけ ui/message を使います。両者のトークン費用は大きく違います。
ui/update-model-context(app.updateModelContext) |
ui/message(app.sendMessage) |
|
|---|---|---|
| モデルのターンが起きるか | 起きない。SDKの説明では「sendMessageと違い、すぐにはモデルの応答を起こさない」 | 起きる。会話にメッセージが追加される |
| 何度も呼んだとき | 毎回、Viewが以前に送ったコンテキストを上書きする | 1通ずつ履歴に残る |
| モデルに届くタイミング | ホストは次のユーザーメッセージまで送るのを遅らせてよい(MAY)。複数の更新があれば最後の1つだけを送るべき(SHOULD) | すぐ |
| 仕様にあるサイズの目安 | なし | なし |
試算例(筆者の計算、Sonnet 5.5・キャッシュなし):会話が20,000トークンの時点で、ユーザーがダッシュボードの絞り込みを10回変えたとします。状態の要約は1回250トークン、モデルの返事は1回150トークンとします。
- 変更のたびに
sendMessageする場合:ターンが10回増えます。k回目のターンは 20,000 + 250k + 150(k − 1) トークンを読むので、入力は合計220,500トークン、出力は1,500トークンです。0.441ドル + 0.015ドル = 0.456ドルで、履歴には4,000トークン分のやりとりが残ります。 - 変更のたびに
updateModelContextする場合:ターンは増えません。モデルに届くのは、次のユーザーメッセージと一緒に送られる最後の250トークンだけで、そのターンでの費用は約0.0005ドルです。
SDKのドキュメントからもう2点。大きなデータを渡すときの例として、先に updateModelContext で内容を送り、短い sendMessage(「要点をまとめて」など)で応答を促す書き方が示されています。また仕様にはサイズの上限がないので、送る量は自分で決めて抑えます。送るのは今見えている画面の要約で、データ全体ではありません。
7. 実装例(TypeScript、型チェック済み)
3章のサーバーから、トークン消費を左右する部分だけを抜き出しました。@modelcontextprotocol/ext-apps 2.0.4、@modelcontextprotocol/server 2.4.0、zod 4.6.7 に対して tsc --strict が通り、SDKのクライアントから呼ぶと上の実測どおりのデータを返しました。loadOrders は自分のデータ取得処理に置き換えてください。
import { McpServer } from "@modelcontextprotocol/server";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";
type Order = { id: string; customer: string; status: string; total: number; created_at: string };
declare function loadOrders(days: number): Promise<Order[]>;
const server = new McpServer({ name: "orders-dashboard", version: "1.0.0" });
const VIEW = "ui://orders/dashboard.html";
// モデルに見せるツール:ダッシュボードを開き、モデルには必要な情報だけを渡す
registerAppTool(server, "show_orders_dashboard", {
description: "Show an interactive dashboard of recent orders. Returns totals by status.",
inputSchema: z.object({ days: z.number().int().min(1).max(90).default(30) }),
_meta: { ui: { resourceUri: VIEW } },
}, async ({ days }) => {
const orders = await loadOrders(days);
const counts: Record<string, number> = {};
for (const o of orders) counts[o.status] = (counts[o.status] ?? 0) + 1;
const revenue = orders.reduce((sum, o) => sum + o.total, 0).toFixed(2);
return {
// どのホストでもモデルが読む:短く、単体で意味が通るように
content: [{ type: "text", text: `${orders.length} orders in the last ${days} days; revenue USD ${revenue}. The dashboard is shown to the user.` }],
// モデルが読むホストもある(ChatGPT):小さな要約だけ
structuredContent: { days, total_orders: orders.length, counts, revenue_usd: Number(revenue) },
// モデルには見えない:View用の最初の1ページ分
_meta: { rows: orders.slice(0, 25) },
};
});
// app-only:Viewがページ送りに使う。モデルはこのツールを見ない
registerAppTool(server, "orders_page", {
description: "Fetch one page of orders for the dashboard table.",
inputSchema: z.object({ days: z.number().int().default(30), cursor: z.number().int().min(0).default(0) }),
_meta: { ui: { resourceUri: VIEW, visibility: ["app"] } },
}, async ({ days, cursor }) => {
const orders = await loadOrders(days);
return {
content: [{ type: "text", text: "ok" }],
_meta: { rows: orders.slice(cursor, cursor + 25), next: cursor + 25 },
};
});
// HTMLテンプレート:resources/readで取得され、ツール結果には含まれない
registerAppResource(server, "Orders dashboard", VIEW, {}, async () => ({
contents: [{ uri: VIEW, mimeType: RESOURCE_MIME_TYPE, text: "<!doctype html><html><body><div id=app></div></body></html>" }],
}));
View側では、ツール結果の _meta からデータを読み、続きは orders_page で取得します。絞り込みを変えたら、1行の要約を updateModelContext で送ります(6章)。
8. チェックリスト
- [ ]
contentは短く、それだけで答えになっていて、テキストのみのホストでも通用する - [ ]
structuredContentにはモデルに読ませてよいものだけを入れている(モデルに渡すホストがあるため) - [ ] 大量の行データ、グラフの系列、表示専用の項目は
_metaに置くか、app-onlyツールでViewが取得している - [ ]
_metaに秘密情報を入れていない。認可はサーバー側で行っている - [ ] UI用の補助ツールに
_meta.ui.visibility: ["app"]を付けている - [ ] app-onlyツールは、クライアントがMCP Apps対応を示したとき(
getUiCapability)だけ登録している - [ ] Viewは状態の共有に
updateModelContextを使い、sendMessageは返事が必要なときだけ使っている - [ ] コンテキスト更新は、自分で決めた上限内の要約で、データ全体ではない
- [ ] モデルが読む部分は空白なしのJSONかプレーンテキストで、整形済みJSONではない
- [ ] ツール結果全体がホストのサイズ上限を十分下回っている(9章)
- [ ] 対象のホストごとに、モデルが実際に何を受け取ったかを確認した
9. よくあるハマりどころ
| 症状 | 原因 | 対処 |
|---|---|---|
データを structuredContent に移したのにトークンがほとんど減らない |
ホストが structuredContent をモデルに渡している(ChatGPTはそう明記) |
データは _meta に置き、structuredContent は要約だけにする |
| モデルがページ送りや並べ替えのツールを勝手に呼ぶ | 補助ツールのvisibilityが既定値の ["model", "app"] のまま |
visibility: ["app"] を付ける |
| テキストのみのクライアントのツール一覧にapp-onlyツールが出る | そのクライアントは _meta.ui を読まない |
getUiCapability で対応を確認してから登録するか、呼び出し元ごとにツールを絞る |
claude.ai やClaude DesktopでViewにデータが表示されない |
Claudeのドキュメントによると、結果が約150,000文字を超え、コード実行サンドボックスが有効な場合、結果はサンドボックスのファイルに書き出され、アプリにはファイルへの参照しか届かない | 最初は1ページ分だけ送り、残りはapp-onlyツールでViewに取らせる |
| Claude Codeで結果が切り詰められる・ファイルに保存される | Claude Codeには別の上限(既定25,000トークン、MAX_MCP_OUTPUT_TOKENS で変更可)がある |
上限を上げるより結果を小さくする |
| 履歴がUIのやりとりで埋まり、クリックのたびにモデルが返事をする | 状態の共有に sendMessage を使っている |
updateModelContext を使う。上書きされ、ターンも起きない |
| テキストのみのユーザーに空っぽや役に立たない答えが表示される | モデルに見せるツールの content が「ok」のまま |
仕様どおり、意味のある content を返す |
| モデルに届くトークンが想定より多い | content や structuredContent が整形済みJSON |
空白なしで出力する(3章では54%小さくなった) |
10. NodeFlareならこう解決できる
NodeFlareは、GitHubリポジトリにあるMCPサーバーをホストし、プロキシ側でサーバー単位の4つのトークン節約スイッチを提供しています。どれもプロキシ側で透過的に適用されるので、サーバーのコードを変える必要はありません。NodeFlareのドキュメントはこれらのスイッチを tools/list とツール呼び出しの単位で説明しており、MCP Appsには触れていません。スイッチを有効にしたら、ホストでViewが従来どおり表示されるかを確認してください。ここまでの課題との対応は次のとおりです。
課題1:app-onlyの補助ツールが、テキストのみのクライアントのツール一覧に出てしまう(5章)。tool_list_filter_by_scope を有効にし、テキストのみのエージェントには、モデル向けのツールだけを呼べるスコープのAPIキーを発行します。tools/list はそのキーで実際に呼べるツールだけに絞られ、スキーマはそのままです。visibility を読まないクライアントでも同じ効果が得られ、サーバーに対応確認の処理を足す必要もありません。
課題2:モデルが要約を見るだけでなく、データそのものを分析したい(3章・4章)。Code Execution(tool_code_mode)を有効にします。サーバーは run_code と search_tools を公開し、モデルは tools.* を呼ぶJavaScriptを書きます。NodeFlareはそれをサンドボックスで実行し、複数のツール呼び出しを1回の実行にまとめて、その戻り値だけを会話に入れます。実行は分離されたDenoのサブプロセスで行われ(ファイルシステム・環境変数・プロセス起動なし、ネットワークはプロキシのコールバック先のみ)、既定ではタイムアウト600秒、1回の実行あたり最大50回のツール呼び出し、V8ヒープ128MBです。試算例(4章の前提での筆者の計算で、NodeFlareの計測値ではありません):「キャンセルが一番多い顧客は?」に答えるために2,578トークンのデータをそのままコンテキストに入れると、Sonnet 5.5で16ターン分約0.083ドルかかります。150トークンのスクリプトが30トークンの答えを返す形なら約0.007ドルです。モデル自身のデータ処理に使い、ダッシュボードの表示は表示用のツールに任せる、という使い分けがおすすめです。
課題3:機能が増えるにつれ、1つのAppサーバーのツールが増えていく(4章)。tool_search_mode を有効にすると、NodeFlareは tools/list を search_tools(query) と call_tool(name, args) の2つのメタツールにまとめます。カタログがどれだけ大きくなっても、最初のトークン消費はほぼ一定です。検索は既定で字句検索で、GEMINI_API_KEY を設定すると意味検索(embedding)に切り替わります。未設定や失敗時は字句検索に戻り、リクエストが止まることはありません。
課題4:モデルに見せるツールの説明文が長い。tool_schema_slim を有効にすると、500文字を超えるツール説明を(UTF-8として安全な位置で)切り詰めます。ツール名と入力スキーマはそのままです。
NodeFlareは固定の削減率を公表していません。各スイッチの前後で、自分のセッションを計測して比べてください。
最小の始め方:
- NodeFlareのダッシュボードで、MCPサーバーのGitHubリポジトリ(モノレポのサブディレクトリも可)を選びます。ランタイム・トランスポート・起動コマンドは自動で判定され、入力されます。
- デプロイしたら
tool_code_modeを有効にします(必要に応じてtool_list_filter_by_scopeやtool_search_modeも)。 - サーバーのURLとAPIキーをMCPクライアントに設定します。クライアントごとの書き方はリモートMCPクライアント設定チートシートをご覧ください。
MCPサーバー1つまでは無料で試せます(Freeプラン:サーバー1つ、コンピュート月30 GB-hours)。→ NodeFlareを無料で始める
11. FAQ
MCP AppsのstructuredContentはモデルのコンテキストに入る?
ホストによります。MCP Appsの仕様は structuredContent を「UI描画向けで、モデルのコンテキストには追加しない」と説明していますが、OpenAI Apps SDKは「モデルとコンポーネントの両方に渡す」としています。ClaudeのMCP Appsドキュメントには記載がありません。どちらでも困らないよう、小さく保つのが安全です。
MCPツール結果の_metaはモデルに送られる?
文書化されているホストでは送られません。MCP Appsの仕様は _meta を「モデルのコンテキスト向けではない」とし、OpenAIのリファレンスは「コンポーネントにだけ渡し、モデルからは隠す」としています。ただしViewからは読めるので、秘密情報は入れないでください。
MCPツールをモデルから隠して、UIからだけ呼べるようにするには?
_meta.ui.visibility を ["app"] にします。仕様では、ホストはこうしたツールをエージェントのツール一覧に入れてはならず(MUST NOT)、"app" を含まないツールへのアプリからの呼び出しは拒否しなければなりません。MCP Apps非対応のホストはこの指定を無視するので、クライアントの対応を確認してから登録します。
MCP AppのHTMLはモデルのトークンを使う?
仕様に書かれている範囲では使いません。ホストは ui:// リソースを resources/read で取得し、事前取得やキャッシュもできます。ツール結果には含まれません。仕様はこれを「表示(テンプレート)とデータ(ツール結果)の分離」と説明しています。
updateModelContextとsendMessageの違いは?
updateModelContext は以降のターン用にコンテキストを保存するだけで、モデルの応答は起こさず、呼ぶたびに前の内容を上書きします。sendMessage は会話にメッセージを追加し、モデルがそれに返事をします。筆者の試算では、絞り込み変更10回をメッセージで送ると0.456ドル、コンテキスト更新なら約0.0005ドルでした(Sonnet 5.5)。
MCP Appsのツール結果は何トークン使う?
ホストがモデルに渡す分だけです。筆者の50件のダッシュボードでは、データが2,578トークン、モデル向けの要約が37トークンでした(o200k_base)。仕様どおりのホストでモデルが読むのは37トークン、structuredContent も読むChatGPTでは、小さな構造化要約と合わせて71トークンでした。
ClaudeでMCP Appsのツール結果にサイズ上限はある?
Claudeのトラブルシューティングページによると、claude.ai とClaude Desktopでは、結果が約150,000文字を超え、コード実行サンドボックスが有効な場合に結果がサンドボックスのファイルへ書き出され、アプリにはファイルへの参照しか届かず表示されません。Claude Codeは別の上限で、既定25,000トークン(MAX_MCP_OUTPUT_TOKENS で変更可)です。
app-onlyツールはChatGPTのツール一覧に出る?
OpenAIのリファレンスは _meta.ui.visibility(既定値 ["model", "app"])を、ツールをモデル・UI・その両方のどれに使わせるかを決めるフィールドとして説明しています。UI専用にするには ["app"] を指定するのが文書化された方法です。以前の openai/widgetAccessible と openai/visibility は互換用のフィールドです。
グラフのデータはcontentとstructuredContentのどちらに入れる?
モデルが使わないなら、どちらにも入れません。グラフの系列は _meta に置き、モデルには content で1行の要約を渡し、structuredContent はモデルに考えさせたい少数の項目だけにします。筆者の試算では、ChatGPTでも1セッションの費用が0.0945ドルから0.0045ドルに下がりました。
ここでいう「MCP Token」はAPIトークンのこと?
違います。この記事が扱うのは、MCP Appsのツール定義・ツール結果・コンテキスト更新がコンテキストウィンドウと請求で消費するLLMのトークンです。MCPサーバーのAPIキーやOAuthのアクセストークンはセキュリティの話題です。
まとめ
MCP Appsでは1つのツール結果をモデルとUIで分け合うため、データをどのフィールドに置くかでトークン消費が決まります。content は必ずモデルに届き、_meta は文書化されたホストでは届きません。structuredContent は、MCP Appsの仕様(モデルのコンテキストに入れない)とChatGPT(そのまま読む)で扱いが分かれるフィールドです。厳しいほうのホストに合わせて、短い content、小さな structuredContent、かさばるデータは _meta かapp-onlyツールの先へ、補助ツールには visibility: ["app"] を付けて対応ホストでだけ登録し、UIの状態は updateModelContext で送る。筆者の実測例では、最も厳しい解釈でも16ターンのセッションが47,248トークンから2,240トークンに減りました。ツール結果と定義の削り方全般は、MCPツール結果を小さくする8つの方法とMCPツール定義の監査と削減も参考にしてください。
参考資料
- MCP Apps仕様 SEP-1865(安定版、2026-01-26)
- MCP Apps概要(ext-apps APIドキュメント)
- modelcontextprotocol/ext-apps(GitHub)
- OpenAI Apps SDK:Reference
- OpenAI Apps SDK:Build your MCP server
- Claude Docs:MCP Apps getting started
- Claude Docs:MCP Apps troubleshooting
- Claude Docs:Pricing
- @modelcontextprotocol/ext-apps(npm) ・ @modelcontextprotocol/server(npm) ・ gpt-tokenizer(npm)
- NodeFlareドキュメント ・ NodeFlare料金
