MCP Backstage Catalog Server

This implementation provides a Model Context Protocol (MCP) server that wraps the Backstage Catalog API, allowing MCP clients to interact with Backstage entities.

Features

• Exposes Backstage catalog entities via MCP-compatible endpoints
• Transforms Backstage entity structure to MCP format
• Supports filtering by entity kind, namespace, and labels
• Provides individual entity lookup by reference
• Create new entities in the Backstage catalog

Setup

1. Install dependencies:

   pip install -r requirements.txt
   

2. Configure environment variables:

   export BACKSTAGE_API_URL=https://your-backstage-instance.com
   export BACKSTAGE_API_KEY=your-api-key  # If required
   export PORT=8080  # Optional, defaults to 8080
   

3. Run the server:

   python mcp_backstage_server.py
   

Usage

The server exposes the following endpoints:

• GET /entities - List all entities, with optional filtering

  • Query parameters:
    • kind: Filter by entity kind (e.g., Component, API, System)
    • namespace: Filter by namespace
    • label_selector: Filter by labels (e.g., "tier=backend,team=infra")

• GET /entities/{namespace}/{kind}/{name} - Get a specific entity by reference

• POST /entities - Create a new entity in the Backstage catalog

  • Request body: MCP-formatted entity
  • Returns: Created entity in MCP format

Entity Format

The MCP server expects entities in the following format when creating:

{
  "apiVersion": "mcp/v1",
  "kind": "Component",
  "metadata": {
    "name": "example-service",
    "namespace": "default",
    "labels": {
      "tier": "backend"
    },
    "annotations": {
      "backstage.io/managed-by": "mcp"
    }
  },
  "spec": {
    "type": "service",
    "lifecycle": "production",
    "owner": "team-a"
  }
}

Integration with MCP Clients

MCP clients can connect to this server using the standard MCP client libraries:

from mcp.client import MCPClient

# Read entities
client = MCPClient("http://localhost:8080")
entities = client.get_entities(kind="Component")

# Create entity
new_entity = {
  "apiVersion": "mcp/v1",
  "kind": "Component",
  "metadata": {
    "name": "new-service",
    "namespace": "default"
  },
  "spec": {
    "type": "service",
    "lifecycle": "development",
    "owner": "team-b"
  }
}
created_entity = client.create_entity(new_entity)

Customization

To extend this implementation or modify the entity transformation logic, you can subclass BackstageMCPServer and override the _transform_backstage_entity or _transform_to_backstage_format methods.