diff --git a/_attributes/attributes.adoc b/_attributes/attributes.adoc index dd868ec13b8b..c3b5bf4c2603 100644 --- a/_attributes/attributes.adoc +++ b/_attributes/attributes.adoc @@ -20,7 +20,7 @@ :ocp-min-version: 4.19 :oc-first: pass:quotes[OpenShift CLI (`oc`)] -:service-mesh: OpenShift Service Mesh +:ossm: OpenShift Service Mesh :service-mesh-version: 3.2 :cert-manager: cert-manager Operator for Red Hat OpenShift diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index b9652ed097ae..683a8fef8b54 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -75,8 +75,8 @@ Distros: rhcl Topics: - Name: Configuring the MCP gateway File: mcp-gateway-config-listener-route -- Name: Register MCP servers - File: mcp-gateway-register-servers +- Name: Registering external MCP servers + File: mcp-gateway-register-ext-mcp-servers - Name: Configuring authentication for the MCP gateway File: mcp-gateway-authz - Name: Configuring authorization for the MCP gateway diff --git a/mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc b/mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc new file mode 100644 index 000000000000..2db07150962b --- /dev/null +++ b/mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="mcp-gateway-register-ext-mcp-servers"] += Registering external MCP servers +include::_attributes/attributes.adoc[] +:context: mcp-gateway-register-ext-mcp-servers + +[role="_abstract"] +To use external MCP servers with your MCP gateway, you must configure ingress, create routing resources, and register the server with the MCP gateway. As a best practice, you must also configure security rules. + +include::modules/proc-register-ext-mcp-server-ingress.adoc[leveloffset=+1] + +include::modules/proc-register-ext-mcp-server-tls.adoc[leveloffset=+1] + +include::modules/proc-register-ext-mcp-server-httproute.adoc[leveloffset=+1] + +include::modules/proc-register-ext-mcp-server-secret.adoc[leveloffset=+1] + +include::modules/proc-register-ext-mcp-server-authpolicy.adoc[leveloffset=+1] + +include::modules/proc-register-ext-mcp-server-mcpserverregistration.adoc[leveloffset=+1] + +include::modules/proc-register-ext-mcp-server-verify.adoc[leveloffset=+1] diff --git a/mcp_gateway_config/mcp-gateway-register-servers.adoc b/mcp_gateway_config/mcp-gateway-register-servers.adoc deleted file mode 100644 index 3e03d49555f7..000000000000 --- a/mcp_gateway_config/mcp-gateway-register-servers.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -[id="mcp-gateway-register-servers"] -= Registering MCP servers -include::_attributes/attributes.adoc[] -:context: mcp-gateway-register-servers - -[role="_abstract"] -FPO assembly diff --git a/modules/proc-register-ext-mcp-server-authpolicy.adoc b/modules/proc-register-ext-mcp-server-authpolicy.adoc new file mode 100644 index 000000000000..d2d2cbf303b9 --- /dev/null +++ b/modules/proc-register-ext-mcp-server-authpolicy.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-authpolicy_{context}"] += Creating an AuthPolicy for an external MCP server + +[role="_abstract"] +To secure your use of an external MCP server, creating an `AuthPolicy` custom resource (CR) to authenticate your sessions is a best practice. The following example uses `Kuadrant/Authorino` for OAuth authentication and creates an `AuthPolicy` CR to handle authorization headers. + +[NOTE] +==== +This step is required if you are using OAuth authentication for your external MCP server. If your external MCP server uses a simple API key, you can use a `credentialRef` in your `MCPServerRegistration` CR instead, and an `AuthPolicy` object is not needed. +==== + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. +* You created `ServiceEntry`, `DestinationRule`, and `HTTPRoute` objects. + +.Procedure + +. Create an `AuthPolicy` CR that handles authorization headers by using the following example: ++ +.Example AuthPolicy CR +[source,yaml,subs="+quotes"] +---- +apiVersion: kuadrant.io/v1 +kind: AuthPolicy +metadata: + name: __ + namespace: __ +spec: + targetRef: + group: gateway.networking.k8s.io + kind: HTTPRoute + name: __ + rules: + response: + success: + headers: + authorization: + plain: + expression: 'request.headers["authorization"]' + x-mcp-api-key: + plain: + expression: 'request.headers["authorization"].split(" ")[1]' +---- ++ +* Replace the `metadata.name:` field value with the name you want to use. This approach uses service naming. +* Replace the `metadata.namespace:` field value with the namespace you used in your `ServiceEntry` object. +* Replace the `spec.name:` value with the name of your external MCP server route. +* This `AuthPolicy` CR extracts the API key from the OAuth token and sets it as the `x-mcp-api-key` header. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name of your CR. diff --git a/modules/proc-register-ext-mcp-server-httproute.adoc b/modules/proc-register-ext-mcp-server-httproute.adoc new file mode 100644 index 000000000000..86c145939321 --- /dev/null +++ b/modules/proc-register-ext-mcp-server-httproute.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-httproute_{context}"] += Creating an HTTPRoute for an external MCP server + +[role="_abstract"] +To use an external MCP server, you must create an `HTTPRoute` custom resource (CR) that matches your internal hostname and routes to the external service by using Istio. + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. +* You created `ServiceEntry` and `DestinationRule` objects. + +.Procedure + +. Create a `HTTPRoute` CR that routes to the external service by using the following example: ++ +.Example HTTPRoute CR +[source,yaml,subs="+quotes"] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: __ + namespace: __ +spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: __ + namespace: __ + hostnames: + - example.mcp.local + rules: + - matches: + - path: + type: PathPrefix + value: /mcp + filters: + - type: URLRewrite + urlRewrite: + hostname: __ + backendRefs: + - name: __ + kind: Hostname + group: networking.istio.io + port: 443 +---- ++ +* Replace the `metadata.name:` field value with the name of your external MCP server. +* Replace the `metadata.namespace:` field value with the namespace that the MCP server is in. +* Set the `spec.parentRefs:` fields to match your MCP `Gateway` object. +* The `spec.hostnames:` field value is your internal hostname. It must match your `*.mcp.local` `Gateway` CR value. +* The `spec.rules.matches.path.value:` field value is your MCP gateway endpoint. In this example, `/mcp` is used. +* Replace the value of `spec.rules.filters.urlRewrite.hostname:` with your external hostname. +* Replace the `spec.rules.backendRefs.name:` field value with the host URL of the MCP server. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name of your CR. diff --git a/modules/proc-register-ext-mcp-server-ingress.adoc b/modules/proc-register-ext-mcp-server-ingress.adoc new file mode 100644 index 000000000000..4f0927552147 --- /dev/null +++ b/modules/proc-register-ext-mcp-server-ingress.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-serviceentry_{context}"] += Creating a ServiceEntry for an external MCP server + +[role="_abstract"] +To register an external MCP server, you must first make sure that it has an ingress pathway by creating a `ServiceEntry` custom resource (CR) in your Istio deployment. {ocp} 4.19 and newer provides Istio through the Gateway API. + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. + +.Procedure + +. Create a `ServiceEntry` CR that registers the external server in the Istio service registry by using the following template: ++ +.Example ServiceEntry CR +[source,yaml,subs="+quotes"] +---- +apiVersion: networking.istio.io/v1beta1 +kind: ServiceEntry +metadata: + name: __ + namespace: __ +spec: + hosts: + - __ + ports: + - number: 443 + name: https + protocol: HTTPS + location: MESH_EXTERNAL + resolution: DNS +---- ++ +* Replace `__` with the name of your external MCP server. +* Replace `__` with the namespace that the MCP server is in. +* Replace `__` with the host URL of the MCP server. +* Replace any other values as required. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name of your CR. diff --git a/modules/proc-register-ext-mcp-server-mcpserverregistration.adoc b/modules/proc-register-ext-mcp-server-mcpserverregistration.adoc new file mode 100644 index 000000000000..3009228525f0 --- /dev/null +++ b/modules/proc-register-ext-mcp-server-mcpserverregistration.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-mcpserverregistration_{context}"] += Creating an MCPServerRegistration for an external MCP server + +[role="_abstract"] +To use an external MCP server, you must create an `MCPServerRegistration` custom resource (CR) that registers your external MCP server with the MCP gateway. + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. +* You created `ServiceEntry`, `DestinationRule`, `HTTPRoute`, and `Secret` objects. +* Recommended: You created an `AuthPolicy` CR. + +.Procedure + +. Create a `MCPServerRegistration` CR that registers the external MCP server with the MCP gateway by using the following example: ++ +.Example MCPServerRegistration CR +[source,yaml,subs="+quotes"] +---- +apiVersion: mcp.kuadrant.io/v1alpha1 +kind: MCPServerRegistration +metadata: + name: __ + namespace: __ +spec: + toolPrefix: _<"extserver_">_ + targetRef: + group: "gateway.networking.k8s.io" + kind: "HTTPRoute" + name: "__" + namespace: "__" + credentialRef: + name: __ + key: api-key +---- ++ +* Replace the `metadata.name:` field value with the name you want to use. +* Replace the `metadata.namespace:` field value with the namespace you need to use. If you did not use a `ReferenceGrant` CR, the value of `metadata.namespace:` must be the same as the namepsace specified in the `HTTPRoute` object. +* Replace the `spec.toolPrefix:` field with the value that you want to use to prefix the tools available with this MCP server. +* Replace the `spec.targetRef.name:` field value with the name of the `HTTPRoute` CR you applied. +* Replace the value of `spec.targetRef.namespace:` with the namespace where your `HTTPRoute` CR is applied. +* The `spec.credentialRef:` field points to the `Secret` CR that has credentials for the external MCP server. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name of your CR. diff --git a/modules/proc-register-ext-mcp-server-secret.adoc b/modules/proc-register-ext-mcp-server-secret.adoc new file mode 100644 index 000000000000..38f25edee218 --- /dev/null +++ b/modules/proc-register-ext-mcp-server-secret.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-secret_{context}"] += Creating a Secret for an external MCP server + +[role="_abstract"] +To use an external MCP server, you must create a `Secret` custom resource (CR) that stores backend API key credentials. + +This `Secret` CR is referenced in your `MCPServerRegistration` CR in the `credentialRef` parameter. These resources are for backend API key authentication. The `api-key` is stored in the config secret and used by the MCP broker component for upstream connections. + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. +* You created `ServiceEntry`, `DestinationRule`, and `HTTPRoute` objects. + +.Procedure + +. Create a `Secret` CR that stores backend API key credentials by using the following example: ++ +.Example Secret CR +[source,yaml,subs="+quotes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: __ + namespace: __ + labels: + mcp.kuadrant.io/secret: "true" + app.kubernetes.io/part-of: mcp-gateway + env: production +type: Opaque +stringData: + api-key: _<"mcp_prod_12abC34...">_ +---- ++ +* Replace the `metadata.name:` field value with the name you want to use. Service naming is used in this example. +* Replace the `metadata.namespace:` field value with the namespace you used in your `ServiceEntry` object. +* You must use the `metadata.labels.mcp.kuadrant.io/secret: "true"` field and value. If you do not use this value, the MCP gateway controller cannot see the `Secret` object. +* The `metadata.labels.app.kubernetes.io/part-of: mcp-gateway` field and value are optional. +* Replace your `stringData.api-key:` value with the one you need to use. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name of your CR. diff --git a/modules/proc-register-ext-mcp-server-tls.adoc b/modules/proc-register-ext-mcp-server-tls.adoc new file mode 100644 index 000000000000..0597ecd96627 --- /dev/null +++ b/modules/proc-register-ext-mcp-server-tls.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-tls_{context}"] += Creating TLS settings for an external MCP server + +[role="_abstract"] +To register an external MCP server, after you create a `ServiceEntry` custom resource (CR) in your Istio deployment, you must configure your TLS settings with a `DestinationRule` CR. + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. +* You created a `ServiceEntry` object. + +.Procedure + +. Create a `DestinationRule` CR that configure your TLS settings by using the following template: ++ +.Example DestinationRule CR +[source,yaml,subs="+quotes"] +---- +apiVersion: networking.istio.io/v1beta1 +kind: DestinationRule +metadata: + name: __ + namespace: __ +spec: + host: __ + trafficPolicy: + tls: + mode: SIMPLE + sni: __ +---- ++ +* Replace `__` with the name of your external MCP server. +* Replace `__` with the namespace that the MCP server is in. +* Replace `_` with the TLS traffic policy that you need according to your requirements. `SIMPLE` is the default value. Use `MUTUAL` in high-security environments or use `ISTIO_MUTUAL` with {service-mesh}. A value of `DISABLE` means that TLS is not used. +* Replace `__` with the host URL of the MCP server. + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f __ +---- ++ +Replace `__` with the name of your CR. diff --git a/modules/proc-register-ext-mcp-server-verify.adoc b/modules/proc-register-ext-mcp-server-verify.adoc new file mode 100644 index 000000000000..8e69fddf2fbd --- /dev/null +++ b/modules/proc-register-ext-mcp-server-verify.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-register-ext-mcp-server-verify_{context}"] += Verifying that your external MCP server is ready to use + +[role="_abstract"] +To verify that your an external MCP server is ready to use, check the status of your `MCPServerRegistration` custom resource (CR). + +.Prerequisites + +* You completed all of the installation and configuration steps for {mcpg}. +* You have the information for the external MCP server you want to connect to. +* You installed the {oc-first}. +* You are using Istio for ingress control. +* You completed the previous steps to register your MCP server with the MCP gateway. + +.Procedure + +* Check the status of all `MCPServerRegistration` CRs in the cluster by running the following command: ++ +[source,terminal] +---- +$ oc get mcpsr -A +---- ++ +.Example output +[source,text] +---- +NAMESPACE NAME READY TARGET-ROUTE PREFIX AGE +mcp-test mcp-server-ext True external-mcp-server extserver 14m +mcp-test mcp-server-one True mcp-api-key-server serverone 1d +mcp-test mcp-server-two True mcp-generic-route servertwo 2d +mcp-prod analytics-tools True analytics-route stats 5h +----