More Judy's comments

Author: pabel-rh

modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc

@@ -3,4 +3,4 @@
 [id="con-understand-and-respond-to-mcp-tool-error-messages.adoc_{context}"]
 = Understand and respond to MCP tool error messages
 
-The response from the MCP tools provides an optional error message output that are used to communicate any errors encountered during the execution of the tool, in addition to potential input validation errors.
+The MCP tools response provides an optional error message that communicates any issues encountered during the use of the tool, including potential input validation errors.

modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc

@@ -3,9 +3,10 @@
 [id="proc-checking-logs-for-mcp-tool-execution-and-errors.adoc_{context}"]
 = Checking logs for MCP tool execution and errors
 
-The {backstage} `LoggerService`` target name starts with the name of the MCP tool (either `software-catalog-mcp-tool` or `techdocs-mcp-tool`). By default, a log is generated when the MCP tools are being executed, For example:
-+
-[source=]
-`[backend]: 2025-09-25T16:24:22.660Z software-catalog-mcp-tool info fetch-catalog-entities: Fetching catalog entities with options: kind="Component"`
+The {backstage} `LoggerService` target name starts with the name of the MCP tool (either `software-catalog-mcp-tool` or `techdocs-mcp-tool`). The MCP tools generate a log by default. For example:
 
+[source,terminal]
+----
+`[backend]: 2025-09-25T16:24:22.660Z software-catalog-mcp-tool info fetch-catalog-entities: Fetching catalog entities with options: kind="Component"`
+----
 If any errors occur in the MCP tools, check the logs.

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

@@ -56,41 +56,43 @@ type: Opaque
   }
 }
 ----
-
 where:
-`<MCP_TOKEN>`:: Previously configured static token
-`<RHDH_HOST>`:: Hostname of your {product-very-short} instance
+
+`<MCP_TOKEN>`:: Enter the previously configured static token
+`<{product-very-short}_HOST>`:: Enter the hostname of your {product-very-short} instance
 
 * Configure the *Continue* client.
+
 .. In your agent yaml configuration file, add the following configuration:
 +
-[source,yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 mcpServers:
   - name: backstage-actions
     type: sse
-    url: https://<RHDH_HOST>/api/mcp-actions/v1/sse
+    url: https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse
     requestOptions:
       headers:
         Authorization: "Bearer <MCP_TOKEN>"
 ----
 
 where:
-`<MCP_TOKEN>`:: Previously configured static token
-`<RHDH_HOST>`:: Hostname of your {product-very-short} instance
+
+`<MCP_TOKEN>`:: Enter the previously configured static token
+`<{product-very-short}_HOST>`:: Enter the 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`:
 +
-[source,yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 mcp_servers:
   - name: mcp::backstage
     provider_id: model-context-protocol
-    url: https://<RHDH_HOST>/api/mcp-actions/v1
+    url: https://<{product-very-short}_HOST>/api/mcp-actions/v1
 ----
-
 where:
+
 `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`).
@@ -103,7 +105,7 @@ providers:
     provider_type: remote::model-context-protocol
     config: {}
 ----
-.. 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} {my-app-config-file}` file, to make POST requests to the LCS `/v1/streaming_query` endpoint, as shown in the following code:
 +
 [source,yaml]
 ----
@@ -117,14 +119,12 @@ lightspeed:
 [source,yaml]
 ----
 curl -X POST \
-  -H 'Content-Type: application/json' \
-  -H 'MCP-HEADERS: {"mcp::backstage": {"Authorization": "Bearer <MCP_TOKEN>"}}' \
-  -d '{"query": "Can you give me all catalog templates of type 'service', "model": "gpt-4o-mini", "provider": "openai"}' \
+  -H `Content-Type: application/json` \
+  -H `MCP-HEADERS: {"mcp::backstage": {"Authorization": "Bearer <MCP_TOKEN>"}}` \
+  -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>`:: Specify the **LCS endpoint**. Use `localhost` (`127.0.0.1:8080`) or the service name if operating within the `{backstage}` container.
+`<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.

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

@@ -11,7 +11,7 @@ You can enable your AI client applications to access {product-very-short} inform
 
 .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:
+. In your {product} {my-app-config-file}` 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:
 +
 [source,yaml]
 ----
