RHDHPAI-1087: MCP plugin doc - dev preview

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}

assemblies/assembly-model-context-protocol-tools.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-model-context-protocol-tools"]
+= Interacting with Model Context Protocol tools for {product}
+:context: assembly-model-context-protocol-tools
+
+include::modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc[leveloffset=+2]
+
+include::assembly-using-the-mcp-tools-to-access-data.adoc[leveloffset=+1]
+
+include::assembly-troubleshooting-mcp-server-and-client-problems.adoc[leveloffset=+1]

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

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-troubleshooting-mcp-server-and-client-problems"]
+= Troubleshooting MCP server and client problems
+:context: assembly-troubleshooting-mcp-server-and-client-problems
+
+include::modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc[leveloffset=+1]
+
+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]

assemblies/assembly-using-the-mcp-tools-to-access-data.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-using-the-mcp-tools-to-access-data"]
+= Using the MCP tools to access data from {product}
+:context: assembly-using-the-mcp-tools-to-access-data
+
+MCP tool plugins enable seamless integration with the Software Catalog and TechDocs.
+
+include::modules/model-context-protocol-tools/proc-retrieving-software-catalog-data-through-mcp-tool.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc[leveloffset=+1]
+
+include::modules/model-context-protocol-tools/proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs.adoc[leveloffset=+2]
+
+include::modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc[leveloffset=+2]
+
+include::modules/model-context-protocol-tools/proc-finding-a-specific-techdoc-using-retrieve-techdocs-content.adoc[leveloffset=+2]

modules/model-context-protocol-tools/artifacts/snip-developer-preview.adoc

@@ -0,0 +1,6 @@
+[IMPORTANT]
+====
+This section describes Developer Preview features in the Model Context Protocol plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA.
+
+For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope].
+====

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

