Argosvix — AI agent observability (87 tools)

@argosvix/mcp-server

Argosvix MCP サーバーを使うと、AI エージェント（Claude Desktop、Cursor、Codex CLI、カスタム MCP クライアント）が会話から直接、LLM のオブザーバビリティデータを照会、管理、操作できます。stdio（サブプロセス）と HTTP（リモート／セルフホスト）の両方のトランスポートに対応しています。

提供機能： 89 個のツール（一般公開 86 個＋顧客アカウントでは 403 を返す内部操作ツール 3 個）／3 個のリソース／8 個のリソーステンプレート／3 個のプロンプト。ヘルスおよび異常検知エンドポイント（get_account_health／detect_anomaly／propose_alert_rules／classify_calls_batch／propose_eval_criteria）に加え、ランタイム制御プレーン（予算ゲート／ポリシーゲート／人間による承認ゲート）により、エージェントは監視と操作の両方を行えます。リリース履歴は npm で確認できます。

導入理由

すでに @argosvix/sdk または Python SDK を通じて LLM を呼び出しているなら、Claude／Cursor に次のような質問をしてみましょう。

• 「過去 24 時間の OpenAI のコストはいくらでしたか？」
• 「現在、どのアラートが発火していますか？」
• 「今日の最も高額な呼び出しを 20 件表示してください。」

ダッシュボードのタブを切り替える必要はありません。エージェントがこの MCP サーバーを介して、Argosvix API キーを使ってデータを取得します。

インストール

ワンクリック（キーなしで起動します。自身のアカウントでツールを使うには、後から ARGOSVIX_API_KEY を設定してください）：

Claude Code ユーザーは、代わりに argosvix plugin をインストールできます。サーバーとセットアップスキルが含まれています。

/plugin marketplace add argosvix/claude-plugin
/plugin install argosvix@argosvix
/reload-plugins

手動インストール：

npm install -g @argosvix/mcp-server

設定（Claude Desktop）

Claude Desktop の設定を編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_..."
      }
    }
  }
}

Claude Desktop を再起動します。89 個すべてのツールが argosvix__ プレフィックス付きで表示されます（例：argosvix__query_calls、argosvix__get_account_health、argosvix__create_budget_gate）。

まだ API キーをお持ちでない場合：サーバーは ARGOSVIX_API_KEY がなくても、イントロスペクション専用モードで起動します。提供機能を確認できるよう、89 個すべてのツールが一覧表示されます。また、2 つの公開データツール（get_synth_daily／get_daily_readthrough — Argosvix 独自の日次 AI ダイジェストと OSS のリードスルー）は、キーなしで利用できます。それ以外のツールを呼び出すと、https://dashboard.argosvix.com/api-keys でキーを取得する手順が返されます。

公開データツールに関する注意：これらのツールはデフォルトの full プロファイルにのみ含まれます（ARGOSVIX_MCP_PROFILE=core には含まれません）。また、ほかのすべてのツールと同様に ARGOSVIX_API_BASE に従います。サーバーの接続先を別のベース URL に設定すると、認証なしでその接続先から /v1/synth-daily／/v1/readthrough を取得します。

設定（Cursor）

~/.cursor/mcp.json を編集します。

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_..."
      }
    }
  }
}

ツールプロファイル（ARGOSVIX_MCP_PROFILE）

デフォルトのプロファイルは full（89 個すべてのツール）です。MCP クライアントのコンテキスト予算が限られている場合は、ARGOSVIX_MCP_PROFILE=core を設定すると、日常的な操作に必要な 11 個の基本ツールのみが公開されます。

query_calls · aggregate_calls · get_cost_summary · get_percentiles · get_account_health · detect_anomaly · list_alerts · create_alert · silence_alert · unsilence_alert · get_deployed_prompt

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_...",
        "ARGOSVIX_MCP_PROFILE": "core"
      }
    }
  }
}

stdio と HTTP の両トランスポートで動作します。不明な値を指定した場合は、標準エラー出力に警告を出して full にフォールバックします。

説明言語（ARGOSVIX_MCP_LANG）

