RHIDP-12603: Doc for MCP Service Selector in chat and token storage (#2031)

* Doc for MCP Service Selector in chat and token storage

* Incorporated Maysun's comments

* Incorporated Maysun's comment and rewrote a bit

* Incorporated Maysun's comments

* Incorporated Tim - peer review comments

* Incorproated Fabrice's comments

* Made CQA changeS

* A few more cqa related updates

Author: pabel-rh

assemblies/integrate_interacting-with-model-context-protocol-tools-for-rhdh/assembly-configure-and-manage-mcp-settings.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="configure-and-manage-mcp-settings_{context}"]
+= Configure and manage MCP settings
+:context: configure-and-manage-mcp-settings
+
+[role="_abstract"]
+To use Model Context Protocol (MCP) servers securely, you must configure the backend storage and encryption. After configuration, users can manage connections and tokens by using the chat interface.
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-enable-encryption-and-database-storage-for-mcp-server-tokens.adoc[leveloffset=+1]
+
+include::../modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-manage-mcp-settings-in-the-user-interface.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

@@ -1,13 +1,10 @@
 :_mod-docs-content-type: ASSEMBLY
 ifdef::context[:parent-context: {context}]
 
-
-
 [id="troubleshoot-mcp-server-and-client-problems_{context}"]
 = Troubleshoot MCP server and client problems
-
-
 :context: troubleshoot-mcp-server-and-client-problems
+
 [role="_abstract"]
 Diagnose and resolve common issues with MCP server installation, client configuration, and tool execution in {product-short}.
 

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

@@ -4,29 +4,28 @@
 = Configure MCP clients to access the {product-very-short} server
 
 [role="_abstract"]
-Configure MCP client applications with server URLs and authentication to enable interaction with the {product-very-short} MCP server.
+Configure Model Context Protocol (MCP) client applications with server URLs and authentication to enable interaction with 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 the configuration for each client, see https://modelcontextprotocol.io/clients[Example Clients].
+You must configure an MCP client before it can interact with the MCP server. For a list of supported clients and their specific configurations, see link:https://modelcontextprotocol.io/clients[Example Clients].
 
 .Prerequisites
 
-* You have configured one of the following endpoints as the server URL, where `pass:c,a,q[{my-product-domain}]` is the hostname of your {product-very-short} instance.
+* You have one of the following endpoints for the server URL, where `pass:c,a,q[{my-product-domain}]` is the hostname of your {product-very-short} instance.
 
-** Streamable: pass:c,a,q[`{my-product-url}/api/mcp-actions/v1`]
-** SSE (Legacy): pass:c,a,q[`{my-product-url}/api/mcp-actions/v1/sse`]
+** Streamable: `pass:c,a,q[{my-product-url}/api/mcp-actions/v1]`
+** SSE (Legacy): `pass:c,a,q[`{my-product-url}/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.
+If a client does not yet support the Streamable endpoint, you must use the SSE endpoint.
 ====
 
-* You have set the `${MCP_TOKEN}` environment variable in your MCP server configuration as the bearer token when authenticating with the MCP server.
+* You have set the `MCP_TOKEN` environment variable in your MCP server configuration as the bearer token for authentication.
 
 .Procedure
 
 . Configure *{ls-short}* as a client. For more details, see {developer-lightspeed-link}[{ls-brand-name}].
-.. In the `lightspeed-stack.yaml` configuration, add the following configuration for `mcp_servers`:
+.. In the `lightspeed-stack.yaml` configuration, add the following `mcp_servers` configuration:
 +
 [source,yaml,subs="+attributes,+quotes"]
 ----
@@ -37,11 +36,11 @@ mcp_servers:
     authorization_headers:
       Authorization: "client"
 ----
-where:
++
 
-`model-context-protocol`:: This is the tool runtime provider defined and configured in the llama-stack `run.yaml` configuration for use in {lcs-short}.
+`model-context-protocol`:: Enter the tool runtime provider defined in the llama-stack `run.yaml` configuration for {lcs-short}.
 
-.. Optional: If you want to use your own Llama Stack configuration, add the following code to your Llama Stack configuration file (`run.yaml`).
+.. Optional: To use a custom Llama Stack configuration, add the following code to the `run.yaml` Llama Stack configuration file.
 +
 [source,yaml]
 ----
@@ -51,16 +50,24 @@ providers:
     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 {lcs-short}, as shown in the following code:
+
+.. To authorize requests to the MCP endpoint using `_<MCP_TOKEN>_`, add one or more servers to the `mcpServers` list in the {ls-short} `{my-app-config-file}` file, to make POST requests to {lcs-short}:
 +
 [source,yaml]
 ----
 lightspeed:
   mcpServers:
   - name: mcp::backstage
     token: ${MCP_TOKEN}
+  - name: _<mcp_server_name>_
+    token: ${MCP_TOKEN_2}
 ----
