Verlon AI MCP

@verlon-ai/mcp

Verlon AI 用の Model Context Protocol サーバーです。Verlon のリソース（ゲート、ログ、レコメンデーション、実験）を MCP ツールとして公開するため、コーディングエージェント（Claude Code、Cursor、Cline など、MCP 対応クライアントであればどれでも）が、AI インフラストラクチャをネイティブに確認・管理できます。

ステータス： 0.4.0 — MCP Registry に ai.verlon/mcp として登録されています。読み取り専用ツール 6 個（list_gates、get_gate、list_logs、get_recommendations、list_experiments、list_models）に加え、--enable-writes を指定した場合にのみ登録される書き込みツール switch_model を提供します。より広範な書き込み機能（create_gate、update_gate、run_chat、start_experiment）は、同じフラグのもとで今後のリリースに追加されます。

インストール

直接インストールする必要はありません。MCP クライアント（Claude Code、Cursor など）が npx 経由でサブプロセスとして起動します。以下のスニペットをクライアントの MCP 設定に追加してください。

Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）またはお使いの OS に対応する設定ファイルに追加します。

{
  "mcpServers": {
    "verlon": {
      "command": "npx",
      "args": ["-y", "@verlon-ai/mcp"],
      "env": {
        "VERLON_API_KEY": "sk-vrln-..."
      }
    }
  }
}

その後、Claude Code を再起動してください。ツール一覧に verlon サーバーが表示され、Claude がアカウントに対して verlon:list_gates を呼び出せるようになります。

Cursor

Cursor の MCP 設定（設定 → 機能 → MCP サーバー）に追加します。

{
  "mcpServers": {
    "verlon": {
      "command": "npx",
      "args": ["-y", "@verlon-ai/mcp"],
      "env": {
        "VERLON_API_KEY": "sk-vrln-..."
      }
    }
  }
}

その他の MCP 対応クライアント

このサーバーは stdio 経由で MCP を使用します。サブプロセスの環境に VERLON_API_KEY を設定して、npx -y @verlon-ai/mcp を起動してください。

ツール

デフォルトのツールセットは読み取り専用です。その理由についてはセキュリティに関する注意をご覧ください。書き込みツールは、サーバーの起動時に --enable-writes を指定した場合のみ登録されます。

ツール	入力	返される内容
list_gates	なし	アカウント内のすべてのゲート — id、name、description、model、taskType、taskSubtype、createdAt
get_gate	gateId（UUID）	ゲートの完全な設定 — model、フォールバックチェーン、タスクタイプ、支出上限、サブゲート、オーケストレーション
list_logs	gate?、since?（ISO 8601）、success?、limit?（1-100、デフォルト 20）	最近のリクエストログ — タイムスタンプ、ゲート、モデル、コスト、レイテンシ、成功／失敗
get_recommendations	gateId（UUID）	Cortex インテリジェンスレポート — テーマ、ドリフト検出、最適化の推奨事項。実行結果がまだない場合は { report: null }
list_experiments	gateId?、status?、projectId?	実験（シャドウ＋分割）— id、name、status、テストタイプ、バリアント、目標指標、設定
list_models	provider?（openai、anthropic、google、mistral、…）	ゲートがルーティング可能なチャットモデル。最新の料金（トークン 100 万個あたりの USD）と機能スコアも含まれます

書き込みツール（--enable-writes 指定時のみ）

ツール	入力	動作
switch_model	model（list_models の id）、gateId?	コーディングゲートがルーティングするモデルを切り替えます。再起動は不要で、実行中のセッションの次のターンから有効になります。gateId を省略すると、アカウントの Claude Code コネクターゲートが対象になります。冪等で、変更は元に戻せるフィールド 1 つだけです。

設定

環境変数	必須	デフォルト	備考
VERLON_API_KEY	はい	—	Verlon API キー（sk-vrln-...）。
VERLON_BASE_URL	いいえ	https://api.verlon.ai	セルフホスト可能な Verlon 用の上書き設定。

CLI フラグ

フラグ	目的
--enable-writes	書き込み可能なツール（現時点では switch_model）を登録します。デフォルトは読み取り専用です。適切に動作しないエージェントが誤ってリソースを破壊することを防ぎます。
--help、-h	使用方法を表示します。

セキュリティに関する注意

デフォルトで読み取り専用にしているのは、意図的な選択です。MCP クライアント（Claude Code、Cursor など）にはこのサーバーのツールが表示され、ユーザーのリクエストに関連すると判断した場合、自律的に呼び出すことがあります。デフォルトで読み取り専用にすることで、エージェントの動作に問題があっても、アカウントを変更できず、調査しかできません。書き込みツール（--enable-writes）は、その影響を理解したうえでのみ有効にしてください。現在唯一の書き込みツールは switch_model です。これは、1つのゲートにある1つのフィールドだけを変更できる、意図的に最も限定的な最初の書き込み機能です。リソースの作成、更新、削除はまだ公開されていません。

開発

npm install
npm test          # vitest
npm run build     # tsc → dist/

公開（メンテナー向け）

このパッケージは、npm では @verlon-ai/mcp（プロビナンス付きで自動公開）、MCP Registry では ai.verlon/mcp（手動公開）として二重に公開されています。Registry は公開を受け付ける前に npm バージョンの存在を検証するため、必ず先に npm へ公開してください。

リリースごとの手順

3つのファイルのバージョンを同じ値にそろえて更新してください。ずれがあると CI が失敗します。

ファイル	フィールド
package.json	version
server.json	version および packages[0].version
src/server.ts	VERLON_MCP_VERSION 定数

次に、以下を実行します。

# 1. Merge the bump to main (CI enforces the lockstep), then tag:
git tag v0.4.1 && git push origin v0.4.1
# The publish workflow runs `npm publish --provenance` automatically.

# Wait ~30s for npm CDN; verify:
npm view @verlon-ai/mcp version   # should print the new version

# 2. MCP Registry publish (manual — needs mcp-publisher + DNS-verified ai.verlon namespace)
npm run publish:mcp

初回セットアップ（Registry への公開）

# Install the MCP Registry publisher (NOT npm — it's a prebuilt binary)
brew install mcp-publisher

# DNS-verify the verlon.ai domain (required to publish under the ai.verlon namespace)
mcp-publisher login --help   # follow the DNS verification flow it prints
# Add the TXT record on verlon.ai; verify with `dig TXT verlon.ai +short`

検証

# All three versions match?
npm view @verlon-ai/mcp version
jq -r .packages[0].version server.json
grep VERLON_MCP_VERSION src/server.ts

# Registry listing live?
curl 'https://registry.modelcontextprotocol.io/v0/servers?search=verlon' | jq

# End-to-end smoke against the published artifact
VERLON_API_KEY=sk-vrln-... npx @modelcontextprotocol/inspector npx -y @verlon-ai/mcp

ライセンス

MIT — LICENSE を参照してください。