第1章 MCP サーバー

手順

1. MCP ゲートウェイをインストールします。

   MCP ゲートウェイのインストール方法は、「MCP ゲートウェイのインストール (Red Hat Connectivity Link)」を参照してください。

   インストール後、コントローラーはゲートウェイアクセス用の HTTP ルートを自動的に作成します。MCP ゲートウェイは、複数の MCP サーバーを単一のエンドポイントに集約するリバースプロキシーとして機能し、認証とレート制限のためのレイヤーを提供します。

手順

1. 次のコマンドを実行して、デプロイメントのステータスを確認します。

   $ oc get pods -n gateway-namespace -l "app.kubernetes.io/name=mcp-gateway"

   注記

   この例では、ゲートウェイのインストールに "gateway-namespace" という namespace を使用します。ゲートウェイを "gateway-namespace" とは異なる namespace にインストールする場合は、手順全体を通してその namespace を使用してください。

   例

   NAME                                      READY   STATUS    RESTARTS   AGE
   mcp-gateway-controller-594b9649cf-zstfw   1/1     Running   0          22s

2. 以下のコマンドを実行して、MCP ゲートウェイ拡張機能が存在することを確認します。

   $ oc get mcpgatewayextension -A

   例

   NAMESPACE          NAME          READY   AGE
   gateway-namespace  mcp-gateway           105s

3. 以下のコマンドを実行して、broker-router デプロイメントを確認します。

   $ oc logs -n gateway-namespace deployment/mcp-gateway

4. 以下のコマンドを実行して、ゲートウェイ namespace に EnvoyFilter が作成されていることを確認します。

   $ oc get envoyfilter -n gateway-namespace -l app.kubernetes.io/managed-by=mcp-gateway-controller

手順

1. HTTPRoute を作成する前に、次のコマンドを入力して MCP サーバーサービスの正確な名前を確認します。

   $ oc get svc -n openshift-mcp-server

   以下のマニフェストの backendRefs.name フィールドが、サービスの NAME 出力と一致していることを確認します。たとえば、openshift-mcp-server などです。

2. 以下のコマンドを実行して、MCP サーバー用の HTTPRoute を作成します。

   $ oc apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: mcp-api-key-server-route
     namespace: openshift-mcp-server
   spec:
     parentRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       namespace: gateway-namespace
       sectionName: mcp
     hostnames:
     - ${MCP_SERVER_HOST}
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /mcp
       backendRefs:
       - name: openshift-mcp-server
         port: 8080
   EOF

   ${MCP_SERVER_HOST} は、MCP ゲートウェイルートのホスト名です (例: mcp-gateway.apps.<cluster-name>.<domain-name>)。

   この HTTPRoute により、MCP ゲートウェイはトラフィックを MCP サーバーインスタンスにルーティングできるようになり、MCPServerRegistration リソースで参照されます。

3. 以下のコマンドを実行して、MCP サーバーの Registration Resource を作成します。

   $ oc apply -f - <<EOF
   apiVersion: mcp.kuadrant.io/v1alpha1
   kind: MCPServerRegistration
   metadata:
     name: my-mcp-server-reg
     namespace: openshift-mcp-server
   spec:
     prefix: "openshift_"
     targetRef:
       group: "gateway.networking.k8s.io"
       kind: "HTTPRoute"
       name: "mcp-api-key-server-route"
       namespace: openshift-mcp-server
   EOF

   • metadata.name: MCP サーバー登録オブジェクトの名前を指定します。
   • metadata.namespace: MCP サーバーの namespace。これは openshift-mcp-server です。
   • spec.targetRef.name: MCP サーバーの HTTPRoute の名前。これは、oc get httproute -n openshift-mcp-server コマンドを実行することで見つけることができます。
   • spec.targetRef.namespace: MCP サーバーの HTTPRoute の namespace。これは openshift-mcp-server です。

4. 以下のコマンドを実行して、登録状況を確認します。

   $ oc wait --for=condition=Ready mcpsr/my-mcp-server-reg -n openshift-mcp-server --timeout=120s
   $ oc get mcpsr -A

   出力例

   NAMESPACE             NAME                PREFIX      TARGET                     PATH   READY   TOOLS   CREDENTIALS   AGE
   openshift-mcp-server  my-mcp-server-reg   myserver_   mcp-api-key-server-route   /mcp   True    4                     30s

   READY 列には True と表示され、TOOLS 列には検出されたツールの数が表示されるはずです。

   ステータスが準備完了でない場合は、以下のコマンドを実行して、MCP サーバーの登録条件の詳細を確認します。

   $ oc describe mcpsr my-mcp-server-reg -n openshift-mcp-server

