What is Mcp Backstage

mcp-backstage is a Model Context Protocol (MCP) server designed to facilitate interaction with Backstage catalog APIs, allowing AI assistants like Claude to query and retrieve information about entities in a Backstage instance.

Use cases

Use cases for mcp-backstage include querying entity details for development purposes, integrating AI assistants for enhanced interaction with Backstage, and enabling real-time updates for monitoring software components.

How to use

To use mcp-backstage, you can install it via Docker or build it from source. After installation, configure your Claude Desktop by adding the necessary server details and authentication tokens in the configuration file.

Key features

Key features of mcp-backstage include entity retrieval by kind, namespace, and name, search functionality across all entities, secure communication with bearer token authentication, and real-time updates through Server-Sent Events (SSE).

Where to use

mcp-backstage can be used in software development environments, particularly in organizations utilizing Backstage for managing their software components and services.

MCP Backstage Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to query and retrieve information from your Backstage catalog.

Features

• Entity Retrieval: Get detailed information about specific entities by kind, namespace, and name
• Search: Search across all entities in the Backstage catalog
• Authentication: Support for bearer token authentication
• SSE Communication: Real-time Server-Sent Events for MCP protocol

Quick Start

1. Install

# Pull from GitHub Container Registry
docker pull ghcr.io/merlindorin/mcp-backstage:latest

# Or build from source
git clone https://github.com/merlindorin/mcp-backstage
cd mcp-backstage
./build.sh

# Or build Docker image locally
docker build -t mcp-backstage .

2. Configure Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "backstage": {
      "command": "/path/to/mcp-backstage",
      "args": [
        "serve",
        "--backstage-url",
        "https://your-backstage.com"
      ],
      "env": {
        "BACKSTAGE_TOKEN": "your-api-token"
      }
    }
  }
}

3. Restart Claude Desktop

4. Use in Claude

"Show me all frontend components"
"Get details about the user-service component"
"Search for APIs related to authentication"

Prerequisites

• Go 1.21+ or Docker
• Access to a Backstage instance with catalog API enabled
• (Optional) Backstage API token for authentication

Running the Server

# Using binary
./mcp-backstage serve --backstage-url="https://your-backstage.com"

# Using Docker (from GHCR)
docker run --rm -it ghcr.io/merlindorin/mcp-backstage:latest serve --backstage-url="https://your-backstage.com"

# Using Docker (local build)
docker run --rm -it mcp-backstage serve --backstage-url="https://your-backstage.com"

# With authentication
export BACKSTAGE_TOKEN="your-api-token"
./mcp-backstage serve --backstage-url="https://your-backstage.com"

Configuration Options

Available Tools

backstage_get_entity

Get detailed information about a specific Backstage entity.

• kind (required): Entity kind (Component, System, API, Resource, User, Group)
• namespace (optional): Entity namespace (defaults to “default”)
• name (required): Entity name

backstage_search

Search across all entities in the Backstage catalog.

• term (required): Search term

Advanced Configuration

Multiple Backstage Instances

{
  "mcpServers": {
    "backstage-prod": {
      "command": "/path/to/mcp-backstage",
      "args": [
        "serve",
        "--backstage-url",
        "https://prod.backstage.com"
      ],
      "env": {
        "BACKSTAGE_TOKEN": "prod-token"
      }
    },
    "backstage-dev": {
      "command": "/path/to/mcp-backstage",
      "args": [
        "serve",
        "--backstage-url",
        "https://dev.backstage.com"
      ],
      "env": {
        "BACKSTAGE_TOKEN": "dev-token"
      }
    }
  }
}

Docker Deployment

The Docker image is available on GitHub Container Registry: https://github.com/merlindorin/mcp-backstage/pkgs/container/mcp-backstage

# Pull from GHCR
docker pull ghcr.io/merlindorin/mcp-backstage:latest

# Run container
docker run -d \
  -e BACKSTAGE_URL=https://your-backstage.com \
  -e BACKSTAGE_TOKEN=your-token \
  -p 8080:8080 \
  ghcr.io/merlindorin/mcp-backstage:latest serve

# Build image locally
docker build -t mcp-backstage .

# Multi-arch build
docker buildx build --platform linux/amd64,linux/arm64 -t mcp-backstage .

Development

Testing

./mcp-backstage test --backstage-url="https://your-backstage.com" --token="your-token"

Project Structure

mcp-backstage/
├── api/v1/           # API client and types
├── cmd/              # CLI application
├── internal/         # Internal packages
│   ├── client/       # Backstage HTTP client
│   ├── logger/       # Logging utilities
│   └── mcptools/     # MCP tool implementations
├── build.sh          # Build script
├── Dockerfile        # Container image definition
└── go.mod            # Go module definition

Troubleshooting

Claude doesn’t see the tools

• Check configuration file location and JSON syntax
• Restart Claude Desktop
• Verify binary path is correct

Connection issues

• Verify Backstage URL is accessible
• Check authentication token
• View MCP logs in Claude Desktop (Settings → Developer)

License

MIT