tools/list／resources/list／ prompts/list が返すツール、リソース、プロンプトの説明は、デフォルトでは英語です。ARGOSVIX_MCP_LANG=ja を設定すると、元の日本語の説明が返されます。未設定または不明な値の場合は en にフォールバックします（不明な値の場合は stderr に警告が表示されます）。ツール名、入力スキーマ、動作はどちらの言語でも同じで、人間／エージェント向けの説明文のみが変わります。

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_...",
        "ARGOSVIX_MCP_LANG": "ja"
      }
    }
  }
}

stdio と HTTP の両方のトランスポートで動作します。

ツール（抜粋）

ツールは全部で89個あり、全リストは tools/list で返されます。主要な読み取り／書き込み機能の一部を紹介します。

ツール	用途	種類
query_calls	最近の LLM 呼び出し記録。プロバイダー／モデル／時間範囲で絞り込み可能	読み取り
get_cost_summary	プロバイダーまたはモデルごとのコスト／呼び出し数／トークン数の集計	読み取り
list_alerts	設定済みアラートと最近のトリガー状態	読み取り
get_alert	特定のアラートの詳細と最近のトリガー履歴	読み取り
list_alert_events	アカウント全体のアラートトリガーイベント（通知履歴）	読み取り
silence_alert	特定のアラートをミュート（一時的に通知を停止。デフォルトは24時間）	書き込み
unsilence_alert	ミュート済みアラートの通知を再開	書き込み
create_alert	新しいアラートルールを作成（コスト／エラー率／レイテンシ／異常）	書き込み
acknowledge_alert	特定のアラートイベントを確認済みとしてマーク（冪等。ミュートとは独立）	書き込み

リソース

リソースは、明示的なツール呼び出しなしで AI エージェントがコンテキストに取り込める、読み取り専用のスナップショットを公開します。

URI	用途
argosvix://account	プラン／クォータ／当月の記録使用量／保持期間のスナップショット（機密情報なし、Bearer のみ）
argosvix://alerts/active	現在有効なアラートのスナップショット
argosvix://cost/today	過去24時間のプロバイダー別コスト内訳（response.total を含む）

リソーステンプレート

リソーステンプレートを使うと、エージェントは既知の ID から動的な URI を構築できます。サーバーはバックエンドでの PK 検索によってアカウントのスコープを適用するため、別のアカウントの ID では404が返されます。

URI テンプレート	用途
argosvix://calls/{id}	単一の LLM 呼び出し記録（プロバイダー／モデル／トークン数／コスト／レイテンシ／タグ／エラー／trace_id）。query_calls の結果にある任意の ID を指定します。
argosvix://alerts/{id}	単一のアラートルール（名前／種類／しきい値／期間／channelKinds／sleep／有効状態／silencedUntil）と最近のトリガーイベント20件。list_alerts の結果にある任意の ID を指定します。channelTargets（通知先）は構造上除外されます。
argosvix://traces/{id}	単一のトレース（すべてのスパンを trace_id ごとにグループ化したもの。LLM 呼び出しの時系列）。スパンは先頭の50件のみ（LLM コンテキストの予算上限）。errorDetails／requestMeta は構造上除外されます。query_calls の結果にある任意の traceId を指定します。

プロンプト

プロンプトは、スラッシュコマンドとしてユーザーが起動できる再利用可能なテンプレートです。

名前	用途
cost_review	24時間／7日間／30日間のコスト推移を比較し、異常にフラグを付ける
alert_audit	現在のアラートルールを監査し、改善案を提示する
incident_triage	最近のエラー／レイテンシの異常を調査する（デフォルトでは過去24時間）

サブスクリプション（= v0.10、stdio のみ）

resources.subscribe ケイパビリティは stdio モードで宣言されます。クライアントは以下の静的リソースを1つ以上サブスクライブできます。サーバーはサブスクライブされた各リソースを60秒ごとにポーリングし、コンテンツのハッシュが変化した場合に notifications/resources/updated を送信します。

サブスクライブ可能な URI（argosvix://calls/{id} などのリソーステンプレートはサブスクライブできません）：

