Incorporating Judy's comments

Author: pabel-rh

assemblies/assembly-resolving-common-problems-with-mcp-clients-and-tools.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: ASSEMBLY
+:previouscontext: {context}
+:context: proc-resolving-common-problems-with-mcp-clients-and-tools
+
+[id="{context}"]
+= Provisioning and using your custom {product} configuration
+
+The following procedures guide you through resolving common issues when using a Model Communication Protocol (MCP) client for tool calling.
+
+include::modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc[leveloffset=+1]

assemblies/assembly-troubleshooting-mcp-server-and-client-problems.adoc

@@ -10,4 +10,4 @@ include::modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-ex
 
 include::modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc[leveloffset=+1]
 
-include::modules/model-context-protocol-tools/proc-resolving-common-problems-with-mcp-clients-and-tools.adoc[leveloffset=+1]
+include::assembly-resolving-common-problems-with-mcp-clients-and-tools.adoc[leveloffset=+1]

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

@@ -7,10 +7,10 @@ You must configure an MCP client to interact with the MCP server. For more infor
 
 .Prerequisites
 
-* You have configured one of the following endpoints as the server URL, where `<RHDH_HOST>` is the hostname of your {product-very-short} instance.
+* You have configured one of the following endpoints as the server URL, where `<{product-very-short}_HOST>` is the hostname of your {product-very-short} instance.
 
-** Streamable: https://<RHDH_HOST>/api/mcp-actions/v1 
-** SSE (Legacy): https://<RHDH_HOST>/api/mcp-actions/v1/sse 
+** Streamable: https://<{product-very-short}_HOST>/api/mcp-actions/v1 
+** SSE (Legacy): https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse 
 +
 [NOTE]
 ====
@@ -21,7 +21,7 @@ Some clients do not yet support the Streamable endpoint, and you might need to u
 
 . Set the ${MCP_TOKEN} in your MCP server configuration as the bearer token when authenticating with the MCP server by completing the following steps:
 .. In the {ocp-short} web console, go to *Secrets*.
-.. Click *Create > Key/value secret*.*
+.. Click *Create > Key/value secret*.
 .. In the *Create key/value secret* page, select the *YAML view* option in *Configure via*, and add the following example:
 +
 [source,yaml]
@@ -37,17 +37,18 @@ stringData:
   LLM_SERVER_URL: _<server_url>_
 type: Opaque
 ----
+.. Click *Create*.
 
 * Configure the *Cursor* client.
 .. From your Desktop app, navigate to `Cursor Settings` and select `MCP Tools > New MCP Server`.
 .. Add the following configuration:
 +
-[source,yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 {
   "mcpServers": {
     "backstage-actions": {
-      "url": "https://<RHDH_HOST>/api/mcp-actions/v1",
+      "url": "https://<{product-very-short}_HOST>/api/mcp-actions/v1",
       "headers": {
         "Authorization": "Bearer <MCP_TOKEN>"
       }

modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-nonsensical-mcp-tool-output.adoc_{context}"]
+= Resolve nonsensical MCP tool output
+
+Nonsensical output often occurs when smaller models or models with smaller context sizes cannot effectively manage repeated tool calls within the same context window.
+
+.Procedure
+
+To improve the quality of the tool output, take the following actions:
+
+. Select an appropriate model for tool calling.
+.. Verify that the model has good support for tool calling.
+.. Make sure your model is not too small. We recommend a model with at least 7 billion parameters and a context window of 32k.
+. Refine your queries.
+.. Use more well-defined queries that limit the amount of data returned in the response from the tool.
+. If possible, increase the context window size of the model. We recommend at least 32k for these MCP tools.

modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-resolving-authentication-issues-when-tool-are-not-found.adoc_{context}"]
+= Resolving authentication issues when tools are not found
+
+If your MCP client connects to the server but cannot find deployed tools, an authentication or configuration issue is likely.
+
+.Procedure
+
+. Verify the authentication token.
+.. Configure a static token for the RHDH MCP server.
+.. Set this token as the bearer token in your MCP client and make sure the authorization header is the configuration specifies `Bearer` before the token, for example, `Bearer <mcp_token>`.
+. Check the MCP endpoint configuration.
+.. Confirm that the MCP server URL properly resolves, particularly if you are using a desktop client.
+.. Use *legacy SSE endpoint* if your MCP client requires it instead of the Streamable endpoint. (For more details, see the *Configuration* topic).
+. Verify your {product-very-short} `{my-app-config-file}` file for duplicate backend entries and make sure that the indentation is accurate.
+.. Make sure that the configuration for the static token and MCP plugin sources go under an existing backend field, if one is present.
+.. If you are unsure, see {model-context-protocol-link}#proc-configuring-model-context-protocol[the sample app configuration provided in the reference procedure].

modules/model-context-protocol-tools/proc-resolving-common-problems-with-mcp-clients-and-tools.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-resolving-the-model-does-not-support-tool-calling-error.adoc_{context}"]
+= Resolving the `Model does not support tool calling` error
+
+This error indicates that the model configured in your MCP client lacks the required functionality to handle tool calls. The error message appears similar to: `Invalid request: model gemma3:27b does not support tool calls`.
+
+.Procedure
+
+. Consult your model documentation to confirm its support for tool calling.
+. If the current model does not support tool calling, change the model that your MCP client uses to a tool-calling compatible model.

modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc

@@ -5,7 +5,7 @@
 
 .Procedure
 
-. Log in to the OCP cluster running RHDH and go to your {product-very-short} project using the following code:
+. Log in to the OCP cluster running {product-very-short} and go to your {product-very-short} project using the following code:
 +
 [source,subs="+attributes]
 ----

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

@@ -2,8 +2,8 @@ include::artifacts/attributes.adoc[]
 :context: title-model-context-protocol-tools
 :imagesdir: images
 :title: Interacting with Model Context Protocol tools for {product}
-:subtitle: Leverage the Model Context Protocol (MCP) server to integrate {product} ({product-very-short}) with AI clients. This connection provides a standardized method for AI applications to access RHDH information and workflows through defined MCP tools.
-:abstract: Leverage the Model Context Protocol (MCP) server to integrate {product} ({product-very-short}) with AI clients. This connection provides a standardized method for AI applications to access RHDH information and workflows through defined MCP tools
+:subtitle: Leveraging the Model Context Protocol (MCP) server to integrate {product} ({product-very-short}) with AI clients
+:abstract: Leverage the Model Context Protocol (MCP) server to integrate {product} ({product-very-short}) with AI clients. This connection provides a standardized method for AI applications to access {product-very-short} information and workflows through defined MCP tools.
 = {title}
 
 include::assemblies/assembly-model-context-protocol-tools.adoc[leveloffset=+1]