-.. Optional: You can query the {lcs-short} `/v1/streaming_query` endpoint directly by providing the `MCP_TOKEN` in the header, as shown in the following code:
+where:
+
+`name`:: Enter the server name. This must match the name configured in the {lcs-short}.
+`token`:: Optional: Enter the static token used to authorize requests. You can also configure the token through the *MCP Server Settings* in the *Developer Lightspeed* user interface. The setting remains disabled until you configure the token.
+
+.. Optional: Query the {lcs-short} `/v1/streaming_query` endpoint directly by providing the `MCP_TOKEN` in the header:
 +
 [source,yaml]
 ----
@@ -73,10 +80,10 @@ curl -X POST \
 +
 where:
 
-`<url>`:: Enter the {lcs-short} endpoint. You can use localhost(pass:c,a,q:[`<{product-very-short}_servicename>.{my-product-namespace}.svc.cluster.local:8080`]) or the service name for this field if you are inside the {backstage} container.
+`<url>`:: Enter the {lcs-short} endpoint. Use `localhost` or the service name `pass:c,a,q:[<{product-very-short}_servicename>.{my-product-namespace}.svc.cluster.local:8080]` if you are inside the {backstage} container.
 
 . Configure *Cursor* as a client.
-.. From your Desktop app, navigate to *Cursor Settings*, select *MCP Tools > New MCP Server* and add the following configuraiton:
+.. From your Desktop app, navigate to *Cursor Settings*, select *MCP Tools* > *New MCP Server* and add the following configuration:
 +
 [source,yaml,subs="+attributes,+quotes"]
 ----

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-enable-encryption-and-database-storage-for-mcp-server-tokens.adoc

@@ -0,0 +1,67 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enable-encryption-and-database-storage-for-mcp-server-tokens_{context}"]
+= Enable encryption and database storage for MCP server tokens
+
+[role="_abstract"]
+To protect sensitive credentials and persist user preferences, you must configure encryption and database settings in the `{my-app-config-file}` file. 
+
+Configuring encryption prevents the system from storing Model Context Protocol (MCP) tokens as plaintext in the database.
+
+.Prerequisites
+
+* You have administrator access to the {product-very-short} environment.
+* Your backend secet is available in the `BACKEND_SECRET` environment variable.
+
+.Procedure
+
+. To enable encryption for MCP server tokens, add the following snippet to the `backend` section of your `{my-app-config-file}` file:
++
+[source,yaml]
+----
+backend:
+  auth:
+    keys:
+    - secret: ${BACKEND_SECRET}
+----
+
+. To store MCP server user preferences, configure the database connection. Use the configuration example that matches your environment:
+
+** *Local development (In-memory):*
++
+[source,yaml]
+----
+backend:
+  database:
+    client: better-sqlite3
+    connection: ':memory:'
+----
+
+** *Local path storage:*
++
+[source,yaml]
+----
+backend:
+  database:
+    client: better-sqlite3
+    connection:
+      directory: './sqlite-data'
+----
+
+** *Deployed PostgreSQL database:*
++
+[source,yaml]
+----
+backend:
+  database:  
+    client: pg
+    connection:
+      host: localhost
+      port: 5432
+      user: ${POSTGRES_USER}
+      password: ${POSTGRES_PASSWORD}
+----
+
+.Verification
+
+* Restart the {product-very-short} instance and ensure no errors appear in the logs related to the `backend-auth` or `database` plugins.

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-manage-mcp-settings-in-the-user-interface.adoc

@@ -0,0 +1,37 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="manage-mcp-settings-in-the-user-interface_{context}"]
+= Manage MCP settings in the user interface
+
+[role="_abstract"]
+To customize the tools and data sources available in the {ls-brand-name} chat interface, you can manage Model Context Protocol (MCP) server connections and personal authentication tokens.
+
+You can use the *MCP settings* panel in the {ls-short} chat interface to review server status and enable or disable specific tools for your session.
+
+.Prerequisites
+
+* An administrator has configured encryption and database storage for the backend.
+* You have a valid Personal Access Token for the MCP servers you want to enable.
+
+.Procedure
+
+. In the {ls-brand-name} chat box, click the *Chatbot options* menu icon in the header.
+. Select *MCP settings*.
+. In the *MCP settings* panel, perform any of the following actions to configure your session:
+** Review server status: View whether available MCP servers are enabled or disabled.
+** View available tools: View the count of specific tools available for each server under *Status*.
+** Configure personal tokens: 
+*** To add or update a token, click the *Edit* icon, enter your Personal Access Token in the field, and click *Save*. The system validates the token automatically.
+*** To remove or replace a token, click the *Edit* icon and select *Forget Token*.
+** Enable or disable servers: Use the toggles to select which servers provide tools for your chat session.
++
+[NOTE]
+====
+You must configure a token before you can enable a server that requires authentication.
+====
+
+.Verification
+
+. Submit a query in the chat that requires an MCP tool, such as requesting catalog resources or server information.
+. If you enabled a server, verify that the response contains data from that specific MCP tool.
+. If you disabled a server, verify that {ls-short} uses standard documentation or general knowledge instead of the MCP tool to provide the response.

modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-resolve-authentication-issues-when-tools-are-not-found.adoc