5. 以下のコマンドを実行して、コントローラーのログを確認します。

   $ oc logs -n gateway-namespace deployment/mcp-gateway-controller

6. 以下のコマンドを実行して、ブローカーのログからツールの検出状況を確認します。

   $ oc logs -n gateway-namespace deployment/mcp-gateway

7. MCP サーバーツールが MCP ゲートウェイ経由で利用可能であることを確認します。

   1. MCP セッションを初期化し、ヘッダーをファイルにダンプするために -D オプションを使用し、次に以下のコマンドを実行してセッション ID を読み取ることで、セッション ID を取得します。

      $ curl -s -D /tmp/mcp_headers -X POST http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/mcp  \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

      <cluster-name>.<domain-name> は、クラスターの名前とドメインです。

   2. 以下のコマンドを実行して、レスポンスヘッダーから MCP セッション ID を抽出します。

      $ SESSION_ID=$(grep -i "mcp-session-id:" /tmp/mcp_headers | cut -d' ' -f2 | tr -d '\r')
      
      $ echo "MCP Session ID: $SESSION_ID"

   3. 以下のコマンドでセッション ID を使用してツールのリストを表示します。

      $ curl -X POST http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/mcp \
        -H "Content-Type: application/json" \
        -H "mcp-session-id: $SESSION_ID" \
        -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

      <cluster-name>.<domain-name> は、クラスターの名前とドメインです。

   4. 以下のコマンドを実行してクリーンアップします。

      $ rm -f /tmp/mcp_headers

      レスポンス内に、設定した prefix 値 (例: openshift_) が付加された MCP サーバーのツールが表示されているはずです。

手順

1. クライアント設定ファイルに以下の行を追加します。

   • Claude Desktop の場合: claude_desktop_config.json ファイル

   • Claude Code (CLI) の場合: .mcp.json ファイル

     {
       "mcpServers": {
         "openshift": {
           "type": "http",
           "url": "<url of the mcp gateway>/mcp"
         }
       }
     }

     <url of the mcp gateway> は、MCP ゲートウェイのインストール時に設定したホスト名です。

2. クライアントから要求があったら、CA 証明書を受け入れます。

手順

1. ClusterRoles、ClusterRoleBindings、Roles、および Rolebindings を拡張することで、RBAC の適用を設定します。

   ClusterRoles、ClusterRoleBindings、Roles、および Rolebindings を拡張するには、以下の RBAC YAML ファイルの例を使用します。

   RBAC 設定の YAML ファイル例

     apiVersion: rbac.authorization.k8s.io/v1
     kind: ClusterRole
     metadata:
       name: acm-managed-clusters
     rules:
       ...
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: ClusterRoleBinding
     metadata:
       name: acm-managed-clusters
       ...
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: Role
     metadata:
       name: acm-cluster-proxy-discovery
       namespace: multicluster-engine
       ...
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: RoleBinding
     metadata:
       name: acm-cluster-proxy-discovery
       namespace: multicluster-engine
       ...

2. 前述の例をファイル (例: rbac-values.yaml) に保存して RBAC 設定を適用し、以下のコマンドを実行します。

   $ oc apply -f rbac-values.yaml

手順

1. 以下のコマンドを実行して、MCP ゲートウェイブローカールーターのデプロイメントで環境変数を設定することにより、OAuth メタデータ検出を設定します。

   $ oc set env mcp-gateway/gateway-namespace -n mcp-system\
   OAUTH_RESOURCE_NAME="MCP Server" \
   OAUTH_RESOURCE="https://<mcp_gateway_host>/mcp" \
   OAUTH_AUTHORIZATION_SERVERS=<authorization_server_url> \
   OAUTH_BEARER_METHODS_SUPPORTED="header" \
   OAUTH_SCOPES_SUPPORTED=<oauth-scopes-supported>

   注記

   これらの環境変数により、クライアントが認証検出に使用する OAuth 2.0 保護リソースメタデータエンドポイントが有効になります。

   • <oauth-scopes-supported> には以下のいずれかを使用してください。

     • エントリー ID の場合: "api://<MCP_SERVER_CLIENT_ID>/mcp-server"
     • Keycloak の場合:mcp-server

   • <authorization_server_url> には以下のいずれかを使用してください。

     • エントラ ID: https://login.microsoftonline.com/< テナント ID>/v2.0
     • Keycloak: https://<keycloak_host>/realms/<realm> ;

