Skip to content

Commit 000e4f1

Browse files
pabel-rhpabel-rh
committed
MCP plugin doc - dev preview
1 parent c067490 commit 000e4f1

23 files changed

+562
-0
lines changed

‎assemblies/assembly-model-context-protocol-tools.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-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::assembly-using-the-mcp-tools-to-access-data.adoc[leveloffset=+1]
16+
17+
include::assembly-troubleshooting-mcp-server-and-client-problems.adoc[leveloffset=+1]

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
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+
include::modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc[leveloffset=+1]
8+
9+
include::modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc[leveloffset=+1]
10+
11+
include::modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc[leveloffset=+1]
12+
13+
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‎

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

‎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 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‎

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.adoc[]
7+
8+
The Model Context Protocol (MCP) server 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.
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 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.
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: 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-checking-logs-for-mcp-tool-execution-and-errors.adoc_{context}"]
4+
= Checking logs for MCP tool execution 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`). By default, a log is generated when the MCP tools are being executed, For example:
7+
+
8+
[source=]
9+
`[backend]: 2025-09-25T16:24:22.660Z software-catalog-mcp-tool info fetch-catalog-entities: Fetching catalog entities with options: kind="Component"`
10+
11+
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: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
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 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].
7+
8+
.Prerequisites
9+
10+
* You have configured one of the following endpoints as the server URL, where `<RHDH_HOST>` is the hostname of your {product-very-short} instance.
11+
12+
** Streamable: https://<RHDH_HOST>/api/mcp-actions/v1
13+
** SSE (Legacy): https://<RHDH_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]
29+
----
30+
{
31+
"mcpServers": {
32+
"backstage-actions": {
33+
"url": "https://<RHDH_HOST>/api/mcp-actions/v1",
34+
"headers": {
35+
"Authorization": "Bearer <MCP_TOKEN>"
36+
}
37+
}
38+
}
39+
}
40+
----
41+
+
42+
where:
43+
`<MCP_TOKEN>`:: Previously configured static token
44+
`<RHDH_TOKEN>`:: Hostname of your {product-very-short} instance
45+
46+
* Configure the *Continue* client.
47+
.. In your agent yaml configuration file, add the following configuration:
48+
+
49+
[source,yaml]
50+
----
51+
mcpServers:
52+
- name: backstage-actions
53+
type: sse
54+
url: https://<RHDH_HOST>/api/mcp-actions/v1/sse
55+
requestOptions:
56+
headers:
57+
Authorization: "Bearer <MCP_TOKEN>"
58+
----
59+
+
60+
where:
61+
`<MCP_TOKEN>`:: Previously configured static token
62+
`<RHDH_TOKEN>`:: Hostname of your {product-very-short} instance
63+
64+
* Configure the *Lightspeed Plugin/Lightspeed Core (LCS)* client.
65+
.. In the `lightspeed-stack.yaml` configuration, add the following configuration for `mcp_servers`:
66+
+
67+
[source,yaml]
68+
----
69+
mcp_servers:
70+
- name: mcp::backstage
71+
provider_id: model-context-protocol
72+
url: https://<RHDH_HOST>/api/mcp-actions/v1
73+
----
74+
+
75+
where:
76+
`model-context-protocol`:: Enter this definition in your llama-stack `run.yaml` configuration for use in LCS.
77+
.. Optional: 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:
78+
+
79+
[source,yaml]
80+
----
81+
lightspeed:
82+
mcpServers:
83+
- name: mcp::backstage
84+
token: ${MCP_TOKEN}
85+
----
86+
.. 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:
87+
+
88+
[source,yaml]
89+
----
90+
curl -X POST \
91+
-H 'Content-Type: application/json' \
92+
-H 'MCP-HEADERS: {"mcp::backstage": {"Authorization": "Bearer <MCP_TOKEN>"}}' \
93+
-d '{"query": "Can you give me all catalog templates of type 'service', "model": "gpt-4o-mini", "provider": "openai"}' \
94+
_<url>_/v1/streaming_query
95+
----
96+
+
97+
where:
98+
`<url>`:: Enter the LCS endooint. You can retrieve the LCS endpoint by using `curl` in the {backstage} container.

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

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="proc-configuring-model-context-protocol_{context}"]
4+
= Configuring Model Context Protocol in {product}
5+
6+
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.
7+
8+
.Procedure
9+
10+
. 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:
11+
+
12+
[source,yaml]
13+
----
14+
backend:
15+
auth:
16+
externalAccess:
17+
- type: static
18+
options:
19+
token: ${MCP_TOKEN}
20+
subject: mcp-clients
21+
----
22+
+
23+
where:
24+
`${MCP_TOKEN}`:: Set the token value that you generate.
25+
26+
. Register the MCP tools that you install as a plugin source, as shown in the following example:
27+
+
28+
[source,yaml]
29+
----
30+
backend:
31+
actions:
32+
pluginSources:
33+
- software-catalog-mcp-tool
34+
- techdocs-mcp-tool
35+
----
36+
37+
.`app-config.yaml` file with MCP configuration example
38+
[source,yaml]
39+
----
40+
app:
41+
title: AI Dev Developer Hub
42+
baseUrl: "${RHDH_BASE_URL}"
43+
auth:
44+
environment: development
45+
session:
46+
secret: "${BACKEND_SECRET}"
47+
providers:
48+
guest:
49+
dangerouslyAllowOutsideDevelopment: true
50+
backend:
51+
actions:
52+
pluginSources:
53+
- 'software-catalog-mcp-tool'
54+
- 'techdocs-mcp-tool'
55+
auth:
56+
externalAccess:
57+
- type: static
58+
options:
59+
token: ${ADMIN_TOKEN}
60+
subject: mcp-clients
61+
keys:
62+
- secret: "${BACKEND_SECRET}"
63+
baseUrl: "${RHDH_BASE_URL}"
64+
cors:
65+
origin: "${RHDH_BASE_URL}"
66+
signInPage: oidc
67+
----

0 commit comments

Comments
 (0)