MCP HostingでツールコールをOpenTelemetryでトレースする方法:SDKの既定動作・_metaでの伝搬・stdioブリッジの死角【2026年版】
ホストしたMCPサーバーのツールコールをOpenTelemetryでエンドツーエンドに追う方法。既定でスパンを出すSDK(Python v2・TypeScript v2・FastMCP 4・C#)、params._metaでのtraceparent伝搬(SEP-414)、セマンティック規約のスパン名と属性、区間ごとのレイテンシの割り出し方、stdoutを壊すエクスポーターやスケールゼロでのスパン消失など6つの落とし穴を解説します。
最終更新:2026年11月16日 / 対象:OpenTelemetryのMCPセマンティック規約(Development、現在はsemantic-conventions-genaiリポジトリで管理)、SEP-414(Final)、MCP仕様2026-07-28、MCP Python SDK v2、MCP TypeScript SDK v2、FastMCP 4.x、MCP C# SDK(規約への準拠は2026年1月14日にマージ)。記述はすべて公式ドキュメントに基づき、ドキュメントに記載がない点はその旨を書いています。
結論(30秒で読める要約)
MCPのツールコールをOpenTelemetryでトレースするとは、MCPリクエストごとにクライアント側とサーバー側で1つずつスパンを記録し、リクエストの params._meta に入れたW3Cの traceparent で同じトレースにつなぐことです。MCP Hostingでは、遅いツールコールの時間がネットワーク、ゲートウェイ、stdioブリッジ、サーバー自身の処理、呼び出し先APIのどこで使われているかを、このトレースで切り分けます。
- 主要な公式SDKは、すでにスパンを出します。MCP Python SDK v2は、設定なしで「処理するすべてのメッセージ」に
SERVERスパンを作ります。TypeScript SDK v2のClient・McpServer・Serverも全リクエストでスパンとメトリクスを出し、FastMCPも「既定でオン」です。ただし、OpenTelemetryのSDKとエクスポーターを登録するまでは何も記録されません。 - トレースコンテキストは
params._metaで運ばれます。SEP-414(Final)が、キー名を接頭辞なしのtraceparent・tracestate・baggageに固定しました。規約では、受け手はこれをサーバースパンの親として使うべき(SHOULD)とされています。 - スパン名は
{mcp.method.name} {target}の形で、たとえばtools/call search_booksになります。isError: trueで返ったツールの失敗には、error.typeにtool_errorを入れるべき(SHOULD)とされています。 - ホスティングでは死角が3つできます。エッジからサーバーまでの区間(ブリッジやプロキシは多くの場合MCPのスパンを出さない)、エクスポーターがstdoutに書いてJSON-RPCを壊すstdioサーバー、スケールゼロで送信待ちのスパンが消えることです。
- 規約のステータスはDevelopmentです。属性名は今後も変わりうるので、SDKのバージョンとダッシュボードをセットで固定します。
目次
- MCPのトレースとは
- 既定でスパンを出すSDK
- トレースコンテキストがMCPの境界を越える仕組み
- スパン名・属性・メトリクス
- ホストしたツールコールの時間はどこで使われているか
- 設定手順:Python SDK v2・FastMCP・TypeScript
- ホスティングでの6つの落とし穴
- サンプリングとコスト
- チェックリスト
- トラブルシューティング:症状→原因→対処
- NodeFlareならこう解決できる
- FAQ
1. MCPのトレースとは
MCPのトレースとは、Model Context Protocolに分散トレーシングを当てはめたものです。MCPクライアントとMCPサーバーの間のJSON-RPCリクエストを1つずつスパンにし、両側のスパンに同じトレースIDを持たせることで、1回のツールコールを1本のタイムラインとして読めるようにします。スパンの名前と属性は、OpenTelemetryのMCPセマンティック規約が定めています。
このブログで以前扱った2つのテーマと隣り合っていますが、どちらとも別物です。
| 死活監視 | 監査ログ | トレース | |
|---|---|---|---|
| 答える問い | サーバーは動いていて、ツールは使えるか | 誰がどのツールを呼び、結果はどうだったか | この呼び出しはどこで時間を使い、どこで失敗したか |
| 単位 | N分ごとの合成プローブ | リクエストごとに改ざんできない記録1件 | 区間ごとのスパン。トレースIDでつながる |
| サンプリング | しない | 絶対にしない | 通常はする |
| 解説記事 | MCPサーバーのヘルスチェック | MCPの監査ログ設計 | この記事 |
MCPの仕様もこの方向を示しています。2026-07-28版ではプロトコル独自のLogging機能がSEP-2577で非推奨になり、代替として「stdioでは stderr、構造化された可観測性にはOpenTelemetry」が挙げられています。
2. 既定でスパンを出すSDK
主要なMCP SDKは、どれもOpenTelemetryのAPIだけに依存する計測を組み込んでいます。そのため、SDKとエクスポーターを入れるまではスパンのコストはかかりません。
| SDK | 既定でスパンを出すか | _meta での伝搬 |
追加するもの | 無効化 |
|---|---|---|---|---|
MCP Python SDK v2(MCPServer) |
出す。受信メッセージごとに SERVER スパン |
クライアントが書き込み、サーバーが読み出す(SEP-414を参照) | opentelemetry-sdk と opentelemetry-exporter-otlp |
OpenTelemetryMiddleware を外す(importは暫定扱い) |
MCP TypeScript SDK v2(Client・McpServer・Server) |
出す。notifications/message 以外の全リクエストと通知でスパンとメトリクス |
params._meta で伝搬 |
@opentelemetry/api・sdk-trace・context-async-hooks・core |
openTelemetry: false |
| FastMCP 4.x | 出す(「On by default」) | _meta に traceparent と tracestate |
opentelemetry-distro とOTLPエクスポーター |
FASTMCP_TELEMETRY_MODE=off または propagation_only |
| MCP C# SDK | 規約に合わせたスパン(PR #1139、2026年1月14日マージ) | PR内で params._meta での伝搬を検証 |
.NETのOpenTelemetry SDK | PRに記載なし |
| Logfire(Python) | 出さない。logfire.configure() を呼ぶ |
クライアントとサーバーのスパンを1つのトレースにまとめる | Logfire | 該当なし |
ホスティングで効いてくる点が2つあります。1つは、MCP Python SDK v2ではSDK自身が計測するため、Logfireのドキュメントが「両側とも logfire.configure() だけでよい」とし、instrument_mcp() は警告を出すだけになったことです。もう1つは、TypeScriptのドキュメントが「SDKを登録しないと何も記録されず、params._meta にも何も追加されない」としている点です。OpenTelemetryを設定していないクライアントはトレースコンテキストを送らないので、サーバー側では新しいトレースが始まります。
3. トレースコンテキストがMCPの境界を越える仕組み
トレースコンテキストは、HTTPヘッダーではなくリクエストの本文に入って、クライアントからサーバーへ渡ります。クライアントが params._meta に traceparent(必要なら tracestate と baggage も)を書き込み、サーバーがそれを読み出して、自分のスパンのリモートの親にします。
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": { "city": "Tokyo" },
"_meta": {
"traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
}
}
}
これはSEP-414の非規範的な例に引数を足したものです。背景にあるルールは次のとおりです。
- キー名は固定で、接頭辞を付けません。SEP-414は
traceparent・tracestate・baggageを「_metaのキーにDNS形式の接頭辞を付ける慣習の例外」としています。MCPのリリース候補の告知記事は、これで「SDKやゲートウェイをまたいで分散トレースが対応づくように」名前を固定したと説明しています。 - サーバーはHTTPヘッダーではなく
_metaを親にします。規約では、サーバーは既定で「params._metaから取り出したコンテキストをMCPサーバースパンの親にし、その時点のアンビエントコンテキストはリンクにすべき」とされています。MCPのコンテキストとトランスポート(HTTP)のコンテキストは独立しているので、ロードバランサーが付けたHTTPのtraceparentヘッダーは親ではなくリンクになります。 - stdioでも動きます。コンテキストはJSON-RPCのメッセージに入っているので、トランスポートに依存しません。メッセージ本文をそのまま転送するstdioブリッジなら、
_metaは子プロセスまで届きます。 - baggageは漏れることがあります。TypeScriptのドキュメントは、
W3CTraceContextPropagatorだけを登録しないとbaggageが第三者のサーバーにも送られうると注意しています。SEP-414も、トレースコンテキストに「相関IDが含まれうる」と書いています。自分で運用していないサーバーに届くbaggageには、ユーザーIDを入れないでください。
4. スパン名・属性・メトリクス
MCPのセマンティック規約では、クライアントとサーバーのスパン名を {mcp.method.name} {target}(targetはツール名やプロンプト名)とし、スパンの種類を CLIENT または SERVER にします。必須の属性は mcp.method.name の1つだけです。
| 属性 | 要件レベル | 例・補足 |
|---|---|---|
mcp.method.name |
Required | tools/call、tools/list、initialize |
gen_ai.tool.name |
Conditionally Required | search_books |
gen_ai.operation.name |
Recommended | ツールコールのときだけ execute_tool |
jsonrpc.request.id |
Conditionally Required | リクエストのとき |
mcp.protocol.version |
Recommended | 規約の例は 2025-06-18 |
mcp.session.id |
Recommended | セッションに属するリクエストのときだけ |
mcp.resource.uri |
Conditionally Required | resources/read のとき |
error.type |
Conditionally Required | isError がtrueなら tool_error。JSON-RPCエラーならエラーコードの文字列 |
rpc.response.status_code |
Conditionally Required | レスポンスにエラーコードがあるとき |
network.transport |
Recommended | HTTPなら tcp/quic、stdioなら pipe |
gen_ai.tool.call.arguments/.result |
Opt-In | 「機密情報を含みうる」 |
メトリクスは秒単位のヒストグラムで、mcp.client.operation.duration と mcp.server.operation.duration があります。推奨されるバケット境界は0.01秒〜300秒(0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300)です。セッションの長さのヒストグラムもあります。
実務への影響は3つです。
- すべてのエラーコードがエラー扱いになるわけではありません。規約は、所要時間のメトリクスでは
-32700・-32600・-32601・-32602・-32002をエラーとみなさないとしています。2026-07-28版の仕様では「リソースが見つからない」が-32002から-32602に変わりましたが、どちらも「エラーではない」側に入るので、新旧どちらのサーバーでも扱いは同じです。 mcp.session.idは空のことが多くなります。2026-07-28版ではMcp-Session-Idヘッダーとプロトコルレベルのセッションが廃止されました(SEP-2567)。集計はトレースIDか、自前の呼び出し元IDで行います。- エージェントでは、ツールごとにスパンが1つ増えるとは限りません。外側のGenAI計測がすでにツールの実行をトレースしている場合、MCPの計測は「別のスパンを作るべきではなく」、そのスパンに属性を足します。C# SDKはクライアント側でこの判定を実装しています。
5. ホストしたツールコールの時間はどこで使われているか
ホストしたツールコールは最大5つの区間を通りますが、見えるスパンを出すのはその一部だけです。入れ子になったスパンの所要時間を引き算すると、どの区間が遅いかがわかります。
| 区間 | MCPのスパンを出すか | 時間の見方 |
|---|---|---|
| 1. MCPクライアント(自作エージェント) | OpenTelemetryを登録したSDKなら出す | tools/call X のCLIENTスパン |
| 1'. MCPクライアント(Claude・Cursor・ChatGPT) | 自分のコレクターには届かない | トレースは区間2から始まる |
| 2. エッジ/ロードバランサー/ゲートウェイ | HTTPスパンを出すことはあるが、MCPスパンはまれ | アクセスログの所要時間、またはゲートウェイのスパン |
| 3. stdioブリッジ/プロキシ | 通常は出さない | 区間2と区間4の差 |
| 4. MCPサーバーのハンドラー | 出す(SDKの既定) | tools/call X のSERVERスパン |
| 5. 呼び出し先API/DB | HTTPやDBの自動計測を入れれば出す | サーバースパンの子スパン |
計算は次のとおりです。
- ネットワーク+エッジ+ブリッジ+待ち行列 = クライアントスパン − サーバースパン(クライアントが自分のものの場合のみ)
- 自分のコードの処理時間 = サーバースパン − 呼び出し先の子スパンの合計
- 呼び出し先の時間 = 子スパンそのもの
- コールドスタートは、アイドル後の最初の呼び出しで区間の差が不自然に長くなる形で現れます。しばらく呼ばれなかった後の1回目を中央値と比べます。往復回数やリージョンの観点はMCPサーバーのレイテンシ計測の記事で扱いました。
Claude.aiやCursorのようにクライアントが自分のものでない場合は、エッジでのリクエスト所要時間からサーバースパンを引いた値が、ブリッジと待ち行列の時間の一番よい推定値になります。
6. 設定手順:Python SDK v2・FastMCP・TypeScript
どのSDKでも手順は同じ3つです。OpenTelemetryのSDKとOTLPエクスポーターを入れ、service.name を付けてトレーサープロバイダーを登録し、標準の環境変数 OTEL_EXPORTER_OTLP_ENDPOINT でコレクターを指定します。
MCP Python SDK v2では、サーバーがすでにスパンを作っているので、送り先を登録するだけです。
import atexit
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from mcp.server import MCPServer
provider = TracerProvider(resource=Resource.create({"service.name": "bookshop-mcp"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) # OTEL_EXPORTER_OTLP_ENDPOINT を読む
trace.set_tracer_provider(provider)
atexit.register(provider.shutdown) # 終了時にバッファ内のスパンを送る
mcp = MCPServer("Bookshop")
@mcp.tool()
def search_books(query: str) -> str:
...
インストールは uv add opentelemetry-sdk opentelemetry-exporter-otlp です。これで各 tools/call が tools/call search_books という名前のスパンになり、mcp.method.name・mcp.protocol.version・jsonrpc.request.id・gen_ai.operation.name・gen_ai.tool.name が付きます。ハンドラーが例外を投げるか is_error=True を返すと、エラーのステータスになります。
FastMCP 4.xでは、公式ドキュメントにあるコード変更なしの計測を使います。
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
opentelemetry-instrument --service_name my-fastmcp-server \
--exporter_otlp_endpoint http://localhost:4317 fastmcp run server.py
前段のゲートウェイがすでにMCPのスパンを作っていて、コンテキストの受け渡しだけが欲しい場合は FASTMCP_TELEMETRY_MODE=propagation_only にします。
TypeScript SDK v2では、@opentelemetry/api・@opentelemetry/sdk-trace・@opentelemetry/context-async-hooks・@opentelemetry/core を入れ、AsyncLocalStorageContextManager を使ってトレーサープロバイダーを登録します。これでSDKの Client と McpServer が、@modelcontextprotocol/client と @modelcontextprotocol/server のスコープで tools/call get-weather のようなスパンを記録します。登録コードの正確な形は、SDKドキュメントのOpenTelemetryのページに従ってください。baggageをプロセスの外に出したくない場合は、W3CTraceContextPropagator だけを登録します。
ホスティング先のコンテナで設定する変数(OpenTelemetry SDK標準)は次のとおりです。
| 変数 | よく使う値 | ホスティングで効く理由 |
|---|---|---|
OTEL_SERVICE_NAME |
github-mcp-prod |
リポジトリ単位ではなく、デプロイしたサーバー単位で名前を付ける |
OTEL_EXPORTER_OTLP_ENDPOINT |
コレクターやベンダーのURL | 外向きの通信が必要 |
OTEL_EXPORTER_OTLP_HEADERS |
authorization=Bearer … |
シークレット。APIキーと同じように保管する |
OTEL_TRACES_SAMPLER |
parentbased_traceidratio |
クライアントのsampledフラグに従う |
OTEL_TRACES_SAMPLER_ARG |
0.1 |
新しいトレースの10% |
OTEL_BSP_SCHEDULE_DELAY |
既定5000ミリ秒 | 送信前にスパンがメモリで待つ時間 |
7. ホスティングでの6つの落とし穴
ホスティングでMCPのトレースが壊れる原因は、たいていSDKではなく、サーバーを取り巻く環境にあります。
- コンソールエクスポーターがstdioサーバーを壊します。Pythonの
ConsoleSpanExporterは既定でsys.stdoutに書きますが、stdioサーバーではstdoutがJSON-RPCの通信路です。ブリッジの後ろのstdioサーバーでOTEL_TRACES_EXPORTER=consoleにすると、クライアント側でパースエラーになります。OTLPで送るか、コンソール出力をstderrに向けます。 - ブリッジの区間は見えません。stdioブリッジや多くのプロキシは、MCPのスパンを出さずにJSON-RPCを転送するので、そこで使った時間は「差」としてしか現れません。この差が大きいときは、ブリッジの並行処理を確認します。stdioの子プロセスは、1本のパイプでリクエストを順に処理します。
- 子プロセスに
OTEL_*の変数が渡っている必要があります。ブリッジがサーバーを起動する場合、サーバーのエクスポーターは引き継いだ環境変数を読みます。環境変数を消したり絞ったりして起動するブリッジだと、エラーも出ずに送信が止まります。 - スケールゼロでスパンが消えます。
BatchSpanProcessorは、スパンをメモリにためてから(既定5秒)送ります。最後のリクエストのあとにインスタンスを止めるプラットフォームや、returnしたら終わるサーバーレス関数では、最後のバッチが失われることがあります。SIGTERMを受けたとき、またはサーバーレスのハンドラーがreturnする前に、provider.shutdown()かforce_flush()を呼びます。 - 外向き通信の制限がエクスポーターを止めます。ホスティング先が外向き通信を制限している場合、コレクターのホスト名を許可リストに入れないと、ツールは動くのに裏でエクスポーターだけが失敗し続けます。
- Opt-Inの属性は、引数をトレースストアに残します。
gen_ai.tool.call.argumentsとgen_ai.tool.call.resultがOpt-Inなのには理由があります。トレースは監査ログより保存期間やアクセス制御がゆるいことが多いので、ツールが受け取る内容を確認するまではオフにしておきます。
8. サンプリングとコスト
MCPのトレースは、親に従う比率サンプラーで間引き、エラーはすべてコレクターのテールサンプリングで残すのが基本です。親に従うサンプラーでは、sampledフラグ付き(-01)の traceparent を送ってきたクライアントが、サーバー側の記録の有無を決めます。
- ヘッドサンプリング(
parentbased_traceidratio、0.05〜0.2)なら、コストを通信量に比例させられます。tools/listは最も頻度が高い一方で一番面白みのないメソッドであることが多いので、コレクターで落とすか強めに間引きます。 - OpenTelemetry Collectorのテールサンプリングを使えば、
error.typeが付いたトレースや目標時間を超えたトレースを100%残せます。 - メトリクスは間引かれません。P95のダッシュボードやアラートには
mcp.server.operation.durationを使い、個々の遅い呼び出しを掘り下げるときにトレースを使います。
9. チェックリスト
- [ ] サーバーのイメージにOpenTelemetry SDKとOTLPエクスポーターが入っている
- [ ] デプロイしたサーバーごとに
OTEL_SERVICE_NAMEを設定した - [ ] ホスティング先からコレクターに届く(外向き通信の許可リストを確認した)
- [ ] エクスポーターのヘッダーをイメージではなくシークレットとして保管した
- [ ] stdioサーバーでstdoutにコンソールエクスポーターを出していない
- [ ] ブリッジの後ろの子プロセスに
OTEL_*の変数が届いている - [ ] SIGTERM時と、サーバーレスのハンドラーがreturnする前にスパンを送り切っている
- [ ] 自作エージェントのクライアントにもOpenTelemetryを登録し、
_meta.traceparentが送られている - [ ] 第三者のサーバーへのbaggageを制限するか、無効にした
- [ ] 引数と結果のOpt-In属性を確認した(既定はオフ)
- [ ] ダッシュボードをスパン数ではなく
mcp.server.operation.durationで作った - [ ] SDKのバージョンとダッシュボードをセットで固定した(規約はDevelopment)
10. トラブルシューティング:症状→原因→対処
| 症状 | 考えられる原因 | 対処 |
|---|---|---|
| クライアントとサーバーのスパンが別のトレースになる | クライアントにOpenTelemetry SDKが登録されておらず、_meta に何も書かれていない |
クライアントのプロセスでトレーサープロバイダーを登録する |
| サーバーのスパンがロードバランサーのトレースの下に入らない | HTTPヘッダーが親になると思っていた | 仕様どおりの動作。規約は _meta を親にし、アンビエントコンテキストはリンクにする |
| トレースを有効にしたらクライアントでJSONのパースエラーが出る | stdioサーバーのコンソールエクスポーターがstdoutに書いている | OTLPかstderrを使う |
| ホストしたサーバーからスパンが1つも来ない | SDK未登録、エンドポイントの誤り、外向き通信のブロック、子プロセスに環境変数が渡っていない | この順に確認する。ローカルのコレクターで試す |
| アイドル前の最後の呼び出しが出てこない | 終了時にバッファが捨てられた | SIGTERMで shutdown()/force_flush() |
| ツールの失敗がエラーとして出ない | isError: true で返ったのに、スパンのステータスだけで絞り込んでいる |
error.type = tool_error で絞り込む |
mcp.session.id が空 |
2026-07-28版でプロトコルのセッションが廃止された | トレースIDか呼び出し元IDで集計する |
| SDKを上げたらダッシュボードが壊れた | 属性名の変更(例:C#では mcp.tool.name が gen_ai.tool.name に) |
バージョンを固定し、SDKと一緒にクエリを直す |
11. NodeFlareならこう解決できる
NodeFlareは、GitHubにあるMCPサーバー(stdioのものも含む)を、認証付きのStreamable HTTPのURLにして動かすMCP専用のホスティングです。この記事で挙げた課題に、NodeFlareのドキュメントと料金ページに書かれている機能で次のように対応できます。
- 見えないブリッジとエッジの区間(落とし穴2):NodeFlareのプロキシを通るリクエストは、すべてリクエストログに記録されます。項目は
mcp_method・tool_name・http_status・outcome・duration_ms・req_bytes/res_bytes・caller_kind・client_ip・user_agent・session_id・error_messageです。計測を入れていないstdioサーバーでも、呼び出しごとのサーバー側の所要時間がわかります。ログはツール名、エラーメッセージ、メソッド、outcome、IPで検索できます。 - 失敗の種類の区別(4章):
outcomeでokとscope_denied・rate_limited・budget_exceededを分けられるので、プラットフォーム側で止まった呼び出しとツールのエラーを取り違えません。 - 引数がトレースストアに残る問題(落とし穴6):リクエストログに残るのは引数のキー名(
arg_keys)だけで、値は記録されません。 - ブリッジの後ろのstdioサーバー(落とし穴1・2):NodeFlareのstdioアダプターがサーバーを子プロセスとして起動し、JSON-RPCのIDを振り直して複数のクライアントで1つの子プロセスを共有します。クラッシュ時は1秒から30秒までの指数バックオフで再起動します。
- トレースに出るコールドスタート(5章):アイドルになったサーバーはスナップショットを取って停止し、次のリクエストで1秒未満で復元されます。Always-On(Pro+)なら温まったレプリカを常に残すので、コールドスタートは起きません。
- 自前のスパンの送信(落とし穴3・5):
OTEL_EXPORTER_OTLP_HEADERSなどの環境変数は暗号化して保存され、VMの起動時にだけ注入されます。ビルド引数、イメージレイヤー、ログには書かれません。外向き通信の制御には実際の送信先を記録するobserveモードがあるので、コレクターのホスト名を許可リスト(最大100件)に入れてからenforceに切り替えられます。
自分でやる必要があること:NodeFlareのドキュメントには、OpenTelemetryでのエクスポートやトレースの取り込みについての記載はありません。ログの保存期間はFreeが7日、ProとTeamが30日です(Freeで表示できるのは直近1時間)。完全な分散トレースが必要なら、6章のSDKの設定を残し、自分のコレクターにスパンを送ってください。
始め方:ダッシュボードにサーバーのGitHubのURLを貼ってデプロイし、クライアントから https://<your-server>.nodeflare.tech/mcp に Authorization: Bearer <YOUR_API_KEY> で接続します。Freeプランには、MCPサーバー1つと月30 GB-hoursのコンピュートが含まれます。1サーバーまで無料でNodeFlareを試す →
12. FAQ
MCPのツールコールをOpenTelemetryでトレースするには?
MCPクライアントとMCPサーバーの両方のプロセスに、OpenTelemetryのSDKとOTLPエクスポーターを登録します。公式のPython SDK v2、TypeScript SDK v2、FastMCPはスパンの作成と params._meta でのコンテキスト伝搬をすでに行うので、追加するコードはたいてい登録部分だけです。
MCP Python SDKはOpenTelemetryに対応している?
対応しています。MCP Python SDK v2は、MCPServer を作った時点から、処理するすべてのメッセージで SERVER スパンを出します。依存しているのは opentelemetry-api だけなので、opentelemetry-sdk とエクスポーターを入れるまでスパンは何もしません。
MCP TypeScript SDKはOpenTelemetryに対応している?
対応しています。TypeScript SDK v2では、Client・McpServer・Server がスパンと、mcp.client.operation.duration・mcp.server.operation.duration のメトリクスを出します。OpenTelemetryのSDKを登録するまでは何も記録されず、無効にするには openTelemetry: false を渡します。
MCPではトレースコンテキストをどう伝搬する?
リクエストの params._meta に、SEP-414が定めた接頭辞なしのキー traceparent・tracestate・baggage で入れます。サーバーはそれを取り出して自分のスパンの親にするので、Streamable HTTPでもstdioでも同じように動きます。
MCPのOpenTelemetryセマンティック規約とは?
MCPのスパンとメトリクスについてのOpenTelemetryのルールです。スパン名は {mcp.method.name} {target}、属性は mcp.method.name・gen_ai.tool.name・mcp.protocol.version など、所要時間は秒単位のヒストグラムで記録します。ステータスはDevelopmentで、現在はsemantic-conventions-genaiリポジトリで管理されています。
MCPのクライアントとサーバーのスパンが別々のトレースになるのはなぜ?
多くの場合、クライアントのプロセスにOpenTelemetry SDKが登録されておらず、_meta に traceparent が書き込まれていないためです。params を書き換えて _meta を落とすプロキシが原因のこともあります。
ブリッジの後ろで動くstdioのMCPサーバーもトレースできる?
できます。サーバーが計測付きのSDKを使い、OTEL_* の環境変数を受け取り、stdoutではなくOTLPで送っていれば大丈夫です。ブリッジ自体は通常MCPのスパンを出さないので、そこで使った時間はエッジとサーバースパンの差として現れます。
MCPのトレースにツールの引数を残すべき?
既定では残しません。gen_ai.tool.call.arguments と gen_ai.tool.call.result の属性は「機密情報を含みうる」ためOpt-Inになっていて、トレースストアのアクセス管理は監査ログほど厳しくないことが多いからです。
MCPのトレースでツールのエラーを見るには?
error.type で絞り込みます。ツールが isError: true を返した場合、規約では error.type を tool_error にすべき(SHOULD)とされ、JSON-RPCのエラーではエラーコードが値になります。-32602 などの一部のコードは、所要時間のメトリクスではエラーとして数えません。
トレースを入れるとMCPサーバーは遅くなる?
スパンの作成は軽く、SDKがなければ何もしません。送信はバッチ処理で裏側で行われるので、コストは主にバッファ用のメモリと外向きの通信量です。どちらもサンプリングで抑えられます。
まとめ
ホストしたMCPサーバーのトレースは、今ではほとんどが設定作業です。公式SDKとFastMCPは既定でMCPのスパンを作り、SEP-414に沿って params._meta で traceparent を運びます。ホスティングで加わるのは3つの死角です。スパンを出さないブリッジやプロキシの区間、stdoutに絶対に書いてはいけないstdioサーバー、スケールゼロで消えるスパンです。エクスポーターを登録し、終了時に送り切り、コレクターへの外向き通信を許可したうえで、入れ子のスパンの所要時間から区間ごとのレイテンシを読みます。規約はDevelopmentなので、バージョンは固定しておきます。
参考資料
- OpenTelemetry semantic conventions for MCP(semantic-conventions-genai)
- SEP-414: Document OpenTelemetry Trace Context Propagation Conventions
- The 2026-07-28 MCP Specification Release Candidate
- MCP Python SDK: OpenTelemetry
- MCP TypeScript SDK v2: OpenTelemetry
- FastMCP: Telemetry
- Logfire: MCP integration
- MCP C# SDK PR #1139: Align telemetry with OpenTelemetry MCP semantic conventions
- NodeFlare ドキュメント