• argosvix://account
• argosvix://alerts/active
• argosvix://cost/today

HTTP トランスポート（= argosvix-mcp --http）では subscribe を宣言せず、サブスクライブリクエストを拒否します。リクエストごとのステートレスモードでは、サブスクリプションの一覧を保持したり、サーバー起点の通知を送信したりできないためです。ライブ更新には stdio を使用してください。

listChanged は意図的に宣言していません。サーバーの稼働中、リソース一覧は固定されるためです。

実装上の注意点（v0.10）：

• 単一実行ガード：ポーリングサイクルが遅れている場合、次のサイクルは並行して開始されません（readResource の呼び出しは重複しません）。
• サブスクライブ解除／シャットダウンの競合：URI ごとにフェッチ前と通知前に再確認し、さらに isShuttingDown フラグを使用することで、サイクルの途中で削除された URI に対する通知が送信されないようにしています。
• エラー処理：フェッチと通知の失敗は無視されます（次のサイクルで再試行します）。ARGOSVIX_MCP_DEBUG=1 の場合、サーバーは { uri, errorClass } を stderr に記録します。上流のペイロードテキストが漏洩しないよう、エラーメッセージは意図的に記録しません。
• テスト：150 件のユニットテスト（重複実行を防ぐ単一実行ガード、サブスクライブ解除／シャットダウンの競合、無効な URI → McpError(InvalidParams)、Axis 4 Tier 1 ディスパッチャーのカバレッジを含む）

プライバシー

MCP サーバーは、API キーを使用して https://ingest.argosvix.com にクエリを送信します。プロンプトや補完内容が外部に送信されることはありません。送信されるのはメタデータ（トークン、コスト、レイテンシ、モデル名、設定したタグ）のみです。

開発

npm install
npm run build
npm test

ライセンス

MIT © Yuto Makihara (Argosvix)。LICENSE を参照してください。

HTTP トランスポート

サーバーは HTTP 経由のリモート MCP エンドポイントとしても実行できます。API キーをリクエストごとに指定するセルフホストやマルチテナントのシナリオに適しています。

# Start HTTP transport (default: 127.0.0.1:3000)
argosvix-mcp --http

# Bind to all interfaces with custom port + allowed Host headers
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_PORT=4000 \
MCP_HTTP_ALLOWED_HOSTS="mcp.example.com,localhost:4000" \
  argosvix-mcp --http

エンドポイント

• GET /health → サーバー名／バージョンを含む 200 OK（認証不要）
• POST /mcp → MCP JSON-RPC エンドポイント（認証必須）

クライアントの例

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer argk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

認証モデル

各リクエストには、有効な Argosvix API キー（https://dashboard.argosvix.com/api-keys で発行）を含む Authorization: Bearer <api-key> が必要です。サーバーはステートレスモード（セッション ID なし）を使用するため、各リクエストは独立しており、異なるキーを指定できます。

セキュリティ上の注意

• デフォルトのバインド先は 127.0.0.1（ローカルホストのみ）です。外部に公開するには MCP_HTTP_HOST=0.0.0.0 を使用できますが、本番環境ではリバースプロキシと TLS を併用してください。
• ローカルホストにバインドする場合、既知のローカルホスト許可リストと Host ヘッダーを照合して、DNS リバインディングを防止します。ローカル以外にバインドする場合は、MCP_HTTP_ALLOWED_HOSTS（カンマ区切り）を使用してください。
• リクエスト本文のサイズ上限は1 MiBです。

デバッグログ

本番環境のログ集約システムにバックエンド内部のペイロードが記録されないよう、バックエンドエラーのレスポンス本文はデフォルトではログに記録されません。デバッグ時にレスポンス本文をそのままログに記録するには、次のようにします。

ARGOSVIX_MCP_DEBUG=1 argosvix-mcp           # stdio mode
ARGOSVIX_MCP_DEBUG=1 argosvix-mcp --http    # HTTP mode

環境変数を設定しない場合、エラーログには path、status、x-request-id のみが含まれます。