コンテンツにスキップ
これは最新の機能を備えた最新リリースですが、長期サポートは提供されません。サポートを継続するには、新しいリリースごとにアップグレードするか、四半期ごとの安定版リリースをご利用ください。

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

MCP Registry v0.1 API を公開する

Page as Markdown

カタログ内の MCP サーバーを公式 MCP Registry v0.1 の読み取り API 経由で再公開し、VS Code などのレジストリ対応クライアントが検出できるようにします。

MCP Registry v0.1 互換レイヤーについて

Solo Enterprise for agentregistry は、カタログ内の MCPServer リソースを、公式 MCP Registry の読み取り API を通じて標準の server.json 形式で再公開できます。VS Code MCP ギャラリーなどのレジストリ対応クライアントは、この API を使用してカタログ内の MCP サーバーを検出します。この互換レイヤーを有効にすると、これらのクライアントを変更せずにカタログを利用できるようになります。

互換レイヤーは、Solo Enterprise for agentregistry が提供するネイティブの ar.dev/v1alpha1 MCPServer API を変更しません。引き続きこの API を使用して、MCP サーバーカタログを構築および更新します。互換レイヤーは、カタログ内の同じリソースに対する読み取り専用の代替ビューを追加するだけです。このレイヤーを使用して、カタログ内の MCP サーバーを公開または更新することはできません。

v0.1 仕様エンドポイント

互換レイヤーを有効にすると、レジストリサーバーは次のエンドポイントを標準仕様のパスで提供します。必要に応じて、これらのエンドポイントのベースパスとしてカスタムプレフィックスを設定できます。詳細については、互換レイヤーを有効にするを参照してください。

メソッドパス説明
GET/v0.1/serversサーバーを一覧表示します。カーソルページネーションを使用します。各レスポンスにはページ番号の代わりにトークンが含まれ、このトークンを渡して次のページを取得します。一覧をフィルタリングまたは検索するには、検索結果をフィルタリングするを参照してください。
GET/v0.1/servers/{serverName}/versions1 つのサーバーのすべてのバージョンを一覧表示します。
GET/v0.1/servers/{serverName}/versions/{version}1 つのバージョンを取得します。{version} セグメントには latest を指定できます。

{serverName} セグメントは、default/weather などの、名前空間で修飾された <namespace>/<name> 形式のカタログ名です。上記 2 つのルートでは、スラッシュを %2F として URL エンコードします。たとえば、GET /v0.1/servers/default%2Fweather/versions/latest のように指定します。スラッシュをエンコードしないリクエストは、ルートに一致しません。

検索結果をフィルタリングする

次のリクエスト例に示すように、GET /v0.1/servers パスにクエリパラメーターを追加して、カタログの検索、フィルタリング、またはページングを行います。

GET /v0.1/servers?limit=50&search=weather&updated_since=2026-09-01T00:00:00Z&include_deleted=false&version=1.2.0
パラメーター説明
searchリソース名にこのテキストが含まれるサーバーに一覧を絞り込みます。例では weather です。大文字と小文字は区別されません。エンドポイントが返す名前空間修飾のカタログ名ではなく、リソース名の列のみと照合します。
limit1 ページあたりに返すサーバー数です。上限は 100 です。省略すると、デフォルトのページサイズが使用されます。
cursorページネーショントークンです。前のレスポンスの metadata.nextCursor 値を設定すると、次のページを取得します。省略すると、最初のページを取得します。
updated_since2026-09-01T00:00:00Z などの RFC3339 タイムスタンプです。この時刻以降に変更されたサーバーのみを返します。
version各サーバーの特定の 1 バージョンに一覧を絞り込みます。このパラメーターを省略するか latest に設定すると、デフォルトどおり各サーバーの最新バージョンのみを返します。
include_deleted削除待ちのサーバーを含めるには true に設定します。デフォルトは false です。

レスポンスは公式 MCP Registry のエンベロープを使用し、camelCase フィールドと io.modelcontextprotocol.registry/official _meta ブロックを含みます。次の例は読みやすくするために省略しています。実際のレスポンスには、ここでは省略している $schema、description、title、repository、statusChangedAt などのフィールドも含まれます。次のページを取得するには、レスポンスの metadata.nextCursor を cursor として渡します。metadata.count は現在のページ内のサーバー数を示します。

{
  "servers": [
    {
      "server": {
        "name": "default/weather",
        "version": "1.2.0",
        "packages": [],
        "remotes": []
      },
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "status": "active",
          "isLatest": true,
          "publishedAt": "2026-08-01T12:00:00Z",
          "updatedAt": "2026-08-01T12:00:00Z"
        }
      }
    },
    {
      "server": {
        "name": "default/echo",
        "version": "0.3.1",
        "packages": [],
        "remotes": []
      },
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "status": "active",
          "isLatest": true,
          "publishedAt": "2026-07-14T09:30:00Z",
          "updatedAt": "2026-07-14T09:30:00Z"
        }
      }
    }
  ],
  "metadata": { "nextCursor": "eyJvZmZzZXQiOjUwfQ", "count": 2 }
}

