Introducing the Backstage MCP Server

If your team uses Backstage, your software catalog already contains information an AI assistant needs: service names, owners, APIs, and relationships between components. Giving the assistant access to that information can save you from copying catalog entries into a conversation every time you ask about a service.

I built Backstage MCP Server to connect an MCP-compatible assistant to the Backstage Software Catalog. It exposes tools for looking up entities, inspecting relationships, validating descriptors, and making authorized catalog changes.

You configure the Backstage backend and credentials. Your MCP client launches the server and makes its tools available to the assistant.

What the Server Does

Model Context Protocol, or MCP, gives an assistant a structured way to discover tools and call them with defined arguments. In this project, those tools translate requests into Backstage Catalog operations.

The server runs as a separate process. It communicates with the MCP client through standard input and output, then connects to Backstage over HTTP using the official Catalog client. The README describes the request flow.

You ask about a service
  -> the assistant selects a Catalog tool
  -> the MCP server calls Backstage
  -> Backstage returns Catalog data
  -> the assistant uses that data in its answer

For example, you might ask:

Find the payments component in the default namespace, show its owner, and list the APIs it provides.

The assistant can retrieve the entity and follow the relevant Catalog relationships. You get an answer based on the configured catalog, with entity references you can check.

The quality of that answer still depends on the catalog. If an ownership record is outdated, connecting an assistant will make that outdated record easier to retrieve. It will not make the former owner any happier to receive the ticket.

Look Up Services, Owners, and Dependencies

The tool catalog includes general queries, individual and batch entity lookups, facets, ancestry, and source-location discovery. It also includes focused lookup tools for questions such as:

• Which entities belong to this System or Domain?
• What does this Group own?
• Which Users belong to this Group?
• Which APIs does this component provide or consume?
• Which entities declare a dependency on this component?
• Which entities have been marked as orphaned?

Here is an example of the arguments an MCP client can send to get_entities_by_owner:

{
  "ownerRef": "group:default/payments-team"
}

That reference identifies a Group named payments-team in the default namespace. Complete references help distinguish entities that share a name across namespaces or kinds.

These lookups use Catalog metadata and processed relations. A declared dependency is useful for investigating a change, but it does not prove you have found every runtime dependency. Likewise, a Catalog ownership relationship describes responsibility; it does not grant permission to change the entity.

Those distinctions matter when you move from asking questions to taking action.

Validate and Maintain Catalog Entries

The server also exposes operations for validating an entity descriptor, adding a location, requesting an entity refresh, and removing entities or locations. The integration guide explains how these map to Backstage’s API.

A useful maintenance workflow could be:

1. Retrieve the entity and find its source location.
2. Inspect a proposed descriptor change.
3. Validate the descriptor in its source-location context.
4. Make the approved source change through your repository workflow.
5. Request Catalog refresh processing.

The MCP server handles the Catalog operations in that sequence. Editing a file or opening a pull request requires the appropriate repository tools as well.

For location registration, add_location supports a dry run so you can check the proposed registration before writing it. Removal operations are identified as destructive in their tool annotations. Your Backstage credential and permission configuration determine which operations the server can perform.

For an initial setup, Catalog read access is enough to explore service discovery and ownership questions.

Connect It to Your Assistant

You need a reachable Backstage backend, a bearer token accepted by that deployment, Node.js 24.15 or newer, and Corepack. Build the server from source:

git clone https://github.com/Coderrob/backstage-mcp-server.git
cd backstage-mcp-server
corepack enable
corepack yarn install --immutable
corepack yarn build

Then configure your MCP client to launch the built CLI. For clients that use an mcpServers configuration, a token-file setup looks like this:

{
  "mcpServers": {
    "backstage": {
      "command": "node",
      "args": ["/absolute/path/to/backstage-mcp-server/dist/cli.cjs"],
      "env": {
        "BACKSTAGE_BASE_URL": "https://backstage.example.com",
        "BACKSTAGE_TOKEN_FILE": "/absolute/path/to/backstage-token"
      }
    }
  }
}

Replace the example paths and URL with your own. The token file must contain a bearer token accepted by your Backstage deployment. The server reads it before each outgoing request, allowing an external process to rotate it. You can also supply BACKSTAGE_TOKEN through your client’s environment or secret mechanism. See the setup instructions for both options.

Once connected, try a small request: ask the assistant to list a few Components in the default namespace. Check the returned references against Backstage before expanding the task.

The repository also provides corepack yarn test:live, a read-only check against your configured backend. It launches the built server through MCP and queries the Catalog, which helps distinguish a connection or credential problem from an assistant configuration problem.

Where MCP Kernel Fits

The current server uses MCP Kernel for tool registration, request policies, startup, shutdown, and transport support. The Backstage application supplies the Catalog tools and authenticated client.

That lets the Backstage code focus on what its tools should ask the Catalog to do. I cover that design and the integration tests in Improving the Backstage MCP Server with MCP Kernel.

Give Your Assistant the Catalog Context

I’ve written about custom Backstage entity relationships before. This project makes Catalog information available during an assistant conversation, where it can help answer questions about the software you are working on.

Start with the repository, connect it to your Backstage instance, and try a lookup you normally do by hand. If a useful Catalog operation is missing or a result is confusing, an issue with a concrete example helps improve the tool.

My goal is simple: let the assistant look up the service information your team already maintains, so you can spend more time using it and less time copying it between tools.

-Rob