RHIDP-12608/12573: MCP doc updates for 1.10 (redhat-developer#2168)

* MCP doc updates for 1.10

* CQA changes

* CQA updates

* Incorporating Judy's comments

* Minor change

* Incorporated Judy's comments

* Update CQA error

Author: pabel-rh

assemblies/integrate_interacting-with-model-context-protocol-tools-for-rhdh/assembly-automate-software-resource-creation-with-scaffolder-mcp-tools.adoc

@@ -0,0 +1,26 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="automate-software-resource-creation-with-scaffolder-mcp-tools_{context}"]
+= Automate software resource creation with Scaffolder MCP tools
+:context: automate-software-resource-creation-with-scaffolder-mcp-tools
+
+[role="_abstract"]
+You can expose Scaffolder actions to AI agents by using Scaffolder Model Context Protocol (MCP) tools in {product}. 
+
+These tools enable AI agents to understand and involve Scaffolder capabilities through natural language input within an IDE or chat interface. You can validate template logic by using sandboxed dry-runs and monitor the progress of automated tasks. To maintain security, these tools must adhere to existing role-based access control (RBAC) permissions and maintain a consistent audit trail.
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-software-template-validation-with-scaffolder-dry-run-tools.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-scaffolder-dry-run-tool-reference.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-software-template-execution-with-scaffolder-mcp-tools.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-scaffolder-execution-tool-reference.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-scaffolder-task-monitoring-with-mcp-tools.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-scaffolder-tasks-list-tool-reference.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/integrate_interacting-with-model-context-protocol-tools-for-rhdh/assembly-automate-software-templates-by-using-scaffolder-mcp-tools.adoc

@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="automate-software-templates-by-using-scaffolder-mcp-tools_{context}"]
+= Automate Software Templates by using Scaffolder MCP tools
+:context: automate-software-templates-by-using-scaffolder-mcp-tools
+
+[role="_abstract"]
+Use the Scaffolder Model Context Protocol (MCP) (`scaffolder-mcp-extras`) tools to query available actions, validate template dry-runs, and retrieve task logs during Software Template development in {product-very-short}.
+
+These tools use provided credentials and adhere to existing role-based access control (RBAC) permissions.
+
+[IMPORTANT]
+====
+All operations performed through Scaffolder MCP tools use the `On Behalf Of the User` (OBOU) security model. The system uses the bearer token from the MCP client to ensure that actions adhere to existing RBAC permissions and maintain a consistent audit trail.
+====
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-list-scaffolder-actions.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-get-scaffolder-task-logs.adoc[leveloffset=+1]
+
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/integrate_interacting-with-model-context-protocol-tools-for-rhdh/assembly-install-the-mcp-server-and-tool-plugins-in-rhdh.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="install-the-mcp-server-and-tool-plugins-in-rhdh_{context}"]
+= Install the MCP server and tool plugins in {product}
+:context: install-the-mcp-server-and-tool-plugins-in-rhdh
+
+[role="_abstract"]
+As an administrator, you can enable Model Context Protocol (MCP) support in {product} by installing the backend server and tool plugins. 
+
+The backend MCP server plugin runs the MCP tools, while the individual tool plugins expose specific capabilities for the Software Catalog, TechDocs, and Scaffolder features.
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-install-the-backend-mcp-server-plugin.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-install-the-mcp-tool-plugins.adoc[leveloffset=+1]
+
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/integrate_interacting-with-model-context-protocol-tools-for-rhdh/assembly-troubleshoot-mcp-server-and-client-problems.adoc

@@ -10,9 +10,9 @@ Diagnose and resolve common issues with MCP server installation, client configur
 
 include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc[leveloffset=+1]
 
-include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-checking-mcp-tool-logs-for-status-and-errors.adoc[leveloffset=+1]
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-check-mcp-tool-logs-for-status-and-errors.adoc[leveloffset=+1]
 
-include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-understand-and-respond-to-mcp-tool-error-messages.adoc[leveloffset=+1]
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-mcp-tool-error-messages.adoc[leveloffset=+1]
 
 include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-resolve-the-model-does-not-support-tool-calling-error.adoc[leveloffset=+1]
 