強調表示された metadata.nextCursor 値はここでは空ではないため、このページの後にもサーバーが存在します。次のリクエストで metadata.nextCursor 値を cursor として渡します。以降のページがないレスポンスでは、nextCursor フィールド自体が省略されます。

アクセス制御

互換レイヤーは、レジストリの他の部分を管理するアクセス制御レイヤーの外側にあります。/v0.1/* エンドポイントへのリクエストは、レイヤー 1 認証を完全にバイパスします。Bearer トークンは不要で、リクエスト時に提示したトークンは無視されます。レジストリは、認証済みかどうかに関係なくすべての呼び出し元を同じ固定の公開 ID として扱い、その ID にカタログで公開されているすべての MCP サーバーへの読み取り専用権限を付与します。また、レイヤー 2 の AccessPolicy リソースを使用して、個々の呼び出し元が参照できる MCP サーバーをスコープ設定することもできません。/v0.1/servers エンドポイントが返すカタログはフラットで、すべての名前空間にまたがり、すべての呼び出し元で同一です。

Warning

互換レイヤーを有効にすると、MCP サーバーカタログ全体が公開アクセス可能になります。レジストリがホストされているネットワークにアクセスできる人は誰でも互換エンドポイントに到達し、MCP サーバーカタログにアクセスできます。公開の読み取り専用カタログが許可される環境でのみ、このレイヤーを有効にしてください。

制限事項

  • v0.1 のみ。 非推奨のレガシー v0 MCP Registry API は、Solo Enterprise for agentregistry では提供されません。
  • 読み取り専用。 MCP Registry v0.1 API 仕様では、サーバーの公開やステータスの編集などの書き込みエンドポイントも定義されています。Solo Enterprise for agentregistry は、これらの書き込みエンドポイントをサポートしていません。互換レイヤーが提供するのは読み取りパスのみです。
  • ベストエフォートのバージョンマッピング。 カタログは、設定されているもののうち最初に見つかった値をサーバーの version として選択します。対象は、パッケージバージョン (npm または PyPI のバージョン、あるいは OCI タグまたはダイジェスト)、サーバー自体の latest 以外のタグ、最後の手段としての 0.0.0 です。パッケージバージョンはそのまま使用されるため、:latest でタグ付けされた OCI イメージはカタログ内で "version": "latest" と表示されます。
  • ベストエフォートのトランスポートマッピング。 サーバーが http トランスポートを使用する場合、カタログはこれを streamable-http として再ラベル付けし、仕様で必須とされる http://localhost:<port><path> などのプレースホルダー URL を入力します。このプレースホルダーは、必ずしもサーバーが実際に到達可能な場所を示すものではありません。

始める前に

  1. OIDC プロバイダーをセットアップして、ユーザーがレジストリで認証できるようにします。

  2. Solo Enterprise for agentregistry をインストールし、arctl CLI をセットアップします。

  3. まだ実行していない場合は、Solo Enterprise for agentregistry サーバーをポート 12121 でポートフォワードします。レジストリはデフォルトでは外部に公開されないため、ローカルマシンから到達するにはポートフォワードが必要です。

    kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 12121:12121
  1. 少なくとも 1 つの MCP サーバーをカタログに公開するか、リモート MCP サーバーを登録します。
  2. VS Code で互換レイヤーを検証する予定がある場合は、HTTPS を終端するイングレスまたはゲートウェイ経由でレジストリを公開します。VS Code では、レジストリが HTTPS URL で公開されている必要があり、プレーンな http:// URL は拒否されます。このガイドの他の部分で使用する localhost ポートフォワードは、VS Code では機能しません。

互換レイヤーを有効にする

互換レイヤーはデフォルトで無効です。レジストリサーバーで AGENT_REGISTRY_MCP_REGISTRY_COMPAT_ENABLED 環境変数を true に設定して有効にします。

  1. Helm リリースをアップグレードし、環境変数をレジストリサーバーに渡します。

    helm upgrade --install agentregistry \
      oci://us-docker.pkg.dev/solo-public/agentregistry-enterprise/helm/agentregistry-enterprise \
      --namespace agentregistry-system \
      --version 2026.10.0 \
      --reuse-values \
      --set-string "extraEnvVars[0].name=AGENT_REGISTRY_MCP_REGISTRY_COMPAT_ENABLED" \
      --set-string "extraEnvVars[0].value=true"

    Warning

    extraEnvVars[0] 構文は、リストの最初のエントリに書き込みます。リリースですでに他の追加環境変数を設定している場合は、既存のエントリを上書きしないように、この変数を Helm values ファイルに追加してください。

  2. レジストリサーバーが新しい環境変数を使用して再起動したことを確認します。

    kubectl -n agentregistry-system get deploy agentregistry-enterprise-server \
      -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="AGENT_REGISTRY_MCP_REGISTRY_COMPAT_ENABLED")].value}'

    出力例:

    true
    
  3. v0.1 エンドポイントにアクセスできることを確認します。次の例では、/v0.1/servers エンドポイントにリクエストを送信して、カタログで利用可能な MCP サーバーを一覧表示します。レジストリが他のすべてのエンドポイントで OIDC 認証を適用している場合でも、このエンドポイントへのリクエストには Bearer トークンは不要です。詳細については、アクセス制御を参照してください。

    curl http://localhost:12121/v0.1/servers

    出力例:

    {
      "servers": [
        {
          "server": {
            "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
            "name": "default/mymcp",
            "description": "mymcp MCP server",
            "title": "mymcp",
            "version": "latest",
            "repository": {
              "url": "https://github.com/solo-io/doc-examples",
              "source": "github",
              "subfolder": "agentregistry/mymcp"
            },
            "packages": [
              {
                "registryType": "oci",
                "identifier": "localhost:5001/mymcp:latest"
                ...
              }
            ]
          }
          ...
        }
      ]
      ...
    }
    

    Tip

    デフォルトでは、レジストリはこれらのエンドポイントを /v0.1/servers などのルートパスで提供します。代わりに /mcp-registry/v0.1/servers などのベースパス配下にマウントするには、AGENT_REGISTRY_MCP_REGISTRY_COMPAT_PATH_PREFIX 環境変数も、使用するプレフィックスに設定します。たとえば /mcp-registry です。後でクライアントに登録する URL のベースとして、このプレフィックスを使用します。

    Tip

    互換レイヤーを再び無効にするには、このコマンドを AGENT_REGISTRY_MCP_REGISTRY_COMPAT_ENABLED を false に設定して繰り返します。

VS Code で MCP サーバーにアクセスする

VS Code などのレジストリ対応クライアントは、ベース URL を受け取り、/v0.1/servers などの標準の相対パスを自分で追加します。フルパスではなく、ベース URL のみを設定してください。VS Code は、GitHub Copilot の McpGalleryServiceUrl エンタープライズポリシーを通じてプライベート MCP レジストリを検出します。通常、管理者はこのポリシーを VS Code の外部、オペレーティングシステムレベルで設定し、管理対象マシン上のすべての VS Code インストールに適用します。

  1. 始める前にでセットアップしたイングレスまたはゲートウェイの HTTPS ベース URL に、McpGalleryServiceUrl ポリシーを設定します。たとえば https://registry.example.com、または AGENT_REGISTRY_MCP_REGISTRY_COMPAT_PATH_PREFIX を設定した場合は https://registry.example.com/mcp-registry です。使用するマシンの種類に応じて、ポリシーの設定方法は異なります。
    プラットフォームポリシーを設定する場所
    WindowsGroup Policy または Intune を通じて Windows Registry 値を配布します。レジストリキー HKEY_LOCAL_MACHINE\SOFTWARE\Policies\GitHubCopilot と値 McpGalleryServiceUrl を使用します。
    macOSMDM プロファイルを通じて Managed Preference を配布します。com.github.copilot preference domain と McpGalleryServiceUrl キーを使用します。
    任意のプラットフォームGitHub Copilot の managed-settings.json ファイルに McpGalleryServiceUrl キーを書き込みます:
    • macOs: /Library/Application Support/GitHubCopilot/managed-settings.json
    • Windows: %ProgramFiles%\GitHubCopilot\managed-settings.json
    • Linux: /etc/github-copilot/managed-settings.json
    Linux にはネイティブの Registry や MDM 相当の仕組みがないため、または Group Policy や MDM ツールよりもスクリプトによるファイル配布を優先する場合は、この仕組みを使用します。
  2. VS Code を再起動して、ポリシーが読み込まれるようにします。
  3. Command Palette (Ctrl+Shift+P または Cmd+Shift+P) を開き、MCP: Browse Servers を実行します。または、Extensions ビュー (Ctrl+Shift+X または Cmd+Shift+X) を開き、@mcp を検索します。
  4. カタログに公開したサーバーが一覧に表示されることを確認します。
  5. サーバーを選択し、Install を選択して、VS Code がそのサーバーをワークスペースに追加できることを確認します。

Note

VS Code は、複数のプライベート MCP レジストリへの同時接続をサポートしていません。組織ですでに McpGalleryServiceUrl が別のレジストリを指している場合、Solo Enterprise for agentregistry を 2 つ目のソースとして追加することはサポートされません。

次の手順