Skip to content

Commit bceea79

Browse files
pabel-rhpabel-rh
authored
RHDHPAI-1087: MCP plugin doc - dev preview (#1462)
* MCP plugin doc - dev preview * Minor update * removed attributes for code blocks that dont use * Minor changes * Added a step regarding Llama stack * Incorporated tech comments * Updated test day comment * Incorporated test day comments * Updating dev preview * Added MCP token * Incorporating Judy's comments * More Judy's comments * Minor change * Peer review * Fixed typos * Indentation changes * Incorporated Ben's comments * Moved lightspeed section here * Adding locations for MCP to lightspeed * minor
1 parent b3acb69 commit bceea79

27 files changed

+672
-1
lines changed

‎artifacts/attributes.adoc‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,4 +170,7 @@
170170
:using-dynamic-plugins-book-title: Using dynamic plugins
171171

172172
:scorecard-plugin-book-link: {product-docs-link}/html-single/understand_and_visualize_red_hat_developer_hub_project_health_using_scorecards/index
173-
:scorecard-plugin-book-title: Understand and visualize {product} project health using Scorecards
173+
:scorecard-plugin-book-title: Understand and visualize {product} project health using Scorecards
174+
175+
:model-context-protocol-link: {product-docs-link}/html-single/interacting_with_model_context_protocol_tools_for_red_hat_developer_hub/index
176+
:model-context-protocol-title: Interacting with Model Context Protocol tools for {product}

‎artifacts/snip-developer-preview-mcp.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[IMPORTANT]
2+
====
3+
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.
4+
5+
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].
6+
====

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-model-context-protocol-tools"]
4+
= Interacting with Model Context Protocol tools for {product}
5+
:context: assembly-model-context-protocol-tools
6+
7+
include::modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc[leveloffset=+1]
8+
9+
include::modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc[leveloffset=+1]
10+
11+
include::modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc[leveloffset=+1]
12+
13+
include::modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc[leveloffset=+2]
14+
15+
include::modules/model-context-protocol-tools/proc-configuring-mcp-tools-for-developer-lightspeed.adoc[leveloffset=+1]
16+
17+
include::assembly-using-the-mcp-tools-to-access-data.adoc[leveloffset=+1]
18+
19+
include::assembly-troubleshooting-mcp-server-and-client-problems.adoc[leveloffset=+1]

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-troubleshooting-mcp-server-and-client-problems"]
4+
= Troubleshooting MCP server and client problems
5+
:context: assembly-troubleshooting-mcp-server-and-client-problems
6+
7+
The following procedures guide you through resolving common issues when using a Model Communication Protocol (MCP) server and tool.
8+
9+
include::modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc[leveloffset=+1]
10+
11+
include::modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc[leveloffset=+1]
12+
13+
include::modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc[leveloffset=+1]
14+
15+
include::modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc[leveloffset=+1]
16+
17+
include::modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc[leveloffset=+1]
18+
19+
include::modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc[leveloffset=+1]

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-using-the-mcp-tools-to-access-data"]
4+
= Using the MCP tools to access data from {product}
5+
:context: assembly-using-the-mcp-tools-to-access-data
6+
7+
MCP tool plugins enable seamless integration with the Software Catalog and TechDocs.
8+
9+
include::modules/model-context-protocol-tools/proc-retrieving-software-catalog-data-through-mcp-tool.adoc[leveloffset=+1]
10+
11+
include::modules/model-context-protocol-tools/proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc[leveloffset=+1]
12+
13+
include::modules/model-context-protocol-tools/proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs.adoc[leveloffset=+2]
14+
15+
include::modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc[leveloffset=+2]
16+
17+
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‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-understand-and-respond-to-mcp-tool-error-messages.adoc_{context}"]
4+
= Understand and respond to MCP tool error messages
5+
6+
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‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="understanding-model-context-protocol"]
4+
= Understanding Model Context Protocol
5+
6+
include::{docdir}/artifacts/snip-developer-preview-mcp.adoc[]
7+
8+
*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.
9+
10+
{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‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools_{context}"]
4+
= Accessing and analyzing documentation using the TechDocs MCP tools
5+
6+
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.
7+
8+
The following TechDocs MCP tools are supported:
9+
* `fetch-techdocs`
10+
* `analyze-techdocs-coverage`
11+
* `retrieve-techdocs-content`

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="proc-checking-logs-for-mcp-tool-execution-and-errors.adoc_{context}"]
4+
= Checking MCP tool logs for status and errors
5+
6+
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:
7+
8+
[source,terminal]
9+
----
10+
`[backend]: 2025-09-25T16:24:22.660Z software-catalog-mcp-tool info fetch-catalog-entities: Fetching catalog entities with options: kind="Component"`
11+
----
12+
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‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="proc-configuring-mpc-clients-to-access-the-rhdh-server_{context}"]
4+
= Configuring MCP clients to access the {product-very-short} server
5+
6+
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].
7+
8+
.Prerequisites
9+
10+
* 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.
11+
12+
** Streamable: https://<{product-very-short}_HOST>/api/mcp-actions/v1
13+
** SSE (Legacy): https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse
14+
+
15+
[NOTE]
16+
====
17+
Some clients do not yet support the Streamable endpoint, and you might need to use the SSE endpoint instead.
18+
====
19+
20+
* You have set the ${MCP_TOKEN} in your MCP server configuration as the bearer token when authenticating with the MCP server.
21+
22+
.Procedure
23+
24+
. Configure the *Cursor* client.
25+
.. From your Desktop app, navigate to *Cursor Settings* and select *MCP Tools > New MCP Server*.
26+
.. Add the following configuration:
27+
+
28+
[source,yaml,subs="+attributes,+quotes"]
29+
----
30+
{
31+
"mcpServers": {
32+
"backstage-actions": {
33+
"url": "https://<{product-very-short}_HOST>/api/mcp-actions/v1",
34+
"headers": {
35+
"Authorization": "Bearer <MCP_TOKEN>"
36+
}
37+
}
38+
}
39+
}
40+
----
41+
where:
42+
43+
`<MCP_TOKEN>`:: Enter the previously configured static token
44+
`<{product-very-short}_HOST>`:: Enter the hostname of your {product-very-short} instance
45+
46+
. Configure the *Continue* client.
47+
48+
.. In your agent yaml configuration file, add the following configuration:
49+
+
50+
[source,yaml,subs="+attributes,+quotes"]
51+
----
52+
mcpServers:
53+
- name: backstage-actions
54+
type: sse
55+
url: https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse
56+
requestOptions:
57+
headers:
58+
Authorization: "Bearer <MCP_TOKEN>"
59+
----
60+
+
61+
where:
62+
63+
`<MCP_TOKEN>`:: Enter the previously configured static token
64+
`<{product-very-short}_HOST>`:: Enter the hostname of your {product-very-short} instance
65+
66+
. Configure the *Lightspeed Plugin/Lightspeed Core (LCS)* client.
67+
.. In the `lightspeed-stack.yaml` configuration, add the following configuration for `mcp_servers`:
68+
+
69+
[source,yaml,subs="+attributes,+quotes"]
70+
----
71+
mcp_servers:
72+
- name: mcp::backstage
73+
provider_id: model-context-protocol
74+
url: https://<{product-very-short}_HOST>/api/mcp-actions/v1
75+
----
76+
where:
77+
78+
`model-context-protocol`:: This is the tool runtime provider defined and configured in the llama-stack `run.yaml` configuration for use in LCS.
79+
80+
.. Optional: If you want to use your own Llama Stack configuration, add the following code to your Llama Stack configuration file (`run.yaml`).
81+
+
82+
[source,yaml]
83+
----
84+
providers:
85+
tool_runtime:
86+
- provider_id: model-context-protocol
87+
provider_type: remote::model-context-protocol
88+
config: {}
89+
----
90+
.. 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:
91+
+
92+
[source,yaml]
93+
----
94+
lightspeed:
95+
mcpServers:
96+
- name: mcp::backstage
97+
token: ${MCP_TOKEN}
98+
----
99+
.. 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:
100+
+
101+
[source,yaml]
102+
----
103+
curl -X POST \
104+
-H `Content-Type: application/json` \
105+
-H `MCP-HEADERS: {"mcp::backstage": {"Authorization": "Bearer <MCP_TOKEN>"}}` \
106+
-d `{"query": "Can you give me all catalog templates of type 'service', "model": "gpt-4o-mini", "provider": "openai"}` \
107+
_<url>_/v1/streaming_query
108+
----
109+
110+
where:
111+
112+
`<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.

0 commit comments

Comments
 (0)