A type-safe Model Context Protocol server for the Backstage Software Catalog, built on the published @coderrob/mcp-kernel runtime.
It exposes 32 Catalog tools over stdio, uses Backstage's official Catalog client, supports rotating bearer credentials, and ships with black-box SDK and MCP Inspector verification.
A production-ready, enterprise-grade Model Context Protocol (MCP) server that exposes the Backstage Catalog API as tools for Large Language Models (LLMs). Features comprehensive operational transparency, cross-platform compatibility, and automated error recovery.
Stars
3
Tools
—
Uptime
—
What you get
Capability
Implementation
Catalog discovery
Entity queries, references, ancestry, facets, and source locations
Catalog operations
Add locations, refresh entities, remove entities or locations, and validate descriptors
Type safety
Zod schemas infer handler inputs and emit MCP-compatible JSON Schemas
Runtime policies
Timeouts, caller scopes, per-principal rate limits, tagged caching, and invalidation
Safe operations
MCP annotations distinguish read-only, mutating, idempotent, and destructive tools
Production boundary
Official Backstage CatalogClient, authenticated fetch, redacted stderr logging
BACKSTAGE_TOKEN_FILE takes precedence when both variables are present and is reread for every outgoing request. Optional LOG_LEVEL=debug enables diagnostic logging. Logs always go to stderr because stdout carries MCP protocol traffic.
3. Start the stdio server
corepack yarn start
The process waits for an MCP client on stdin/stdout. For a read-only check against a real deployment, use corepack yarn test:live; see live Backstage verification.
Connect an MCP client
After building, configure a stdio client with an absolute path:
After global installation, use backstage-mcp-server as the command. Do not place credentials in committed client configuration; use the client's secret or environment mechanism where available.
Tool catalog
The checked-in tools-manifest.json is generated from the runtime definitions and is the machine-readable source of truth.
get_entities.filter follows Backstage's key-value model: keys in one record are AND conditions, values for one key are OR conditions, and multiple records are OR groups.
This selects Components or APIs in the default namespace. The Backstage integration guide documents every tool-to-client mapping, cursor behavior, authentication, permissions, and error conversion.
How it works
An MCP client launches the packaged CLI and exchanges JSON-RPC over stdio.
The published MCP Kernel validates and compiles immutable feature definitions.
Zod validates input before middleware, authorization, caching, rate limiting, and timeout policies run.
A Backstage tool calls the typed Catalog contract from its application context.
The adapter delegates HTTP behavior to the official Backstage CatalogClient and injects the bearer token at the fetch boundary.
Results return as MCP text plus structured content; expected failures use stable error codes and safe details.
The published @coderrob/mcp-kernel package owns protocol registration, lifecycle, policies, transports, testing support, and protocol-safe logging. This repository owns only the Backstage application and Catalog integration. See the current architecture overview for the dependency boundary.
MCP Kernel dependency
Generic server authoring, lifecycle, policies, transports, results, testing support, and logging are documented in the @coderrob/mcp-kernel repository. This package re-exports the kernel API for compatibility, but new generic consumers should install and import @coderrob/mcp-kernel directly.
test:mcp runs contract tests, builds the distribution, launches dist/cli.cjs over stdio with the official SDK client, invokes every registered tool against a deterministic authenticated Catalog stub, and performs an independent MCP Inspector check. It does not bypass the server with direct handler or HTTP calls.
The Backstage knowledge base maintains classified articles, named source citations and schema.org metadata. Repository skills in .agents/skills support catalog lookups, entity maintenance and MCP development.
The 19 contextual lookup tools cover names, System and Domain contents, Groups, ownership, dependencies, APIs, annotations and orphaned entities. See lookup contracts and examples, including pagination, ambiguity and work bounds.
B
Backstage
Coderrob·3 stars·
A production-ready, enterprise-grade Model Context Protocol (MCP) server that exposes the Backstage Catalog API as tools for Large Language Models (LLMs). Features comprehensive operational transparen
A production-ready, enterprise-grade Model Context Protocol (MCP) server that exposes the Backstage Catalog API as tools for Large Language Models (LLMs). Features comprehensive operational transparency, cross-platform compatibility, and automated error recovery.
Tools
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Questions
How do I install Backstage?
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
What transport does Backstage use?
Backstage runs locally over stdio.
When was Backstage last checked?
Last checked 2026-10-28. A production-ready, enterprise-grade Model Context Protocol (MCP) server that exposes the Backstage Catalog API as tools for Large Language Models (LLMs). Features comprehensive operational transparency, cross-platform compatibility, and automated error recovery.