@@ -23,38 +23,38 @@ backend:
           token: ${MCP_TOKEN}
           subject: mcp-clients
 ----
-+
 where:
-`${MCP_TOKEN}`:: Set the token value that you generate.
 
+`${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")'
+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]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 backend:
   actions:
     pluginSources:
       - software-catalog-mcp-tool
       - techdocs-mcp-tool
 ----
-
-.`app-config.yaml` file with MCP configuration example
-[source,yaml]
++
+.`{my-app-config-file}` file with MCP configuration example
+[source,yaml,subs="+attributes,+quotes"]
 ----
 app:
   title: AI Dev Developer Hub
-  baseUrl: "${RHDH_BASE_URL}"
+  baseUrl: "${{product-very-short}_BASE_URL}"
 auth:
   environment: development
   session:
@@ -75,8 +75,8 @@ backend:
           subject: mcp-clients
     keys:
       - secret: "${BACKEND_SECRET}"
-  baseUrl: "${RHDH_BASE_URL}"
+  baseUrl: "${{product-very-short}_BASE_URL}"
   cors:
-    origin: "${RHDH_BASE_URL}"
+    origin: "${{product-very-short}_BASE_URL}"
 signInPage: oidc
 ----

modules/model-context-protocol-tools/proc-finding-a-specific-techdoc-using-retrieve-techdocs-content.adoc

@@ -3,7 +3,7 @@
 [id="proc-finding-a-specific-techdoc-using-retrieve-techdocs-content_{context}"]
 = Finding a specific TechDoc using `retrieve-techdocs-content`
 
-The `retrieve-techdocs-content` TechDocs MCP tool retrieves the content of a TechDocs resource, enabling AI clients to access documentation content for specific Software Catalog entities. By default, the tool returns a JSON entity with the following fields: 'entityRef', 'name', 'title', 'kind', 'namespace', 'content', 'path', 'contentType', 'lastModified', and 'metadata'.
+The `retrieve-techdocs-content` TechDocs MCP tool retrieves the content of a TechDocs resource, enabling AI clients to access documentation content for specific Software Catalog entities. By default, the tool returns a JSON entity with the following fields: `entityRef`, `name`, `title`, `kind`, `namespace`, `content`, `path`, `contentType`, `lastModified`, and `metadata`.
 
 The following examples show common queries:
 

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

@@ -5,8 +5,8 @@
 
 To enable MCP support in {product}, you need to install the following components:
 
-* Backend MCP server plugin: Runs the MCP tools.
-* MCP tool plugins: Facilitates integration with the Software Catalog and TechDocs.
+Backend MCP server plugin:: Runs the MCP tools.
+MCP tool plugins:: Facilitates integration with the Software Catalog and TechDocs.
 
 .Prerequisites
 

modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc

@@ -3,7 +3,7 @@
 [id="proc-measuring-doc-gaps-using-analyze-techdocs-coverage_{context}"]
 = Measuring documentation gaps using `analyze-techdocs-coverage`
 
-The `analyze-techdocs-coverage` TechDocs MCP tool calculates the percentage of entities that have TechDocs configured, helping identify documentation gaps and improve overall documentation coverage. This tool supports filtering by entity type, namespace, owner, lifecycle, and tags to analyze coverage for specific subsets of entities. By default, it returns a JSON entity that includes the fields 'totalEntities', 'entitiesWithDocs', and 'coveragePercentage'.
+The `analyze-techdocs-coverage` TechDocs MCP tool calculates the percentage of entities that have TechDocs configured. This tool identifies documentation gaps and improve overall documentation coverage. This tool supports filtering by entity type, namespace, owner, lifecycle, and tags to analyze coverage for specific subsets of entities. By default, it returns a JSON entity that includes the fields `totalEntities`, `entitiesWithDocs`, and `coveragePercentage`.
 
 The following examples show common queries: