mcp-agent-trace-inspector

MCP エージェントトレースインスペクター

npm mcp-agent-trace-inspector パッケージ

エージェントのワークフローをローカル優先で可視化する、MCP ネイティブのツールです。ツール呼び出し、プロンプトの変換、レイテンシ、トークン数をすべてローカルの SQLite データベースに記録します。クラウドアカウントも API キーも不要で、トレースがマシンの外に送信されることはありません。汎用 LLM プロキシに後付けしたものではなく、MCP 専用に構築されています。

ツールのリファレンス | 設定 | コントリビューション | トラブルシューティング | 設計原則

主な機能

• ツール呼び出しのトレース：ワークフロー内の各ステップについて、入力、出力、レイテンシ、トークン使用量を記録します。
• 永続ストレージ：トレースはセッションを再起動しても保持されます。外部依存関係はなく、ローカルの SQLite に保存されます。
• HTML ダッシュボード：ステップのタイムラインを操作できる、自己完結型の単一ファイルダッシュボードを生成します。
• トークンコストの見積もり：設定可能なモデル料金表を使い、API 呼び出しなしでトレースごとの USD コストを算出します。
• トレースの比較：2 つのトレースを並べて差分を取り、プロンプトやツールの変更による影響を測定します。
• 低オーバーヘッド：ステップごとの追加時間は 5ms 未満で、ボトルネックになることはありません。

LangSmith / AgentOps ではなく、これを選ぶ理由

	mcp-agent-trace-inspector	LangSmith / AgentOps
データの保存先	ローカルの SQLite。マシンの外に出ることはありません	クラウド上。トレースは外部サーバーに送信されます
セットアップ	npx のワンライナーで設定不要	アカウント登録、API キー、SDK による計装
MCP 対応	ネイティブ対応。ツール呼び出しを主要なステップとして記録	汎用 LLM プロキシ。MCP の構造は不透明です
実行差分	compare_traces による差分機能を内蔵	別料金の機能、または手動エクスポートが必要
コストの見積もり	オフラインの tiktoken と設定可能な料金表を使用	プロキシ経由のライブ API トラフィックが必要
オーバーヘッド	1 ステップあたり <5ms	イベントごとにネットワーク往復が発生

トレースに機密性の高いツール出力、独自のプロンプト、またはデバイス上に保持する必要があるデータが含まれる場合は、このツールが適しています。チーム横断でトレースを共有したい場合や、マネージド SaaS が必要な場合は、LangSmith をご利用ください。

免責事項

mcp-agent-trace-inspector は、ツール呼び出しの入力と出力をローカルの SQLite データベースに保存します。トレースには、ツールに渡された、またはツールから返された機密情報が含まれる場合があります。ダッシュボードをエクスポートして共有する前に、トレースの内容を確認してください。トレースが自動送信されることはありません。オプションでアラート用 Webhook を利用できます。

必要条件

• Node.js v22.5.0 以降。
• npm。

はじめに

MCP クライアントに次の設定を追加します。

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-agent-trace-inspector@latest"]
    }
  }
}

カスタムの保存先パスを設定するには、次のようにします。

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-agent-trace-inspector@latest",
        "--db=~/traces/my-project.db"
      ]
    }
  }
}

MCP クライアントの設定

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

最初のプロンプト

すべてが正常に動作していることを確認するため、MCP クライアントに次の内容を入力します。

Start a trace called "test-run", then list the files in the current directory, then end the trace and show me the summary.

クライアントには、ステップ数、合計トークン数、レイテンシを示す概要が返されます。

ツール

トレースのライフサイクル（3 つのツール）

• trace_start — 新しいトレースを開始します。後続の呼び出しに使用する trace_id を返します
• trace_step — 1 回のツール呼び出しのステップを記録します（入力、出力、オプションのトークン数とレイテンシ）
• trace_end — トレースを完了としてマークします

インスペクション（4 つのツール）

• list_traces — 保存されたトレースを、名前、ステータス、タイムスタンプとともに一覧表示します
• get_trace_summary — トレースの合計トークン数、ステップ数、レイテンシ、コストの見積もりを表示します
• compare_traces — 2 つのトレースを並べて差分を表示します（ステップ数、トークン数、レイテンシ）
• extract_reasoning_chain — トレースから推論／思考ステップのみを抽出します

エクスポート（3 ツール）

• export_dashboard — レイテンシのウォーターフォールを含む、自己完結型の単一ファイル HTML ダッシュボードを生成します
• export_otel — 1 つまたはすべてのトレースを OpenTelemetry OTLP JSON スパン形式でエクスポートします
• export_compliance_log — コンプライアンス監査ログを JSON または CSV でエクスポートします。オプションで日付範囲を絞り込めます

運用（3 ツール）

• configure_alerts — レイテンシ、エラー率、またはコストに関するアラートルールを設定します。Slack または汎用 Webhook に通知します
• set_retention_policy — トレースを保持する日数を設定します（メモリ内の設定です。apply_retention の前に呼び出す必要があります）
• apply_retention — 設定されたしきい値より古いトレースをアーカイブし、しきい値の 2 倍を過ぎたトレースを削除します

設定

--db / --db-path

トレースの保存に使用する SQLite データベースファイルのパスです。

型：string デフォルト：~/.mcp/traces.db

--retention-days

N 日より古いトレースを自動的に削除します。無効にするには 0 を指定します。

型：number デフォルト：0

--pricing-table

カスタムモデル料金（1,000 トークンあたりの米ドル）を含む JSON ファイルのパスです。組み込みの料金表を上書きします。

型：string

--no-token-count

tiktoken ベースのトークン数カウントを無効にします。トレースにトークン使用量のメトリクスが含まれなくなります。

型：boolean デフォルト：false

JSON 設定の args プロパティでフラグを渡します。

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-agent-trace-inspector@latest", "--retention-days=30"]
    }
  }
}

設計原則

• 追記専用のトレース：記録後のステップは変更できません。信頼性には完全性が必要です。
• ローカル優先：すべてのコア機能はネットワーク接続なしで動作します。
• ポータブルなダッシュボード：HTML エクスポートは常に単一ファイルで、表示にサーバーは不要です。

検証

新しいバージョンを公開する前に、MCP Inspector でサーバーを検証し、すべてのツールが正しく公開され、プロトコルのハンドシェイクが成功することを確認してください。

対話型 UI（ブラウザーを開きます）：

npm run build && npm run inspect

CLI モード（スクリプト実行／CI 向け）：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_traces

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_traces --tool-arg key=value

公開前に実行し、ツール登録とランタイム起動に関するリグレッションを検出してください。

コントリビュート

コントリビューションのガイドライン全体については、CONTRIBUTING.md をご覧ください。

npm install && npm test

MCP レジストリとマーケットプレイス

このプラグインは以下で利用できます。

• MCP Registry
• MCP Market

mcp-agent-trace-inspector を検索してください。