@@ -0,0 +1,6 @@
+:_mod-docs-content-type: CONCEPT
+
+[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.

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

@@ -0,0 +1,10 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="understanding-model-context-protocol"]
+= Understanding Model Context Protocol
+
+include::{docdir}/artifacts/snip-developer-preview.adoc[]
+
+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-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools_{context}"]
+= Accessing and analyzing documentation using the TechDocs MCP tools
+
+The TechDocs Model Context Protocol (MCP) tool enables AI clients to search and retrieve documentation directly from {product-very-short} TechDocs instances. Use this tool to query documentation content and integrate it as context into your AI applications.
+
+The following TechDocs MCP tools are supported:
+* `fetch-techdocs`
+* `analyze-techdocs-coverage`
+* `retrieve-techdocs-content`

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

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: PROCEDURE
+
+[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"`
+
+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

@@ -0,0 +1,112 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-configuring-mpc-clients-to-access-the-rhdh-server_{context}"]
+= Configuring MCP clients to access the {product-very-short} server
+
+You must configure an MCP client to interact with the MCP server. For more information on the list of clients and their respective configurations, see https://modelcontextprotocol.io/clients[Example Clients].
+
+.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.
+
+** Streamable: https://<RHDH_HOST>/api/mcp-actions/v1 
+** SSE (Legacy): https://<RHDH_HOST>/api/mcp-actions/v1/sse 
++
+[NOTE]
+====
+Some clients do not yet support the Streamable endpoint, and you might need to use the SSE endpoint instead. 
+====
+
+* You have set the ${MCP_TOKEN} in your MCP server configuration as the bearer token when authenticating with the MCP server. 
+
+.Procedure
+
+* 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]
+----
+{
+  "mcpServers": {
+    "backstage-actions": {
+      "url": "https://<RHDH_HOST>/api/mcp-actions/v1",
+      "headers": {
+        "Authorization": "Bearer <MCP_TOKEN>"
+      }
+    }
+  }
+}
+----
+
+where:
+`<MCP_TOKEN>`:: Previously configured static token
+`<RHDH_HOST>`:: Hostname of your {product-very-short} instance
+
+* Configure the *Continue* client.
+.. In your agent yaml configuration file, add the following configuration:
++
+[source,yaml]
+----
+mcpServers:
+  - name: backstage-actions
+    type: sse
+    url: https://<RHDH_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
+
+* Configure the *Lightspeed Plugin/Lightspeed Core (LCS)* client.
+.. In the `lightspeed-stack.yaml` configuration, add the following configuration for `mcp_servers`:
++
+[source,yaml]
+----
+mcp_servers:
+  - name: mcp::backstage
+    provider_id: model-context-protocol
+    url: https://<RHDH_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`).
++
+[source,yaml]
+----
+providers:
+  tool_runtime:
+  - provider_id: model-context-protocol
+    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:
++
+[source,yaml]
+----
+lightspeed:
+  mcpServers:
+  - name: mcp::backstage
+    token: ${MCP_TOKEN}
+----
+.. Optional: You can query the LCS `/v1/streaming_query` endpoint directly by providing the `MCP_TOKEN` in the header, as shown in the following code:
++
+[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"}' \
+  _<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.

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

@@ -0,0 +1,82 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-configuring-model-context-protocol_{context}"]
+= Configuring Model Context Protocol in {product}
+
+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:
++
+[source,yaml]
+----
+backend:  
+  auth:
+    externalAccess:
+      - type: static
+        options:
+          token: ${MCP_TOKEN}
+          subject: mcp-clients
+----
++
+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]
+----
+backend:
+  actions:
+    pluginSources:
+      - software-catalog-mcp-tool
+      - techdocs-mcp-tool
+----
+
+.`app-config.yaml` file with MCP configuration example
+[source,yaml]
+----
+app:
+  title: AI Dev Developer Hub
+  baseUrl: "${RHDH_BASE_URL}"
+auth:
+  environment: development
+  session:
+    secret: "${BACKEND_SECRET}"
+  providers:
+    guest:
+      dangerouslyAllowOutsideDevelopment: true
+backend:
+  actions:
+    pluginSources:
+      - 'software-catalog-mcp-tool'
+      - 'techdocs-mcp-tool'
+  auth:
+    externalAccess:
+      - type: static
+        options:
+          token: ${MCP_TOKEN}
+          subject: mcp-clients
+    keys:
+      - secret: "${BACKEND_SECRET}"
+  baseUrl: "${RHDH_BASE_URL}"
+  cors:
+    origin: "${RHDH_BASE_URL}"
+signInPage: oidc
+----

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

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: PROCEDURE
+
+[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 following examples show common queries:
+
+* “Fetch techdoc with reference component:default/my-service”
+* “Fetch page about.html from techdoc with reference component:default/my-service”
+
+.Procedure
+* Use the parameters as shown in the following table to configure your `retrieve-techdocs-content` TechDocs MCP tool.
+
+|===
+| Name | Description | Example
+
+| `entityRef`
+| Specifies the entity to retrieve using the `kind:namespace/name` format.
+| "component:default/my-service"
+
+| `pagePath`
+| Specifies the path to a specific documentation page. Defaults to `index.html`
+| "index.html"
+
+|===

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

@@ -0,0 +1,39 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-installing-the-mcp-server-and-tool-plugins_{context}"]
+= Installing the MCP server and tool plugins in {product}
+
+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.
+
+.Prerequisites
+
+* Your {product-very-short} instance is installed and running.
+
+.Procedure
+
+. Install the backend MCP server plugin: In your dynamic plugins ConfigMap (for example, `dynamic-plugins-rhdh.yaml`), add the MCP server plugin as shown in the following example:
++
+[source,yaml]
+----
+plugins:
+    - package: 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
+      disabled: false
+----
+. Install any of the following MCP tools that you would like to use:
+** To install the Software Catalog MCP tool, in your dynamic plugins ConfigMap (for example, `dynamic-plugins-rhdh.yaml`), add the Software Catalog 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-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.3.0!red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool
+  disabled: false
+----