…-respond-to-mcp-tool-error-messages.adoc …or-rhdh/con-mcp-tool-error-messages.adocmodules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-understand-and-respond-to-mcp-tool-error-messages.adoc renamed to modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-mcp-tool-error-messages.adoc modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-understand-and-respond-to-mcp-tool-error-messages.adoc renamed to modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-mcp-tool-error-messages.adoc

@@ -1,9 +1,9 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="understand-and-respond-to-mcp-tool-error-messages_{context}"]
-= Understand and respond to MCP tool error messages
+[id="mcp-tool-error-messages_{context}"]
+= MCP tool error messages
 
 [role="_abstract"]
 MCP tools provide optional error messages that communicate issues including input validation errors encountered during tool use.
 
-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.
+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.

…nderstanding-model-context-protocol.adoc …for-rhdh/con-model-context-protocol.adocmodules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-understanding-model-context-protocol.adoc renamed to modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-model-context-protocol.adoc modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-understanding-model-context-protocol.adoc renamed to modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-model-context-protocol.adoc

@@ -1,7 +1,7 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="understanding-model-context-protocol_{context}"]
-= Understanding Model Context Protocol
+[id="model-context-protocol_{context}"]
+= Model Context Protocol
 
 [role="_abstract"]
 Model Context Protocol (MCP) connects AI applications to external systems, enabling {product-short} MCP tools through the mcp-actions-backend plugin.

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-scaffolder-task-monitoring-with-mcp-tools.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="scaffolder-task-monitoring-with-mcp-tools_{context}"]
+= Scaffolder task monitoring with MCP tools
+
+[role="_abstract"]
+Scaffolder task monitoring provides visibility into the lifecycle of automated resource creation. By using MCP tools, you can track the progress of templates and retrieve execution results for workflows initiated by an AI agent.
+
+Monitoring capabilities include the following features:
+
+* User interaction: You must ask for a status update on your tasks or a list of recent activities.
+* Agent invocation: The AI agent calls the task list tool. To restrict results to only include your own tasks, the agent must set the `owned` parameter to `true`.
+* Outcome processing: The AI agent filters and summarizes the `tasks[]` list, reporting statuses such as `processing`, `completed`, or `failed`.
+

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-software-template-execution-with-scaffolder-mcp-tools.adoc

@@ -0,0 +1,15 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="software-template-execution-with-scaffolder-mcp-tools_{context}"]
+= Software Template execution with Scaffolder MCP tools
+
+[role="_abstract"]
+Automate resource creation, such as repositories or components, by executing Software Templates through the AI agent. 
+
+By using Scaffolder MCP tools, the AI agent interacts directly with your existing software templates to streamline the development lifecycle.
+
+The execution process relies on three core components:
+
+* User interaction: You must identify a reference for the target template (for example, `template:default/create-node`) and provide the necessary input `values` and `secrets`.
+* Agent invocation: The AI agent maps the data to the `templateRef`, `values`, and `secrets` parameters to execute the template.
+* Outcome processing: The AI agent confirms the execution and provides the `taskId` to the user for progress tracking.

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/con-software-template-validation-with-scaffolder-dry-run-tools.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="software-template-validation-with-scaffolder-dry-run-tools_{context}"]
+= Software Template validation with Scaffolder dry-run tools
+
+[role="_abstract"]
+With Software Template validation, you can verify YAML configuration and execution logic in a sandboxed environment. This preliminary testing ensures that your templates function as intended before you deploy them to a production environment.
+
+The validation process involves the following key components:
+
+* User interaction: You must provide the template YAML content, required input values, and any additional files.
+* Agent invocation: The AI agent maps these inputs to the `templateYAML`, `values`, and `files` parameters to invoke the dry-run tool.
+* Outcome processing: The AI agent interprets the `valid` status and execution logs to provide a plain-language summary or troubleshooting steps if validation fails.

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-configure-mcp-clients-to-access-the-rhdh-server.adoc

@@ -17,7 +17,7 @@ You must configure an MCP client before it can interact with the MCP server. For
 +
 [NOTE]
 ====
-If a client does not yet support the Streamable endpoint, you must use the SSE endpoint.
+Some clients do not yet support the Streamable endpoint. Use the SSE (Legacy) endpoint if your client requires it.
 ====
 
 * You have set the `MCP_TOKEN` environment variable in your MCP server configuration as the bearer token for authentication.