@@ -4,18 +4,25 @@
 = Resolve authentication issues when tools are not found
 
 [role="_abstract"]
-Verify authentication tokens and configuration when MCP clients connect but cannot find deployed tools.
+Verify authentication tokens and configuration settings when Model Context Protocol (MCP) clients connect to the server but do not display deployed tools.
 
-If your MCP client connects to the server but cannot find deployed tools, an authentication or configuration issue is likely.
+If an MCP client connects to the server but cannot find deployed tools, verify the authentication status and endpoint resolution.
 
 .Procedure
 
-. Verify the authentication token.
-.. Configure a static token for the {product-very-short} MCP server.
-.. Set this token as the bearer token in your MCP client and make sure the authorization header is the configuration that specifies `Bearer` before the token, for example, `Bearer <mcp_token>`.
+. Check the token validation status in the {ls-brand-name} interface:
+.. In the {ls-brand-name} chat box, click the menu icon (*Chatbot options*) and select *MCP settings*.
+.. Locate the relevant server and check the status message displayed below the token field.
+.. If the status is *Authorization failed. Try again*, the token is incorrect, improperly formatted, or missing. You must verify the token value and ensure the server is enabled.
+
+. Verify the authentication token configuration.
+.. Ensure a static token is configured for the {product-very-short} MCP server.
+.. In your MCP client, verify that the token is set as the bearer token. The authorization header must use the `Bearer _<mcp_token>_` format.
+
 . Check the MCP endpoint configuration.
-.. Confirm that the MCP server URL properly resolves, particularly if you are using a desktop client.
-.. Use *legacy SSE endpoint* if your MCP client requires it instead of the Streamable endpoint. (For more details, see the *Configuration* topic).
-. Verify your {product-very-short} `{my-app-config-file}` file for duplicate backend entries and make sure that the indentation is accurate.
-.. Make sure that the configuration for the static token and MCP plugin sources go under an existing backend field, if one is present.
-.. If you are unsure, see {model-context-protocol-book-link}#configure-model-context-protocol-in-red-hat-developer-hub[the sample app configuration provided in the reference procedure].
+.. Confirm that the MCP server URL properly resolves correctly, particularly when using desktop clients.
+.. Use *legacy SSE endpoint* if your MCP client requires it instead of the *Streamable* endpoint. (For more details, see the *Configuration* topic).
+
+. Verify the {product-very-short} `{my-app-config-file}` file for formatting errors:
+.. Ensure there are no duplicate `backend` entries and that the YAML indentation is accurate.
+.. Confirm that the configuration for the static token and MCP plugin sources is nested under an existing `backend` field, if one is present. For a reference configuration, see {model-context-protocol-book-link}#configure-model-context-protocol-in-red-hat-developer-hub[Configure MCP in {product-very-short}].

modules/shared/proc-manage-chats.adoc

@@ -4,7 +4,7 @@
 = Manage chats
 
 [role="_abstract"]
-Manage your chat history in {product-very-short} to organize your workspace, resume earlier tasks, or find past solutions.
+Manage your chat history and configuration in {product-very-short} to organize your workspace, resume earlier tasks, or find past solutions.
 
 image::shared/chat-options.png["Chat options menu"]
 
@@ -16,9 +16,9 @@ image::shared/chat-options.png["Chat options menu"]
 
 . Click the *Lightspeed* floating action button (FAB) at the lower right of the screen to open the chat overlay.
 
-. Optional: Configure the interface display:
+. Optional: Configure the interface display and server settings:
 * Click the *Chatbot options* icon (⋮) to view chat history or start a new chat.
-* Click the *Display menu* icon and select any of the following views:
+* Click the *Display mode* icon and select any of the following views:
 +
 image::shared/settings.png["Display menu options"]
 
@@ -35,6 +35,8 @@ image::shared/lightspeed-docked-mode.png["Lightspeed docked mode"]
 image::shared/lightspeed-fullscreen.png["Lightspeed full-screen mode"]
 
 ** Optional: Toggle *Enable pinned chats*/*Disable pinned chats* to enable or hide the pinned chats. The system enables this option by default.
+// To add the link to the new module. Will add it once the anchor is generated.
+** Available only if MCP is configured: *MCP settings*: Manage Model Context Protocol connections.
 
 . Start a chat or load an earlier session:
 

titles/integrate_interacting-with-model-context-protocol-tools-for-rhdh/master.adoc

@@ -22,6 +22,8 @@ include::modules/integrate_interacting-with-model-context-protocol-tools-for-rhd
 
 include::modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-configure-mcp-clients-to-access-the-rhdh-server.adoc[leveloffset=+2]
 
+include::assemblies/integrate_interacting-with-model-context-protocol-tools-for-rhdh/assembly-configure-and-manage-mcp-settings.adoc[leveloffset=+1]
+
 include::modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-accessing-rhdh-data-using-the-software-catalog-mcp-tools.adoc[leveloffset=+1]
 
 include::modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/ref-fetching-entities-using-fetch-catalog-entities.adoc[leveloffset=+2]