2. 以下のコマンドを実行して、OAuth 検出用の HTTP ルートを作成します。

   $ oc apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: mcp-gateway-oauth-metadata
     namespace: gateway-namespace
   spec:
     parentRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       namespace: gateway-namespace
       sectionName: mcp
     hostnames:
     - ${MCP_GATEWAY_HOST}
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /.well-known/oauth-protected-resource
       backendRefs:
       - name: mcp-gateway
         port: 8080
   EOF

   ${MCP_GATEWAY_HOST} は、MCP ゲートウェイの完全修飾ドメイン名です (例: mcp.127-0-0-1.sslip.io)。

   このルートにより、クライアントは認証フローに必要な OAuth メタデータを検出できるようになります。このルートがない場合、クライアントは OAuth 検出を試行するときに 404 エラーが表示されます。

3. IdP(Entra ID または Keycloak) アプリ登録の設定:

   • エントリー ID の場合:

     1. Azure ポータルまたは Entra 管理センターで、Entra ID アプリ登録に移動します。
     2. Expose an API に、mcp-server という名前のカスタムスコープを追加します。
     3. openid、offline_access、および mcp-server のスコープが利用可能であることを確認してください。

     4. 組織の要件に応じて、これらのスコープに対する管理者の同意を付与してください。

        Entra ID アプリ登録の設定の詳細は、「Microsoft Entra ID」を参照してください。

   • Keycloak の場合:

     1. Keycloak レルムに以下の必須スコープが存在することを確認してください。

        • openid (組み込み)
        • オフラインアクセス (組み込み)
        • mcp-server (カスタム - 存在しない場合は作成する)

     2. 管理コンソールで、[レルム設定] > [クライアント登録] > [認証済みアクセスポリシー] に移動し、これらのスコープをレルムの DCR 許可クライアントスコープポリシーに追加します。

        Keycloak に関する詳細は、Red Hat build of Keycloak を参照してください。

4. 以下のコマンドを実行して、IdP の CA 証明書を Authorino デプロイメントにマウントし、JWT 検証のための証明書の信頼性を設定します。

   重要

   IdP が公開信頼済み証明書を使用している場合は、この手順をスキップしてください。

   $ oc create configmap idp-ca --from-file=ca.crt=/path/to/idp-ca.crt -n kuadrant-system

   $ oc patch deployment authorino -n kuadrant-system --type=json -p='[
     {
       "op": "add",
       "path": "/spec/template/spec/volumes/-",
       "value": {"name": "idp-ca", "configMap": {"name": "idp-ca"}}
     },
     {
       "op": "add",
       "path": "/spec/template/spec/containers/0/volumeMounts/-",
       "value": {"name": "idp-ca", "mountPath": "/etc/ssl/certs/idp-ca.crt", "subPath": "ca.crt"}
     }
   ]'

   これにより、Authorino は IdP からの JWT トークン署名を検証できるようになります。

5. 以下のコマンドを実行して、JWT トークンを検証する認証ポリシーを適用し、MCP ゲートウェイ認証を設定します。

   $ oc apply -f - <<EOF
   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: mcp-auth-policy
     namespace: gateway-namespace
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       sectionName: mcp
     defaults:
       when:
         - predicate: "!request.path.contains('/.well-known')"
       rules:
         authentication:
           'idp':
             jwt:
               issuerUrl: <authorization_server_url>
         response:
           unauthenticated:
             code: 401
             headers:
               'WWW-Authenticate':
                 value: Bearer resource_metadata=https://<mcp_gateway_host>/.well-known/oauth-protected-resource/mcp
               body:
                 value: |
                   {
                     "error": "Unauthorized",
                     "message": "Authentication required."
                   }
   
           success:
             headers:
               authorization:
                 plain:
                   expression: "request.headers['authorization']"
   
   EOF

   • <authorization_server_url> には以下のいずれかを使用してください。

     • エントラ ID: http://login.microsoftonline.com/<tenant-id>/v2.0
     • Keycloak: https://<keycloak_host>/realms/<realm> ;

