ModelSpec

ModelSpec リモート MCP サーバー

ModelSpec カタログに対する読み取り専用の MCP ツールです。データツールには API キーが必要です。サイトは Cloudflare Pages 上に維持し、この Worker は https://api.modelspec.dev/mcp と公開サーバーカード https://api.modelspec.dev/.well-known/mcp/server-card.json のみを処理します。

公式レジストリへの掲載

ルートの server.json は、公式レジストリの 2025-12-11 スキーマを使用して、キーが必要なリモートサーバーを記述します。 リポジトリに含まれるバージョンには、掲載時に確認されたデプロイが記録されています。 オフラインで検証を実行できるよう、スキーマは変更せず tests/fixtures/mcp_registry/ に格納されています。

レビューとマージが完了し、MCP のデプロイが成功した後、オペレーターは main で Publish MCP registry listing を実行できます。このワークフローは、 稼働中の Worker の serverInfo.version が選択したコミットと一致することを検証し、 そのバージョンを一時マニフェストに書き込みます。デプロイの不一致があると、 認証や公開の前に失敗します。このワークフローではチェックサムで固定された mcp-publisher v1.8.1 と GitHub OIDC を使用します。push をトリガーとせず、 レジストリ用のシークレットも不要です。

レジストリのメタデータでは、必須のシークレットキー Authorization: Bearer を宣言します。キーは 料金とキーから入手できます。

参照先：レジストリスキーマ、 公式の公開ワークフロー、 および publisher v1.8.1。

Smithery への掲載

レビューとマージが完了し、MCP のデプロイが成功した後、以下の必須 API キー設定を使って リモート URL を公開します。YOUR_SMITHERY_NAMESPACE を、公開アカウントが所有する 名前空間に置き換えてください。

smithery mcp publish "https://api.modelspec.dev/mcp" \
  -n @YOUR_SMITHERY_NAMESPACE/modelspec \
  --config-schema '{"type":"object","properties":{"apiKey":{"type":"string","title":"ModelSpec API key","description":"Create one at https://modelspec.dev/pricing/","x-from":{"header":"x-api-key"},"x-to":{"header":"x-api-key"}}},"required":["apiKey"]}'

