RHDHPAI-1087: MCP plugin doc - dev preview

artifacts/attributes.adoc

@@ -170,4 +170,7 @@
 :using-dynamic-plugins-book-title: Using dynamic plugins
 
 :scorecard-plugin-book-link: {product-docs-link}/html-single/understand_and_visualize_red_hat_developer_hub_project_health_using_scorecards/index
-:scorecard-plugin-book-title: Understand and visualize {product} project health using Scorecards
+:scorecard-plugin-book-title: Understand and visualize {product} project health using Scorecards
+
+: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}

artifacts/snip-developer-preview-mcp.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].
+====

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

@@ -0,0 +1,19 @@
+:_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::modules/model-context-protocol-tools/proc-configuring-mcp-tools-for-developer-lightspeed.adoc[leveloffset=+1]
+
+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,19 @@
+:_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
+
+The following procedures guide you through resolving common issues when using a Model Communication Protocol (MCP) server and tool.
+
+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-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-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/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 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/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-mcp.adoc[]
+
+*Model Context Protocol* (*MCP*) offers a standardized method for linking AI models and applications (*MCP clients*) with external systems (*MCP servers*). This connection facilitates access to information and workflows residing on those systems. *MCP servers* are responsible for defining the tools that MCP clients can interact with.
+
+{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 MCP tool enables MCP clients to search and retrieve documentation directly from TechDocs registered in your {product-very-short} instance. 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,12 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-checking-logs-for-mcp-tool-execution-and-errors.adoc_{context}"]
+= Checking MCP tool logs for status and errors
+
+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

@@ -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 before it can 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 `<{product-very-short}_HOST>` is the hostname of your {product-very-short} instance.
+
+** Streamable: https://<{product-very-short}_HOST>/api/mcp-actions/v1 
+** SSE (Legacy): https://<{product-very-short}_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,subs="+attributes,+quotes"]
+----
+{
+  "mcpServers": {
+    "backstage-actions": {
+      "url": "https://<{product-very-short}_HOST>/api/mcp-actions/v1",
+      "headers": {
+        "Authorization": "Bearer <MCP_TOKEN>"
+      }
+    }
+  }
+}
+----
+where:
+
+`<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,subs="+attributes,+quotes"]
+----
+mcpServers:
+  - name: backstage-actions
+    type: sse
+    url: https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse
+    requestOptions:
+      headers:
+        Authorization: "Bearer <MCP_TOKEN>"
+----
++
+where:
+
+`<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,subs="+attributes,+quotes"]
+----
+mcp_servers:
+  - name: mcp::backstage
+    provider_id: model-context-protocol
+    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`).
++
+[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} {my-app-config-file}` 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.

modules/model-context-protocol-tools/proc-configuring-mcp-tools-for-developer-lightspeed.adoc

@@ -0,0 +1,65 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-configure-mcp-tools-for-developer-lightspeed_{context}"]
+= Configuring the {product-very-short} Model Context Protocol (MCP) tools for {ls-short} (Optional)
+
+To leverage Model Context Protocol (MCP) servers like, the {model-context-protocol-link}[server in {product-very-short} with {ls-short}], you must first integrate them into the Llama Stack service. Configuring MCP in {lcs-short} enables the deployed {lcs-short} and Llama Stack to use external tools and retrieve real-time data. This integration allows the virtual assistant to execute complex actions and incorporate current operational context into its responses.
+
+Configuration requires synchronizing settings across three components: the Llama Stack tool definition, the {lcs-short} MCP server endpoint definition, and the {ls-brand-name} plugin MCP authorization token.
+
+For more information on configuring {ls-short}, see {developer-lightspeed-link}#proc-installing-and-configuring-lightspeed_developer-lightspeed[Installing and configuring {ls-brand-name}].
+
+.Prerequisites
+
+* You have configured {model-context-protocol-link}[MCP tools in your {product} instance].
+
+.Procedure
+. Configure the Llama Stack tool definition by defining the MCP provider in the `tool_runtime` section of the Llama Stack configuration file (`run.yaml`), as shown in the following code:
++
+[source,yaml]
+----
+providers:
+  tool_runtime:
+    - provider_id: model-context-protocol
+      provider_type: remote::model-context-protocol
+      config: {}
+----
+
+. Configure the {lcs-short} MCP server endpoint by defining the MCP server endpoints in the {lcs-short} configuration file (`lightspeed-stack.yaml`), as shown in the following code:
++
+[source,yaml]
+----
+mcp_servers:
+  - name: mcp::backstage
+    provider_id: model-context-protocol
+    url: https://<RHDH_HOST>/api/mcp-actions/v1
+----
+
+where:
+
+`<RHDH_HOST>`:: Hostname of your {product-very-short} instance
++
+[IMPORTANT]
+====
+`provider_id` must match the Llama Stack definition (`model-context-protocol`).
+====
+
+. Configure the {ls-brand-name} plugin authorization token by specifying the MCP servers and providing the token for authentication in the {ls-brand-name} plugin configuration file (`lightspeed-app-config.yaml`), as shown in the following code:
++
+[source,yaml]
+----
+lightspeed:
+  mcpServers:
+  - name: mcp::backstage
+    token: ${MCP_TOKEN}
+----
++
+[IMPORTANT]
+====
+`name` must match the {lcs-name} definition (`mcp::backstage`).
+====
+
+[NOTE]
+====
+Self-hosted models might provide inconsistent or poor performance when using tool calling features, such as the Model Context Protocol (MCP). It is recommended to use the latest foundation models from providers like `OpenAI`` when experimenting with this integration to ensure the most reliable functionality.
+====

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 MCP client applications to use the MCP protocol to access {product-very-short} information and workflows. This configuration is a prerequisite for MCP clients to use the defined MCP tools and access the exposed capabilities of {product-very-short}.
+
+.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} {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]
+----
+backend:  
+  auth:
+    externalAccess:
+      - type: static
+        options:
+          token: ${MCP_TOKEN}
+          subject: mcp-clients
+----
+where:
+
+`${MCP_TOKEN}`:: Set the token value that you generate manually and share with your MCP clients
++
+[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,subs="+attributes,+quotes"]
+----
+backend:
+  actions:
+    pluginSources:
+      - software-catalog-mcp-tool
+      - techdocs-mcp-tool
+----
++
+.Full `{my-app-config-file}` file example with MCP configuration
+[source,yaml,subs="+attributes,+quotes"]
+----
+app:
+  title: AI Dev Developer Hub
+  baseUrl: "${{product-very-short}_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: "${{product-very-short}_BASE_URL}"
+  cors:
+    origin: "${{product-very-short}_BASE_URL}"
+signInPage: oidc
+----