Incorporated tech comments

Author: pabel-rh

artifacts/attributes.adoc

@@ -168,3 +168,6 @@
 :upgrading-book-title: Upgrading {product}
 :using-dynamic-plugins-book-link: {product-docs-link}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index
 :using-dynamic-plugins-book-title: Using dynamic plugins
+
+:model-context-protocol-link: {product-docs-link}/html-single/interacting_with_model_context_protocol_tools_for_red_hat_developer_hub/index
+:model-context-protocol-title: Interacting with Model Context Protocol tools for {product}

modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc

@@ -5,6 +5,6 @@
 
 include::{docdir}/artifacts/snip-developer-preview.adoc[]
 
-The Model Context Protocol (MCP) server offers a standardized method for linking AI models and applications (MCP clients) with external systems. This connection facilitates access to information and workflows residing on those systems. MCP servers are responsible for defining the tools that AI applications can utilize to retrieve this data.
+Model Context Protocol (MCP) offers a standardized method for linking AI models and applications (MCP clients) with external systems. This connection facilitates access to information and workflows residing on those systems. MCP servers are responsible for defining the tools that AI applications can utilize to retrieve this data.
 
 {product} supports running MCP tools through the `mcp-actions-backend` plugin available in {backstage} 1.40 or later. 

modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc

@@ -38,10 +38,10 @@ Some clients do not yet support the Streamable endpoint, and you might need to u
   }
 }
 ----
-+
+
 where:
 `<MCP_TOKEN>`:: Previously configured static token
-`<RHDH_TOKEN>`:: Hostname of your {product-very-short} instance
+`<RHDH_HOST>`:: Hostname of your {product-very-short} instance
 
 * Configure the *Continue* client.
 .. In your agent yaml configuration file, add the following configuration:
@@ -56,10 +56,10 @@ mcpServers:
       headers:
         Authorization: "Bearer <MCP_TOKEN>"
 ----
-+
+
 where:
 `<MCP_TOKEN>`:: Previously configured static token
-`<RHDH_TOKEN>`:: Hostname of your {product-very-short} instance
+`<RHDH_HOST>`:: Hostname of your {product-very-short} instance
 
 * Configure the *Lightspeed Plugin/Lightspeed Core (LCS)* client.
 .. In the `lightspeed-stack.yaml` configuration, add the following configuration for `mcp_servers`:
@@ -71,9 +71,10 @@ mcp_servers:
     provider_id: model-context-protocol
     url: https://<RHDH_HOST>/api/mcp-actions/v1
 ----
-+
+
 where:
-`model-context-protocol`:: Enter this definition in your llama-stack `run.yaml` configuration for use in LCS.
+`model-context-protocol`:: This is the tool runtime provider defined and configured in the llama-stack `run.yaml` configuration for use in LCS.
+
 .. Optional: If you want to use your own Llama Stack configuration, add the following code to your Llama Stack configuration file (`run.yaml`).
 +
 [source,yaml]
@@ -84,7 +85,7 @@ providers:
     provider_type: remote::model-context-protocol
     config: {}
 ----
-.. Optional: To authorize requests to the MCP endpoint using `<MCP_TOKEN>`, add it in the `{ls-short} app-config.yaml` file, to make POST requests to the LCS `/v1/streaming_query` endpoint, as shown in the following code:
+.. To authorize requests to the MCP endpoint using `<MCP_TOKEN>`, add it in the `{ls-short} app-config.yaml` file, to make POST requests to the LCS `/v1/streaming_query` endpoint, as shown in the following code:
 +
 [source,yaml]
 ----
@@ -103,6 +104,9 @@ curl -X POST \
   -d '{"query": "Can you give me all catalog templates of type 'service', "model": "gpt-4o-mini", "provider": "openai"}' \
   _<url>_/v1/streaming_query
 ----
-+
+
+where:
+`<url>`:: Enter the LCS endpoint. You can use localhost(<{product-very-short}_servicename>.<{product-very-short}-namespace>.svc.cluster.local:8080) or the service name for this field if you are inside the {backstage} container.
+
 where:
-`<url>`:: Enter the LCS endooint. You can retrieve the LCS endpoint by using `curl` in the {backstage} container.
+`<url>`:: Specify the **LCS endpoint**. Use `localhost` (`127.0.0.1:8080`) or the service name if operating within the `{backstage}` container.

modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc

@@ -5,6 +5,10 @@
 
 You can enable your AI client applications to access {product-very-short} information and workflows. This configuration is a prerequisite for AI clients to use the defined MCP tools and leverage {product-very-short} data.
 
+.Prerequisite
+
+* You have {model-context-protocol-link}#proc-installing-the-mcp-server-and-tool-plugins[installed the MCP server and tool plugins in {product}].
+
 .Procedure
 
 . In your `{product} app-config.yaml` file, configure a static token for authentication against the MCP server endpoint. MCP clients (such as `Cursor`, `Continue`, or `Lightspeed Core`) use these tokens to authenticate against the {backstage} MCP server. For example:
@@ -23,6 +27,17 @@ backend:
 where:
 `${MCP_TOKEN}`:: Set the token value that you generate.
 
+[NOTE]
+====
+Tokens must be long and complex strings without whitespace to prevent brute-force guessing.
+
+To generate a sample token, use the following command:
+[source,bash]
+----
+node -p 'require("crypto").randomBytes(24).toString("base64")'
+----
+====
+
 . Register the MCP tools that you install as a plugin source, as shown in the following example:
 +
 [source,yaml]
@@ -56,7 +71,7 @@ backend:
     externalAccess:
       - type: static
         options:
-          token: ${ADMIN_TOKEN}
+          token: ${MCP_TOKEN}
           subject: mcp-clients
     keys:
       - secret: "${BACKEND_SECRET}"

modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc

@@ -27,13 +27,13 @@ plugins:
 +
 [source,yaml]
 ----
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.1.2!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
     disabled: false
 ----
 ** To install the TechDocs MCP tool, in your dynamic plugins ConfigMap (for example, `dynamic-plugins-rhdh.yaml`), add the TechDocs MCP tool plugin as shown in the following example:
 +
 [source,yaml]
 ----
-- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool:bs_1.42.5__0.1.2!red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool
+- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool:bs_1.42.5__0.3.0!red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool
   disabled: false
 ----

modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc

@@ -25,16 +25,16 @@ oc logs -c install-dynamic-plugins deployment/<my-product-deployment>
 [source]
 ----
 ..... prior logs ....
-======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0!backstage-plugin-mcp-actions-backend
+======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend
 	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0 to local filesystem
-	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0!backstage-plugin-mcp-actions-backend
+	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend
 ----
 . You must see entries for any of the MCP tool plugins you installed as shown in the following code:
 +
 [source]
 ----
 ..... prior logs ....
-======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:next__0.2.0!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
-	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:next__0.2.0 to local filesystem
-	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:next__0.2.0!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
+======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
+	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool to local filesystem
+	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
 ----