第1章 MCP サーバー

手順

1. 以下のいずれかのコマンドを実行して、Red Hat OpenShift Container Platform Helm チャート用の MCP サーバーをインストールします。

   • 読み取り専用アクセスの場合 (ほとんどのユースケースで推奨):

     $ helm upgrade -i -n openshift-mcp-server --create-namespace openshift-mcp-server \
         openshift-helm-charts/redhat-openshift-mcp-server \
         --set config.toolsets=<toolset-names> \
         --set ingress.host=<hostname> \
         --set openshift=true \
         --set-json 'rbac.extraClusterRoleBindings=[{"name":"use-view-role","roleRef":{"name":"view","external":true}}]'

   • クラスターへのフルアクセスには以下が必要です。

     $ helm upgrade -i -n openshift-mcp-server --create-namespace openshift-mcp-server \
         openshift-helm-charts/redhat-openshift-mcp-server \
         --set config.toolsets=<toolset-names> \
         --set ingress.host=<hostname> \
         --set openshift=true \
         --set-json 'rbac.extraClusterRoleBindings=[{"name":"admin-access","roleRef":{"name":"cluster-admin","external":true}}]'

   • ここで、<hostname> は、OpenShift Container Platform MCP サーバーのエントリーポイントとして機能する完全修飾ドメイン名 (FQDN) です。このホストアドレスは、イングレスコントローラーが外部トラフィックを MCP サーバーサービスにルーティングするために使用されます。これは、mcp-server.apps.cluster-name.domain.com のような URL である必要があります。

   • ここで、<toolset-names> には、次の表のツールセットを含めることができます。

     Expand

     表1.1 利用可能なツールセット

     ツールセット	説明	デフォルト	Status
     コア	Kubernetes 管理でよく使われるツール (Pod、汎用リソース、イベントなど)	はい	テクノロジープレビュー
     config	現在のローカル Kubernetes 設定 (kubeconfig) を表示および管理します。	はい	テクノロジープレビュー
     ネットエッジ	OpenShift Container Platform 用の NetEdge トラブルシューティングツール	いいえ	テクノロジープレビュー
     helm	Helm チャートとリリースを管理するためのツール	いいえ	テクノロジープレビュー
     metrics	Prometheus および Alertmanager エンドポイントを効率的にクエリーするためのツールセット	いいえ	テクノロジープレビュー
     ossm	OSSM を管理するための最も一般的なツール	いいえ	テクノロジープレビュー
     kubevirt	KubeVirt 仮想マシン管理ツール	いいえ	開発者プレビュー
     tekton	Tekton のパイプライン管理ツール (パイプライン、パイプライン実行、タスク、タスク実行用)	いいえ	開発者プレビュー

     Show more

手順

1. クライアント設定ファイルに以下の行を追加してください。

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

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

     {
       "mcpServers": {
         "openshift": {
           "type": "http",
           "url": "<url of the route created in the Helm chart>/mcp"
         }
       }
     }

     ここで、<Helm チャートで作成されたルートの URL> は、Helm のインストール時に設定したホスト名です。

2. クライアントから要求があったら、CA 証明書を受け入れてください。

手順

1. MCP ゲートウェイをインストールしてください。

   MCP ゲートウェイのインストール方法については、Red Hat Connectivity Link の ドキュメントの MCP ゲートウェイのインストール セクションを参照してください。

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

手順

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

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

   注記

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

   例

   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
   mcp-system  mcp-gateway           105s

3. 以下のコマンドを実行して、ブローカールーターのデプロイメントを確認します。

   $ oc logs -n mcp-system deployment/mcp-gateway-broker-router

4. 以下のコマンドを実行して、ゲートウェイ名前空間に EnvoyFilter が作成されていることを確認してください。

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

手順

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

   $ 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-system
       sectionName: mcp
     hostnames:
     - ${MCP_SERVER_HOST}
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /mcp
       backendRefs:
       - name: openshift-mcp-server
         port: 8080
   EOF

   ここで、${MCP_SERVER_HOST} は Helm のインストール時に設定したホスト名です。

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

2. 以下のコマンドを実行して、MCP サーバーの登録リソースを作成します。

   $ oc apply -f - <<EOF
   apiVersion: mcp.kuadrant.io/v1alpha1
   kind: MCPServerRegistration
   metadata:
     name: my-mcp-server-reg
     namespace: openshift-mcp-server
   spec:
     toolPrefix: "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 サーバーの名前空間。これは openshift-mcp-server です。
   • spec.targetRef.name: MCP サーバーの HTTPRoute の名前。これは、`oc get httproute -n openshift-mcp-server .` コマンドを実行することで確認できます。
   • spec.targetRef.namespace: MCP サーバーの HTTPRoute の名前空間。これは openshift-mcp-server です。

3. 以下のコマンドを実行して、登録状況を確認してください。

   $ 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

4. 以下のコマンドを実行して、コントローラーのログを確認してください。

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

5. 以下のコマンドを実行して、ブローカーのログからツールの検出状況を確認してください。

   $ oc logs -n mcp-system deployment/mcp-gateway-broker-router

6. 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

      これで、応答に MCP サーバーツールが表示されるはずです。ツールには、設定した toolPrefix (例:myserver_) がプレフィックスとして付加されます。