6. 認証済みユーザーにクラスター上での権限を付与するには、以下のようなファイルを使用して ClusterRoleBinding を 作成します。

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: oidc-mcp-cluster-reader
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
   - apiGroup: rbac.authorization.k8s.io
     kind: User
     name: <issuer_url>#<username>

   • 名前: ユーザー主体、形式は <issuer_url>#<username> です。
   • ClusterRole (たとえば、view) をユーザーが必要とするアクセスレベルに調整します。

検証

1. ブローカーが OAuth ディスカバリー情報を提供していることを確認するには、次のコマンドを実行してテストします。

   curl ${MCP_GATEWAY_HOST}/.well-known/oauth-protected-resource

   ${MCP_GATEWAY_HOST} には、MCP ゲートウェイのドメインを使用してください。

   このコマンドを実行すると、以下のような OAuth 2.0 保護リソースメタデータが表示されるはずです。

   例

   {
     "resource_name": "MCP Server",
     "resource": "http://mcp.127-0-0-1.sslip.io:8001/mcp",
     "authorization_servers": [
       "https://login.microsoftonline.com/<tenant-id>/v2.0"
     ],
     "bearer_methods_supported": [
       "header"
     ],
     "scopes_supported": [
       "mcp-server",
     ]
   }

2. 保護されたエンドポイントで認証が必要になったことを確認するには、次のコマンドを実行します。

   $ curl -v ${MCP_GATEWAY_HOST}/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

   • ${MCP_GATEWAY_HOST} には、MCP ゲートウェイのドメインを使用してください。

     例

     {
       "error": "Unauthorized",
       "message": "Authentication required."
     }

手順

1. 発行する JWT トークンに、アイデンティティープロバイダーが必要なグループ/ロールの要求を含めていることを確認します。

   発行される OAuth トークンには、以下のような要求が含まれている必要があります。

   例

   {
     "resource_access": {
       "mcp-ns/openshift-mcp-server": {
         "roles": ["pods_list", "events_list", "nodes_list", "deployments_get"]
       },
       "mcp-ns/geometry-mcp-server": {
         "roles": ["pods_list", "events_list", "nodes_list", "deployments_get"]
       }
     }
   }

   • namespace は、MCPServerRegistration CR の namespace と一致する必要があります。
   • 「roles」 は、使用可能なツールを表します。この例では、pods_list、events_list、nodes_list、deployments_get です。

2. 以下のコマンドを実行して、ツールレベルのアクセス制御を強制する AuthPolicy を適用することにより、ツールレベルの認可を設定します。

   $ oc apply -f - <<EOF
   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: mcp-tool-auth-policy
     namespace: openshift-mcp-server
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       sectionName: mcp
     rules:
       authentication:
         'idp':
           jwt:
             issuerUrl: <authorization_server_url>
       authorization:
         'tool-access-check':
           patternMatching:
             patterns:
               - predicate: |
                   request.headers['x-mcp-toolname'] in (has(auth.identity.resource_access) && auth.identity.resource_access.exists(p, p == request.headers['x-mcp-servername']) ? auth.identity.resource_access[request.headers['x-mcp-servername']].roles : [])
       response:
         unauthenticated:
           headers:
             'WWW-Authenticate':
               value: Bearer resource_metadata=https://<mcp_gateway_host>/.well-known/oauth-protected-resource/mcp
           body:
             value: |
               {
                 "error": "Unauthorized",
                 "message": "MCP Tool Access denied: Authentication required."
               }
         unauthorized:
           body:
             value: |
               {
                 "error": "Forbidden",
                 "message": "MCP Tool Access denied: Insufficient permissions for this tool."
               }
   EOF

   • <authorization_server_url> には以下のいずれかを使用してください。

     • エントラ ID:login.microsoftonline.com/< テナント ID>/v2.0
     • Keycloak: https://<keycloak_host>/realms/<realm> ;
   • spec.sectionName は、MCP サーバーリスナーを対象とします。
   • <cluster-name>.<domain-name> は、クラスターの名前とドメインです。

検証

1. MCP Inspector を設定して、認可によってツールへのアクセスが制御されることを確認するテストを行います。

   1. 以下のコマンドを実行して、MCP Inspector (Node.js/npm が必要) を起動します。

      $ npx @modelcontextprotocol/inspector@latest &
      INSPECTOR_PID=$!

   2. 以下のコマンドを実行して、サービスが起動するまでお待ちください。

      $ sleep 3

   3. 次の URL にアクセスして MCP Inspector を開きます: http://localhost:6274/?transport=streamable-http&serverUrl=https://<mcp_gateway_host>/mcp。

      <mcp_gateway_host> を MCP ゲートウェイの完全修飾ドメイン名に置き換えてください。

