Procedure

1. Configure Developer Lightspeed for RHDH as a client. For more details, see {developer-lightspeed-link}[Red Hat Developer Lightspeed for Red Hat Developer Hub].

   1. In the lightspeed-stack.yaml configuration, add the following mcp_servers configuration:

      mcp_servers:
        - name: mcp::backstage
          provider_id: model-context-protocol
          url: https://<my_developer_hub_domain>/api/mcp-actions/v1
          authorization_headers:
            Authorization: "client"

      model-context-protocol

      Enter the tool runtime provider defined in the llama-stack run.yaml configuration for LCORE.

   2. Optional: To use a custom Llama Stack configuration, add the following code to the run.yaml Llama Stack configuration file.

      providers:
        tool_runtime:
        - provider_id: model-context-protocol
          provider_type: remote::model-context-protocol
          config: {}

   3. To authorize requests to the MCP endpoint using <MCP_TOKEN>, add one or more servers to the mcpServers list in the Developer Lightspeed for RHDH app-config.yaml file, to make POST requests to LCORE:

      lightspeed:
        mcpServers:
        - name: mcp::backstage
          token: ${MCP_TOKEN}
        - name: _<mcp_server_name>_
          token: ${MCP_TOKEN_2}

      where:

      name

      Enter the server name. This must match the name configured in the LCORE.

      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 for RHDH user interface. The setting remains disabled until you configure the token.

   4. Optional: Query the LCORE /v1/streaming_query endpoint directly by providing the MCP_TOKEN in the header:

      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 LCORE endpoint. Use localhost or the service name pass:c,a,q:[<RHDH_servicename>.my-rhdh-project.svc.cluster.local:8080] if you are inside the Backstage container.

2. Configure Cursor as a client.

   1. From your Desktop app, navigate to Cursor Settings, select MCP Tools > New MCP Server and add the following configuration:

      {
        "mcpServers": {
          "backstage-actions": {
            "url": "https://<my_developer_hub_domain>/api/mcp-actions/v1",
            "headers": {
              "Authorization": "Bearer <mcp_token>"
            }
          }
        }
      }

      where:

      <mcp_token>

      Enter the previously configured static token

      <my_developer_hub_domain>

      Enter the hostname of your RHDH instance

3. Configure Continue as a client.

   1. In your agent yaml configuration file, add the following configuration:

      mcpServers:
        - name: backstage-actions
          type: sse
          url: https://<my_developer_hub_domain>/api/mcp-actions/v1/sse
          requestOptions:
            headers:
              Authorization: "Bearer <mcp_token>"

      where:

      <mcp_token>

      Enter the previously configured static token

      <my_developer_hub_domain>

      Enter the hostname of your RHDH instance

Procedure

1. Obtain an authentication token:

   1. To obtain a user session token:

      1. Sign in to your RHDH instance at https://__<my_developer_hub_domain>__.

      2. Navigate to Settings > Profile and select Copy user token. This copies your OIDC session token to the clipboard.

         Note

         User session tokens are short-lived and expire when your RHDH session ends. Retrieve a new token by signing in again when it expires.

   2. To obtain a static service token:

      1. Ask your platform engineer for the value of the MCP_TOKEN environment variable configured in the RHDH deployment. This is the token set in backend.auth.externalAccess in the app-config.yaml file.

2. Configure your MCP client with the server endpoint and your authentication token:

   1. To configure Cursor:

      1. From the Cursor desktop app, navigate to Cursor Settings > MCP Tools > New MCP Server.

      2. Add the following configuration, replacing <your_token> with the token you obtained:

         {
           "mcpServers": {
             "backstage-actions": {
               "url": "https://<my_developer_hub_domain>/api/mcp-actions/v1",
               "headers": {
                 "Authorization": "Bearer <your_token>"
               }
             }
           }
         }

   2. To configure Visual Studio Code:

      1. Create or update the .vscode/mcp.json file in your workspace, replacing <your_token> with the token you obtained:

         {
           "servers": {
             "backstage-actions": {
               "type": "http",
               "url": "https://<my_developer_hub_domain>/api/mcp-actions/v1",
               "headers": {
                 "Authorization": "Bearer <your_token>"
               }
             }
           }
         }

   3. To configure Claude Code:

      1. Run the following command, replacing <your_token> with the token you obtained:

         $ claude mcp add backstage-actions \
           --transport http \
           --url https://<my_developer_hub_domain>/api/mcp-actions/v1 \
           --header "Authorization: Bearer <your_token>"

         Note

         If your client does not yet support the Streamable HTTP endpoint, use the Server-Sent Events (SSE Legacy) endpoint instead: https://__<my_developer_hub_domain>__/api/mcp-actions/v1/sse.

3. Optional: If your platform engineer has enabled Dynamic Client Registration (DCR), you do not need to copy or paste any token. Your MCP client obtains authentication automatically through a browser sign-in.

   For example, to configure Cursor to use DCR:

   1. From the Cursor desktop app, navigate to Cursor Settings > MCP Tools > New MCP Server.

   2. Add the following configuration:

      {
        "mcpServers": {
          "backstage-actions": {
            "url": "https://<my_developer_hub_domain>/api/mcp-actions/v1"
          }
        }
      }

      No headers or Authorization field is required. DCR handles the token exchange automatically.

   3. When you first call a tool, your browser opens for sign-in. After you authenticate, tools work with your personal RBAC permissions.

Verification

1. In your MCP client, view the list of available tools.
2. Confirm that your MCP client lists the RHDH tools (for example, fetch-catalog-entities, fetch-techdocs).
3. Request a tool that requires a specific permission. If your user role does not include that permission, the tool returns an Unauthorized error, confirming that RBAC enforcement is active.

Procedure

1. To enable encryption for MCP server tokens, add the following snippet to the backend section of your app-config.yaml file:

   backend:
     auth:
       keys:
       - secret: ${BACKEND_SECRET}

2. To store MCP server user preferences, configure the database connection. Use the configuration example that matches your environment:

   • Local development (In-memory):

     backend:
       database:
         client: better-sqlite3
         connection: ':memory:'

   • Local path storage:

     backend:
       database:
         client: better-sqlite3
         connection:
           directory: './sqlite-data'

   • Deployed PostgreSQL database:

     backend:
       database:
         client: pg
         connection:
           host: localhost
           port: 5432
           user: ${POSTGRES_USER}
           password: ${POSTGRES_PASSWORD}

Procedure

1. In the Red Hat Developer Lightspeed for Red Hat Developer Hub chat box, click the Chatbot options menu icon in the header.

2. Select MCP settings.

   

3. 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

1. Submit a query in the chat that requires an MCP tool, such as requesting catalog resources or server information.
2. If you enabled a server, verify that the response contains data from that specific MCP tool.
3. If you disabled a server, verify that Developer Lightspeed for RHDH uses standard documentation or general knowledge instead of the MCP tool to provide the response.

Procedure

1. Log in to the OCP cluster running RHDH and go to your RHDH project using the following code:

   $ oc project my-rhdh-project

2. Inspect the logs for the installation of the RHDH dynamic plugins using the following code:

   $ oc logs -c install-dynamic-plugins deployment/<my-product-deployment>

Verification

1. You must see an entry for the MCP backend server plugin as shown in the following code:

   ..... prior logs ....
   ======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:<tag>
   	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:<tag> to local filesystem
   	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:<tag>

   where:

   <tag>

   Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

2. Find your Backstage version in the RHDH release notes preface.

3. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.9 based on Backstage 1.45.3, use the format bs_1.45.3__<plugin-version>.

   Tip

   To ensure environment stability, use a SHA256 digest instead of a version tag. See Determining SHA256 Digests.

4. You must see entries for any of the MCP tool plugins you installed as shown in the following code:

   ..... prior logs ....
   ======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:<tag>
   	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:<tag> to local filesystem
   	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:<tag>

   where:

   <tag>

   Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

5. Find your Backstage version in the RHDH release notes preface.

6. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.9 based on Backstage 1.45.3, use the format bs_1.45.3__<plugin-version>.

   Tip

   To ensure environment stability, use a SHA256 digest instead of a version tag. See Determining SHA256 Digests.

Procedure

1. Consult your model documentation to confirm its support for tool calling.
2. If the current model does not support tool calling, change the model that your MCP client uses to a tool-calling compatible model.

Procedure

1. Check the token validation status in the Red Hat Developer Lightspeed for Red Hat Developer Hub interface:

   1. In the Red Hat Developer Lightspeed for Red Hat Developer Hub chat box, click the menu icon (Chatbot options) and select MCP settings.
   2. Locate the relevant server and check the status message displayed below the token field.
   3. 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.

2. Verify the authentication token configuration.

   1. Ensure a static token is configured for the RHDH MCP server.
   2. In your MCP client, verify that the token is set as the bearer token. The authorization header must use the Bearer <mcp_token> format.

3. Check the MCP endpoint configuration.

   1. Confirm that the MCP server URL properly resolves correctly, particularly when using desktop clients.
   2. Use legacy SSE endpoint if your MCP client requires it instead of the Streamable endpoint. (For more details, see the Configuration topic).

4. Verify the RHDH app-config.yaml file for formatting errors:

   1. Ensure there are no duplicate backend entries and that the YAML indentation is accurate.
   2. 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 Configure MCP in RHDH.

Procedure

1. Select an appropriate model for tool calling.

   1. Verify that the model has good support for tool calling.
   2. Make sure your model is not too small. We recommend a model with at least 7 billion parameters and a context window of 32k.

2. Refine your queries.

   1. Use more well-defined queries that limit the amount of data returned in the response from the tool.
3. If possible, increase the context window size of the model. We recommend at least 32k for these MCP tools.