Smithery は各ユーザーの ModelSpec キーを取得し、値をそのまま x-api-key ヘッダーとして転送します。MCP Worker は API 呼び出し用にこれを Authorization: Bearer <key> に変換します。この別名は MCP にのみ適用されます。 直接の /v1/* API 呼び出しでは、引き続き Bearer 認証のみが使用できます。

公開サーバーカードにはキーは不要です。その serverInfo は initialize と一致し、 バージョンとしてデプロイ済みのコミットを含みます。 authentication: {"required": true, "schemes": ["bearer"]} を宣言し、 tools/list と同じ登録情報からツールを生成します。このカードでは Cache-Control: public, max-age=300 を使用します。

参照先：Smithery での公開、 および設定のトランスポート。

SDK とトランスポート

選択肢	内容
ハンドラー	agents/mcp/server の createMcpHandler
サーバー	@modelcontextprotocol/server 2.0 の McpServer
トランスポート	Streamable HTTP（POST /mcp）
状態	ステートレス。Durable Object はありません。

McpAgent は非推奨で、機能追加は凍結されています。Durable Object の状態が必要な セッション型サーバー向けに存在します。これらのツールはプロキシです。呼び出しごとに 公開ランク API、ポリシーチェック API、または静的 JSON エクスポートにアクセスし、 その本文とオリジン URL を返します。永続化するものはありません。

参照日（2026-09-18）：

• https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/
• https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/
• https://developers.cloudflare.com/agents/model-context-protocol/apis/agent-api/

ルート

ゾーン modelspec.dev 上の Workers ルート api.modelspec.dev/mcp* と api.modelspec.dev/.well-known/mcp/server-card.json は、この Worker に属します。 ランク Worker はすでに api.modelspec.dev/* を所有しており、より具体的なパターンが 優先されます。 カードのルートは完全一致のため、ディスカバリークライアントはクエリ文字列を付けずに その URL を使用する必要があります。その他の API ルートは、既存の Worker を引き続き使用します。 CI トークンでは Workers ルートを編集できますが、DNS は作成できないため、 新しいホスト名はありません。

ツール

呼び出しが成功すると、オリジンに転送されます。カード上の null は未調査を意味します。

ツール	オリジン
rank	POST https://api.modelspec.dev/v1/rank
model_info	GET https://modelspec.dev/api/models/<id>.json
list_use_cases	GET https://modelspec.dev/api/rank/profiles.json
policy_check	POST https://api.modelspec.dev/v1/policy-check
decide	POST https://api.modelspec.dev/v1/decide
compare_models	POST https://api.modelspec.dev/v1/compare-models
hardware_fit	POST https://api.modelspec.dev/v1/hardware-fit
vocab	GET https://modelspec.dev/api/decision/vocabulary.json
feedback	POST https://api.modelspec.dev/v1/feedback（キー不要。client は常に mcp で、呼び出し元のアドレスはレート制限のためにのみ転送されます）

rank、policy_check、decide、compare_models、hardware_fit は RANK サービスバインディングを使用します。同一ゾーンの Worker から公開 API ホスト名へフェッチすると、ゾーンオリジンに到達して 522 が返されるためです。これら5つのツールはすべて、キーを Authorization: Bearer <key> として転送します。
API は提示されたキーを検証し、認証エラーや支払いエラーを変更せずに返します。

MCP では Authorization: Bearer <key> または x-api-key: <key> のどちらかを使用できます。
両方のヘッダーが存在する場合、キーが一致している必要があります。認証情報が一致しない場合は、JSON-RPC エラーとともに HTTP 400 が返されます。キーがログやエラーメッセージに記録されることはありません。

すべてのデータツールで ModelSpec キーが必要です。MCP_REQUIRE_API_KEY="false" の場合も同様です。認証情報がない、または形式が正しくない場合、オリジンへの呼び出しの前に 401 missing_api_key の拒否が返されます。対象には rank、policy_check、decide、compare_models、hardware_fit、vocab、model_info、list_use_cases が含まれます。initialize と tools/list は引き続き公開されています。フィードバックは引き続きキー不要で、モデルデータを含みません。既存のキーを使用するか、利用可能状況については料金をご覧ください。

decide は、docs/decision-contract.md で定義された意思決定仕様を受け付けます。MCP 入力スキーマは、生成された docs/decision-contract.schema.json に基づいているため、API と MCP の契約に差異が生じることはありません。有効な facet id を確認するには、先に vocab をお読みください。除外する Musts には where を使用し、除外せずに順位付けする Prefers には optimize.weights を使用します。不明な機能値は may_qualify に表示されます。意思決定を再現するには、snapshot を固定してください。

compare_models は {models: ["lab/a", "lab/b"]} のみを受け付けます。カタログ ID は2〜4個で、それぞれ異なる必要があります。現在のスナップショットから取得した根拠付きの事実、提供内容、エビデンスを、呼び出し元が指定した順序で返します。順位付けや勝者の選定は行いません。不明な値は null のままになり、omitted は削除されたレコード数を示します。MCP のテキスト全体は 16 KB 以内に収まります。オリジンのレスポンスが大きすぎる場合は、簡潔な response_too_large ツールエラーとなり、比較データは返されません。この名前付きモデル比較によって、/v1/compare のスナップショット比較が変更されることはありません。

hardware_fit は model、sku、device_count、memory、runtime、quantisation、batch、context を受け付けます。memory はデバイスあたりの10進 GB 単位で指定する任意のオーバーライドです。入力が省略または null で、それによって評価できない場合、その入力は API に渡され、undetermined が返されます。不明な SKU または量子化の識別子も API に渡されます。このツールはエンドポイントの回答と引用を完全な形で保持します。measured の回答では、該当する実行が正確に引用されます。estimated の回答には、estimated_fit: likely|unlikely、メモリの余裕、計算式、入力、前提条件が含まれます。推定によって適合が証明されることはなく、fits: true が含まれることもありません。

クライアント設定

クライアント向けのネイティブスニペットを取得するには、modelspec setup mcp --client claude-code または modelspec setup mcp --client claude-desktop を実行してください。 Claude Code：

{
  "mcpServers": {
    "modelspec": {
      "type": "http",
      "url": "https://api.modelspec.dev/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Claude Desktop は mcp-remote stdio ブリッジを使用し、Node.js/npx が必要です：

{
  "mcpServers": {
    "modelspec": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.modelspec.dev/mcp",
               "--header", "Authorization:${MODELSPEC_AUTH_HEADER}"],
      "env": {"MODELSPEC_AUTH_HEADER": "Bearer <MODELSPEC_API_KEY>"}
    }
  }
}

macOS の GUI アプリはシェル環境を引き継ぎません。env ブロック内のプレースホルダーをキーに明示的に置き換え、Bearer はそのまま残してください。キーはこの設定に保存されます。CLI のセットアップコマンドはプレースホルダーを書き込み、保存済みのキーや環境変数のキーを設定にコピーすることはありません。env ブロックとヘッダーの形式は、mcp-remote のドキュメントに従っています。

ローカル

npm install
npm test
npm run typecheck
npx [email protected] dev --local --var BUILD_COMMIT:dev

デプロイは main へのプッシュ時のみ、.github/workflows/mcp.yml で行います。ノート PC からデプロイしないでください。