2. 後でサービスを停止するには、次のコマンドを実行してください。

   $ kill $INSPECTOR_PID

3. アイデンティティープロバイダーで必要なロール要求が設定されたユーザーアカウントを使用して認証します。

4. 以下の許可されたツールをお試しください。

   • pods_list
   • events_list
   • nodes_list
   • deployments_get

5. この制限付きツールをお試しください: pods_delete

   このツールは制限されているため、403 Forbidden エラーが表示されます。

6. 認可決定を監視します。

   1. 以下のコマンドを実行して、AuthPolicy のステータスを確認します。

      $ oc get authpolicy -A

   2. 認可ログを表示するには、次のコマンドを実行します。

      $ oc logs -n kuadrant-system -l authorino-resource=authorino

手順

1. ossm ツールセットを有効にするには、config.toml ファイルに ossm ツールセットを追加または更新してください。

   ossm ツールセットを追加

   toolsets = ["core", "ossm"]

2. ossm ツールセットを以下のように設定してください。

   ossm ツールセットの設定を追加します

   [toolset_configs.kiali]
   url = "https://<kiali_route>"
   # insecure = true
   # certificate_authority = "/path/to/ca.crt"

   重要

   テーブルが存在しないか無効な場合、サーバーは起動しません。

   • ossm ツールセットは [toolset_configs.kiali] から設定を読み込みます。

   • URL は必須です。

     ホスト名を含む http:// または https://の URL を使用してください。URL が https:// で insecure が false の場合、certificate_authority を Kiali 証明書の CA ファイルに設定します。相対的な CA パスは、TOML ファイルを含むディレクトリーから解決されます。

   • 外部環境では、insecure = true は 証明書の検証をスキップします。

   • read_only = true (デフォルト) は ossm_manage_istio_config を 非表示にします。

     アシスタントがメッシュ設定を作成、更新、または削除する権限を設定するには:

     • 許可されていません: set read_only = true。

     • 許可されています: read_only を 未設定のままにするか、false に設定してください。

       設定変更の適用方法については、Red Hat OpenShift 用 MCP サーバーへの設定変更の適用を参照してください。

3. 呼び出し元のアイデンティティーを、オペレーターが提供する kiali-viewer (読み取り) または kiali (読み取り/書き込み) ClusterRole にバインドします。

   サーバーは、既存の Kubernetes 認証情報 (kubeconfig またはクラスター内から取得) を使用して、Kiali 呼び出し用のベアラートークンを設定します。Kiali の場合、MCP HTTP エンドポイントに HTTP 認証ヘッダーを渡す必要はありません。Kiali の呼び出しでは、サーバーに設定されているトークンが使用されます。

   Kiali は、そのトークンを使用してアクセスを強制します (名前空間の取得/リスト表示、および書き込みとログ記録のためのリソース RBAC)。ツールはこれを RBAC メタデータとして宣伝します。

   • Kubernetes チェックが引数または有限種類の列挙型から導出可能なツール (ログ、リソースの詳細、Istio 設定の読み書き、メトリクス/トレース名前空間ゲート、トラフィックグラフ) に対して制限されます。OpenShift Container Platform では、リソース/グラフの宣言には、オペレーターのビューアーロールからの デプロイメント設定 と ルート も含まれます。
   • Kiali は、有限な Kubernetes 要件セットとして表現できない制御プレーンとオブザーバビリティーバックエンドを集約するため、メッシュ全体のステータスとメッシュクラスターのリストに関しては無制限です。

4. オプション: マルチクラスターサポートを設定します。

   Kiali は、Istio サービスメッシュ内の複数のクラスターを管理できます。Kiali のほとんどのツールは、特定のメッシュクラスターを対象とするためのオプションの meshCluster パラメーターを受け入れます。ツールがクラスター名を指定しない場合、Kiali はホームクラスター (Kiali が実行されているクラスター) を使用します。

   他のツールを呼び出す前に、利用可能なメッシュクラスター名を確認するには、ossm_list_mesh_clusters を使用します。そのレスポンスの name フィールドは meshCluster の唯一の有効な値です。

   ossm ツールは OpenShift コンテキスト を受け取りません。ossm_list_mesh_clusters からメッシュクラスター名を使用します。マルチクラスターモードが有効になっている場合でも、同じ MCP サーバー上のコアツールは 引き続きコンテキスト を使用します。