手順

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

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

   RBAC 設定の YAML ファイル例

   extraClusterRoles:
     - name: acm-managed-clusters
       rules:
         # Required for discovering and watching managed clusters
         - apiGroups: ["cluster.open-cluster-management.io"]
           resources: ["managedclusters"]
           verbs: ["list", "watch"]
   
   # -- ClusterRoleBinding for the ACM managed clusters role
   extraClusterRoleBindings:
     - name: acm-managed-clusters
       roleRef:
         name: acm-managed-clusters
   
   # -- Role for accessing cluster-proxy-addon service in multicluster-engine namespace
   extraRoles:
     - name: acm-cluster-proxy-discovery
       namespace: multicluster-engine
       rules:
         # Required for auto-discovering cluster-proxy-addon service
         - apiGroups: [""]
           resources: ["services"]
           verbs: ["get"]
   
   # -- RoleBinding for the cluster-proxy-discovery role
   extraRoleBindings:
     - name: acm-cluster-proxy-discovery
       namespace: multicluster-engine
       roleRef:
         name: acm-cluster-proxy-discovery

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

   $ helm upgrade openshift-mcp-server openshift-helm-charts/redhat-openshift-mcp-server \
       -n openshift-mcp-server \
       -f rbac-values.yaml

手順

1. 機密性の高い CR へのアクセスを制限するために、アクセス拒否リソースを設定します。

   Secrets、ConfigMaps、および RBAC リソースへのアクセス権を取り消すには、以下のサンプルファイルを使用してください。

   例

   # Deny access to Secrets
   [[denied_resources]]
   group = ""
   version = "v1"
   kind = "Secret"
   
   # Deny access to ConfigMaps
   [[denied_resources]]
   group = ""
   version = "v1"
   kind = "ConfigMap"
   
   # Deny access to RBAC resources for additional security
   [[denied_resources]]
   group = "rbac.authorization.k8s.io"
   version = "v1"
   kind = "Role"
   
   [[denied_resources]]
   group = "rbac.authorization.k8s.io"
   version = "v1"
   kind = "RoleBinding"
   
   [[denied_resources]]
   group = "rbac.authorization.k8s.io"
   version = "v1"
   kind = "ClusterRole"
   
   [[denied_resources]]
   group = "rbac.authorization.k8s.io"
   version = "v1"
   kind = "ClusterRoleBinding"

2. 以下のいずれかの方法でこの設定を適用してください。

   • 設定をファイル (例: deny-resources.toml) に保存し、Helm の値ファイルを使用して渡します。

     $ helm upgrade openshift-mcp-server openshift-helm-charts/redhat-openshift-mcp-server \
         -n openshift-mcp-server \
         --set-file config.deniedResources=deny-resources.toml

   • または、--set-json を使用して設定をインラインで渡すこともできます。

     $ helm upgrade openshift-mcp-server openshift-helm-charts/redhat-openshift-mcp-server \
         -n openshift-mcp-server \
         --set-json 'config.deniedResources=[{"group":"","version":"v1","kind":"Secret"},{"group":"","version":"v1","kind":"ConfigMap"}]'

手順

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

   $ oc set env deployment/mcp-gateway-broker-router -n mcp-system\
   OAUTH_RESOURCE_NAME="MCP Server" \
   OAUTH_RESOURCE="http://mcp.127-0-0-1.sslip.io:8001/mcp" \
   OAUTH_AUTHORIZATION_SERVERS="https://login.microsoftonline.com/<tenant-id>/v2.0" \
   OAUTH_BEARER_METHODS_SUPPORTED="header" \
   OAUTH_SCOPES_SUPPORTED="openid,mcp-server,offline_access"

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

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

   $ oc apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: mcp-gateway-oauth-metadata
     namespace: mcp-system
   spec:
     parentRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       namespace: gateway-system
       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. アイデンティティープロバイダー (Entra ID) アプリ登録の設定:

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

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

      Entra ID の設定に関する詳細は、Microsoft Entra ID のアプリケーション登録の設定に関するドキュメントを参照してください。

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

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

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

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

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

   $ oc apply -f - <<EOF
   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: mcp-auth-policy
     namespace: mcp-system
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       sectionName: mcp
     defaults:
       when:
   
         - predicate: "!request.path.contains('/.well-known')"
       rules:
         authentication:
           'entra-id':
             jwt:
               issuerUrl: https://login.microsoftonline.com/<tenant-id>/v2.0
         response:
           unauthenticated:
             code: 401
             headers:
               'WWW-Authenticate':
                 value: Bearer resource_metadata=http://mcp.127-0-0-1.sslip.io:8001/.well-known/oauth-protected-resource/mcp
             body:
               value: |
                 {
                   "error": "Unauthorized",
                   "message": "Authentication required."
                 }
   EOF

検証

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

   curl http://mcp.127-0-0-1.sslip.io:8001/.well-known/oauth-protected-resource

   このコマンドを実行すると、以下のような 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": [
       "openid",
       "mcp-server",
       "offline_access"
     ]
   }

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

   $ curl -v http://mcp.127-0-0-1.sslip.io:8001/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

   例

   {
     "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"]
       }
     }
   }

   • 名前空間は、MCPServerRegistration CR の名前空間と一致する必要があります。
   • 「ロールは」、使用可能なツールを表します。この例では、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:
         'sso-server':
           jwt:
             issuerUrl: https://login.microsoftonline.com/<tenant-id>/v2.0
       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=http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/.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

   詳細は、以下のようになります。

   • 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=http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/mcp。

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

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

   $ kill $INSPECTOR_PID

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

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

   • pods_list
   • イベントリスト
   • ノードリスト
   • デプロイメント _get

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

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

6. 認可決定を監視する:

   1. 以下のコマンドを実行して、AuthPolicy の状態を確認してください。

      $ oc get authpolicy -A

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

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