Backstage MCP server
2026년 11월 13일 커밋Backstage Software Catalog API를 LLM용 도구로 노출하여 엔티티 검색, 카탈로그 작업 및 검증을 수행합니다.
다른 이름 Coderrob/backstage-mcp-server
- 스타
- 3
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- GPL-3.0
Backstage MCP란?
Backstage은(는) MCP server입니다. Backstage Software Catalog API를 LLM용 도구로 노출하여 엔티티 검색, 카탈로그 작업 및 검증을 수행합니다.
프로젝트 README에서 생성된 요약
Backstage MCP server 정보
이 서버는 LLM을 Backstage Software Catalog API에 연결하여 AI 에이전트를 통해 소프트웨어 카탈로그를 관리할 수 있게 합니다. stdio 연결을 통해 엔티티 검색, 위치 관리, 디스크립터 검증을 위한 32개의 특화된 도구를 제공합니다. 개발자는 이를 사용하여 엔티티의 계층 구조, 패싯(facet), 소스 위치를 쿼리하거나 위치 추가 및 엔티티 새로고침과 같은 변경 작업을 수행할 수 있습니다.
서버를 설정하려면 Node.js 24.15 이상 버전과 접근 가능한 Backstage 백엔드가 필요합니다. 인증은 BACKSTAGE_TOKEN 환경 변수를 통해 제공되는 bearer token이나, 자격 증명 로테이션을 위한 BACKSTAGE_TOKEN_FILE을 통해 처리됩니다. 이 서버는 프로덕션급 통합을 보장하기 위해 공식 Backstage CatalogClient를 사용합니다. 또한 주체별 속도 제한(rate limits), 타임아웃, 그리고 읽기 전용, 변경, remove_entity_by_uid와 같은 파괴적 도구를 구분하는 어노테이션 등 내장된 안전 기능을 포함하고 있습니다.
활용 사례
- 1소프트웨어 컴포넌트 검색AI에게 특정 네임스페이스 내의 모든 컴포넌트와 API를 찾아달라고 요청합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
BACKSTAGE_BASE_URLBACKSTAGE_TOKENBACKSTAGE_TOKEN_FILE
| 이름 | 설명 | 유형 |
|---|---|---|
| BACKSTAGE_BASE_URL | — | |
| BACKSTAGE_TOKEN | — | |
| BACKSTAGE_TOKEN_FILE | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능coderrob/backstage-mcp-server is public and reachablegithub.com/coderrob/backstage-mcp-server ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-12github.com/coderrob/backstage-mcp-server ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Backstage MCP Server
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.
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 |
| Verification | Per-file coverage, SDK stdio smoke tests, every-tool execution, and MCP Inspector |
Quick start
1. Install and build
Requirements:
- Node.js 24.15 or newer
- Corepack
- A reachable Backstage backend and an accepted external-access bearer token
corepack enable
corepack yarn install --immutable
corepack yarn build
The Yarn release comes from the packageManager field in package.json; use corepack yarn so local and CI behavior stay aligned.
2. Configure Backstage
Set the backend root or the complete Catalog plugin URL and choose one credential source:
export BACKSTAGE_BASE_URL=https://backstage.example.com
export BACKSTAGE_TOKEN=your-token
For externally rotated credentials, point to a token file instead:
export BACKSTAGE_BASE_URL=https://backstage.example.com
export BACKSTAGE_TOKEN_FILE=/run/secrets/backstage-token
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:
{
"mcpServers": {
"backstage": {
"command": "node",
"args": ["/absolute/path/to/backstage-mcp-server/dist/cli.cjs"],
"env": {
"BACKSTAGE_BASE_URL": "https://backstage.example.com",
"BACKSTAGE_TOKEN": "your-token"
}
}
}
}
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.
| Category | Tools |
|---|---|
| Entity discovery | get_entities, get_entities_by_query, get_entities_by_refs, get_entity_by_ref, get_entity_ancestors, get_entity_facets |
| Location discovery | get_location_by_entity, get_location_by_ref |
| Validation | validate_entity |
| Catalog mutation | add_location, refresh_entity |
| Destructive mutation | remove_entity_by_uid, remove_location_by_id |
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.
{
"filter": {
"kind": ["Component", "API"],
"metadata.namespace": "default"
}
}
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
CatalogClientand 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.
To contribute a Catalog capability, follow Adding a Backstage MCP tool.
Verification

Run the normal contributor gate:
corepack yarn lint
corepack yarn typecheck
corepack yarn architecture:check
corepack yarn knip
corepack yarn test
corepack yarn test:shell
For MCP, tool, adapter, or packaging changes, also run:
corepack yarn test:mcp
corepack yarn manifest:check
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.
See Repository tooling for the purpose and side effects of every command and MCP end-to-end testing for the exact black-box boundary.
Documentation
Choose a path from the documentation hub:
- Operate it: Backstage integration and end-to-end testing
- Develop it: Repository tooling, code quality, and adding tools
- Understand it: Architecture overview, ADRs, historical analysis, and implementation plan
- Maintain it: Dependency management
License
GPL-3.0. See LICENSE.
Curated knowledge and skills
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.
Backstage MCP 질문
Backstage 서버 인증은 어떻게 구성하나요?
BACKSTAGE_TOKEN 환경 변수를 통해 bearer token을 제공하거나, BACKSTAGE_TOKEN_FILE을 사용하여 토큰 파일을 지정할 수 있습니다.
AI가 어떤 종류의 카탈로그 작업을 수행할 수 있나요?
이 서버는 엔티티 검색, 위치 검색, 엔티티 검증을 위한 도구와 엔티티 및 위치 추가, 새로고침, 삭제와 같은 카탈로그 변경(mutation) 도구를 제공합니다.
실제 Backstage 배포 환경에서 이 서버를 사용할 수 있나요?
네, test:live 명령어를 사용하여 실제 배포 환경에 대해 읽기 전용 체크를 수행할 수 있습니다.
설치를 위한 시스템 요구 사항은 무엇인가요?
Node.js 24.15 이상 버전과 Corepack이 설치되어 있어야 합니다.