あなたのエージェントは一晩中稼働しました。ワークフローの途中で1つが失敗しました。3つのツール呼び出しは成功しました。2つは成功しませんでした。どの順番だったのかは分かりません。
実際に、何をデバッグする必要があるのでしょうか？
ほとんどのMCP構成での正直な答えは「それほど多くありません」です。サーバーログは乏しいです。クライアント側のトレースはアプリケーション固有です。監査証跡は存在しません。そして、MCPのやり取りはプロトコル層を通じて行われるため、標準的なAPIデバッグツールはきれいに適用できません。
これが、本番環境でのMCP導入における可観測性のギャップです。そして、それはマルチエージェント、マルチサーバーのアーキテクチャへスケールするほど増幅します。
MCPの可観測性が異なる理由
標準的なAPIの可観測性は解決済みの課題です。HTTP層を計測し、リクエスト／レスポンスのペアを取得し、ログスタックに出力して、問題が起きたときにクエリできます。
一方でMCPは、次のような形でモデルを変えてしまいます：
プロトコルのラッピング。 ツール呼び出しはJSON-RPCまたはHTTPで行われますが、単一のAPIエンドポイントよりもセマンティクス（意味論）が豊かです。ツールの呼び出しは、サーバー内部で複数の操作を連鎖できます。観測可能な境界が内側へ移動します。
資格情報の不透明さ。 呼び出し側のエージェントは、サーバーがどの上流資格情報を使ったのか分からないかもしれません。複数の資格情報モードが有効（auto／bring-your-own／server-managed）である場合、監査証跡は「どのモードが発火したのか」と「どのアイデンティティで行われたのか」を記録する必要があります。
複合的なアクションの表面。 ステートレスなAPIエンドポイントとは異なり、MCPのツールは副作用を引き起こし、それが積み上がっていきます。create_issueツールをループして実行するエージェントは、複数のイシューを作成します。可観測性とは単に「呼び出しが成功したかどうか」ではありません。「下流で何件の影響が起きたのか」と「それらは回復可能なのか」が重要になります。
セッション状態。 MCPサーバーはセッションをまたいで状態を保持します。つまり、可観測性には個々の呼び出しだけでなく、状態遷移の記録が必要です。
4つの監査質問
本番環境のMCPでは、インシデント発生後にあなたの可観測性スタックが答えるべき4つの質問があります：
1. 誰が、どのツールを呼んだのか？
- どのエージェントのアイデンティティ（またはマルチテナント構成ではユーザー）
- どのツール名とバージョン
- いつ（タイムスタンプ）で、どの入力パラメータで
2. どの資格情報が使われたのか？
- 有効だった認証モード
- 呼び出された上流プロバイダ
- その操作に対して資格情報が適切にスコープされていたかどうか
3. 何が起きたのか？
- 返された出力、またはエラー
- レイテンシとリトライの挙動
- 操作が冪等かどうか（安全に再実行できるか）
4. どんな副作用が発生したのか？
- サーバーが行った下流API呼び出し
- 作成・更新・削除されたリソース
- 実行がメータリングされている場合の発生コスト
この4つの質問への答えがなければ、インシデント対応は推測になります。
実際に機能するログのパターン
構造化されたツール呼び出しログ
ツール呼び出しに必要最小限のログエントリ：
{
"event": "tool_call",
"tool": "create_file",
"server": "filesystem-server-v1.2",
"session_id": "ses_abc123",
"agent_id": "agent_xyz789",
"timestamp": "2026-04-03T14:32:01Z",
"input_summary": { "path": "/workspace/output.txt", "content_length": 4096 },
"outcome": "success",
"duration_ms": 142,
"idempotent": false,
"side_effects": [ "file_created"]
}
idempotentフラグは重要です。タイムアウト後にリトライが発生したとき、そのツールが再実行しても安全なのかどうかを知ることは、復旧ロジックを根本から変えます。
エラーの分類
生のエラーストリングは、自動復旧には役に立ちません。エラーログを構造化してください：
{
"event": "tool_error",
"tool": "send_email",
"error_class": "auth_expired",
"error_code": "TOKEN_REVOKED",
"recoverable": true,
"recovery_action": "reauth",
"retry_safe": false
}
recoverableは、オーケストレータに対して復旧を試みるべきかどうかを伝えます。retry_safeは、生のリトライが安全か、それとも副作用の重複リスクがあるかを伝えます。
セッションレベルの監査証跡
呼び出しごとのログに加えて、セッションのサマリを維持してください：
{
"session_id": "ses_abc123",
"started_at": "2026-04-03T14:30:00Z",
"tool_calls": 12,
"successful_calls": 10,
"failed_calls": 2,
"credentials_used": ["fs_local", "openai_byok"],
"side_effects_summary": {
"files_created": 3,
"api_calls_made": 8,
"spend_incurred_usd": 0.042
},
"terminal_state": "partial_success",
"recovery_status": "pending"
}
このセッションの要約は、ポストインシデント分析に必要なものであり、呼び出しレベルの生の詳細ではありません。
コスト配賦（アトリビューション）を複数ツール・エージェントループで行う
エージェントのワークフローで複数のMCPサーバーが関与する場合、支出（spend）の配賦は、現場の実運用上の重要な懸念になります：
- どのツールが、どのAPIのクレジットを消費したか
- どのエージェント、セッション、またはユーザーが、どのコストを負担したか
- ツールごとの支出が、想定範囲内かどうか
セッション単位のトークン消費（token-burn）ガバナーが、暴走した支出を防ぎます：
class SpendGovernor:
def __init__(self, session_id: str, limit_usd: float):
self.session_id = session_id
self.limit = limit_usd
self.spent = 0.0
def check(self, estimated_cost: float) -> bool:
if self.spent + estimated_cost > self.limit:
raise SpendLimitExceeded(
f"Session {self.session_id}: limit ${self.limit:.2f} would be exceeded"
)
return True
def record(self, actual_cost: float):
self.spent += actual_cost
ガバナーがない場合、有料ツールでリトライの嵐に遭遇したエージェントループは、オーケストレーターが気づく前に実際のお金を燃やしてしまう可能性があります。
MCPチェーンにおける部分的な失敗をデバッグする
最も難しいMCPデバッグのシナリオ：ツール呼び出しの連鎖の途中で、いくつかは成功し、いくつかは失敗した状態です。
回復戦略は、次の2つの質問に依存します：
失敗の直前の正確な状態チェックポイントを特定できますか？ できるなら、最後に成功した呼び出しから再開できます。できないなら、ワークフロー全体を再起動する必要があるかもしれません。
失敗前の呼び出しは巻き戻し可能ですか？ できるなら、完全なロールバックが可能です。できないなら、副作用は恒久的です—その場合は、前に進むしかありません。
この2つの質問に明確に答えられるように、ワークフローを設計してください：
- 各成功したツール呼び出しの後に状態チェックポイントをログに記録する
- 各ツール呼び出しに、その巻き戻し可能性クラスをタグ付けする：
no_effect | reversible | permanent - 失敗時は、再開する前の最新の状態チェックポイントを問い合わせる
- 1つのセッションで完了した呼び出しが、リトライセッションでも可視であると決めつけない（特に状態を持つサーバーでは）
監視性（Observability）においてANスコアが捉えるもの
production readiness checklist におけるRhumbの監査可能性（auditability）次元は、これを直接測定します。主要なシグナル：
- 構造化されたエラー： サーバーは、リカバリのヒント付きで機械が解析できるエラーを返すのか、それとも生の文字列なのか？
- 冪等性の保証： ツール呼び出しは、サイドエフェクトの重複なしに安全にリトライできるのか？
- 状態の検証： 副作用が実際に発生したかどうかを確認する仕組みはあるのか？
- 資格情報の配賦： サーバーは、特定の呼び出しでどの認証モードが使われたかを公開しているのか？
高スコアのサーバー（8.0以上）は、4つすべてをカバーしている傾向があります。5.0未満のサーバーには、多くの場合それがありません。このギャップが最も問題になるのは、午前2時です。エージェントループが途中までしか進まず、手作業の後片付けとの間にあるのが監査証跡だけ、という状況でのことです。
監視性チェックリスト
MCPサーバーを本番環境に昇格させる前に：
- [ ] ツール呼び出しログは、ツール名、入力概要、結果、および所要時間を記録します
- [ ] エラーログには、エラーのクラス、復旧のヒント、リトライ安全フラグが含まれます
- [ ] セッション単位の監査証跡は、すべての副作用と支出を追跡します
- [ ] 支出ガバナーは有効であり、セッションごとの上限が設定されています
- [ ] ステートのチェックポイント手法が実装されているため、一部の失敗が起きても再起動ではなく再開できます
- [ ] チェーン内の各ツールには、その可逆性クラスがタグ付けされています
- [ ] 認証情報モードのログ記録が有効です — 各呼び出しがどのアイデンティティのもとで実行されたかを把握できます
本番環境で「成熟している」と感じられるサーバーは、必ずしも最も高機能なサーバーとは限りません。デバッグを簡単にしてくれるサーバーこそが、それに当たります。
本番環境で安全なMCPデプロイに関するシリーズの一部:
