Backstage MCP Server

How to use

You operate the MCP server from a local runtime and connect it to Backstage through a stdio channel. The server is designed to read commands from Goose or a similar runner and return results via stdout. Use the provided runtime configuration to start the server and then interact with it from your MCP client, such as a Backstage integration.

How to install

Prerequisites you need before installing this MCP server: a Backstage installation, and a Java-based runtime to execute the Quarkus app. You also need an environment that supports Service to Service communication and token-based authentication for external access.

1) Ensure Backstage is set up and has service-to-service communication enabled. 2) Prepare an environment token for internal communication. 3) Set up the GoOSe/Quarkus runtime according to your platform.

Define the external access token in your Backstage-like configuration. The token is placed along with the subject for curl requests under externalAccess. Here is the structure you would establish in your configuration:

app:
  # ...
backend:
  # ...
  auth:
    # ...
    externalAccess:
      - type: static
        options:
          token: <put your token here>
          subject: curl-requests

Additional sections

Dependencies used to implement the MCP server via Quarkus Backstage are shown as code blocks below. They illustrate the components required to read from stdin and write to stdout and to enable communication with the Backstage API.

<dependency>
    <groupId>io.quarkiverse.mcp</groupId>
    <artifactId>quarkus-mcp-server-stdio</artifactId>
    <version>1.0.0.Alpha5</version>
</dependency>

<dependency>
    <groupId>io.quarkiverse.backstage</groupId>
    <artifactId>quarkus-backstage</artifactId>
    <version>0.4.1</version>
</dependency>

The runtime implementation uses a tiny file to wire Backstage integration. It relies on a Backstage-aware MCP server component to translate Backstage operations into MCP actions.

Goose is used as a local AI agent that runs interactively and supports plugins, including MCP servers. To configure Goose to run this MCP server, add the following extension to your configuration file for Goose integration:

quarkus-backstage-mcp:
    args:
    - --quiet
    - /home/iocanel/demo/backstage-mcp/target/quarkus-app/quarkus-run.jar
    cmd: jbang
    enabled: true
    envs: {}
    name: quarkus-backstage-mcp
    type: stdio

Notes about templates and prompts

To list available backstage templates from Goose, you can prompt with a natural language request such as listing all available backstage templates.

To instantiate a template you first obtain a values.yaml file containing template parameters. You can extract default values for a template by querying the backstage CLI for the template info and default values. The typical flow is to fetch defaults, edit if needed, and then instantiate the template using those values within a Goose session.

quarkus backstage template info --show-default-values <template name>

listTemplates

List all available Backstage templates exposed by the MCP server, enabling you to see what templates you can instantiate.

instantiateTemplate

Create a new project from a selected Backstage template using the provided values.yaml for parameters.