prism

Prism

ステートレスな MCP ゲートウェイです。AI クライアントと MCP サーバーの間に入り、JSON-RPC をそのまま中継し、すべての呼び出しを OpenTelemetry スパンに変換します。スパンは、選択した 任意の エンドポイントに OTLP で送信されます。データベースも、アカウントも、プロビジョニングも不要です。詳しい仕様は docs/PRISM.md をご覧ください。

ダッシュボードを最速で稼働させる方法： telinea.terradev.cloud で無料キーを取得し、送信先を 1 つ設定すれば、数秒以内にすべてのスパンが Telinea に表示されます。

実行

pip install -r requirements.txt

# Zero-config dev: spans print to stdout.
PRISM_UPSTREAM_ALLOW='*' \
PRISM_ALLOW_INSECURE_HOSTS='localhost,127.0.0.1' \
uvicorn prism.main:app --port 8080

スパンの送信先

パイプラインは 1 つ、送信の基本処理も 1 つです：PrismSpan → Serializer → Dispatcher。 Prism が認識する送信先スキームは 4 種類で、バックエンドについては関知しません。

• https:// / http:// — シリアライズしたスパンを任意の OTLP エンドポイントに POST します。Grafana、Honeycomb、コレクター、Telinea など、バックエンドのドキュメントでエンドポイントと認証ヘッダーを確認して、2 つのフィールドに入力すれば完了です。
• file:// — ローカルパスに JSONL を追記します。アカウントもネットワークも不要です。
• stdout:// — 開発向けに読みやすい形式で出力します。
• multi://a,b — 名前付き送信先にファンアウトします。障害はそれぞれ独立して処理されます。

~/.prism/config.toml（または ./prism.toml、または PRISM_CONFIG）で設定します。

[prism]
destination = "telinea"

[destinations.telinea]
endpoint = "https://api.terradev.cloud/telinea/v1/ingest"
format = "telinea"
headers = { "Authorization" = "Bearer tl_your_key" }

形式：otlp_json（デフォルト — 業界標準のワイヤ形式）、otlp_proto（pip install opentelemetry-proto が必要）、jsonl、telinea（Telinea 取り込み用のネイティブエンベロープ）。

各フィールドには環境変数による上書き設定があります。シークレットをディスクに保存する必要はありません。

PRISM_DESTINATION=telinea
PRISM_DESTINATION_TELINEA_HEADERS_AUTHORIZATION="Bearer tl_..."

ホスト型モード："Authorization" = "Bearer {token}" を設定すると、{token} はスパンごとに呼び出し元のベアラートークンに置き換えられます。各ユーザーのスパンは、それぞれのアカウントに送られます。

配信：バッファーに蓄積し、5 秒ごと、または 512 スパンごとにフラッシュします。すべてのバックエンドで 429 に対する Retry-After を尊重します。失敗したバッチはデッドレターリングバッファー（10k スパン）に格納され、バックオフ後に再試行されます。シャットダウン時には、処理中のスパンを排出し、デッドレターバッファーを ~/.prism/deadletter.jsonl に書き込みます。次回の起動時に再生されます。ファイア・アンド・フォーゲット方式のため、Prism がフラッシュを理由にチャットセッションをブロックすることはありません。

クライアント設定

連携に必要なのは、URL の変更とヘッダーの追加だけです。

{
  "mcpServers": {
    "acme-prod": {
      "url": "https://prism-mcp.terradev.cloud/mcp",
      "headers": {
        "Authorization": "Bearer tln_live_…",
        "X-Prism-Upstream": "http://localhost:9000/mcp",
        "X-Prism-Project": "acme-prod",
        "X-Prism-Env": "development"
      }
    }
  }
}

• X-Prism-Upstream — 実際の MCP サーバーです。PRISM_UPSTREAM_ALLOW と一致する必要があります。
• X-Prism-Upstream-Authorization — Authorization として上流に転送されます。
• X-Prism-Capture — none（デフォルト）| args | args,results。機密情報はマスキングされます。
• X-Prism-Sample — 0.0～1.0。セッションごとに 1 回サンプリングされます。

ヘッダーに対応していないクライアントでは、パスに上流を指定できます。 POST /mcp/u/{base64url(upstream)}。

レジストリ（Smithery など）

レジストリからのインストールではカスタムヘッダーを設定できないため、設定はクエリパラメーターで渡します。すべての X-Prism-* オプションには、対応するクエリパラメーターがあります。

/mcp?upstream=https://mcp.acme.dev/mcp&api_key=tln_live_…&project=acme&env=prod

• upstream → X-Prism-Upstream（または、上流が 1 つのデプロイでは PRISM_DEFAULT_UPSTREAM を設定します）
• api_key / token → Authorization / X-Api-Key
• upstream_authorization → X-Prism-Upstream-Authorization
• project、env、role、capture、sample → 対応する X-Prism-*

このディレクトリの smithery.yaml は、セルフホスト型コンテナー向けのレジストリマニフェストです。ホスト型のリスティングは https://prism-mcp.terradev.cloud/mcp を指します。

利用できる機能

1 つの MCP セッションが 1 つのトレースになります。1 つの JSON-RPC リクエストが 1 つのスパンになります。ツールの失敗は正しく反映されます（result.isError → ERROR。成功を示す 200 にはなりません）。Telinea を送信先にすると、Prism 経由のすべてのサーバーが endpoint 属性を通じて Telinea Gateway ボードにも表示されます。p50/p95/p99、req/min、スパークラインを確認でき、バックエンドの変更は不要です。

意図的に実装していない機能

• バックエンド固有のシリアライズ。バックエンドで独自形式が必要な場合は、OpenTelemetry Collector を実行して Prism の送信先に指定してください。Collector はそのためのものです。
• クエリレイヤー、ストレージ、UI。Prism は送信し、Telinea は保存して可視化します。
• レガシー HTTP+SSE トランスポート（/sse + /messages、2024-11-05 仕様）。
• トランスポートレイヤーでの DNS リバインディング対策済み IP ピンニング（guard.py を参照）。