backstage-mcp
oopsmyops/backstage-mcp
Standalone MCP server for Backstage - catalog, scaffolder, and TechDocs tools for LLM clients
Instalação
npx convez-ai oopsmyops/backstage-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
backstage-mcp
Bring your Backstage developer portal to AI — two ways:
- 🤖 Backstage Assistant plugins — an in-portal AI chat widget (frontend + backend Backstage plugins) with multi-provider LLM support, a UI model picker, and the full catalog / scaffolder / TechDocs toolset.
- 🔌 Standalone MCP server — a single ~550 KB file exposing the same Backstage tools to external MCP clients (Claude, Cursor, VS Code, Windsurf) with no changes to your Backstage instance.
🤖 Backstage Assistant plugins
An AI assistant embedded directly in your Backstage UI.
| Package | Role | |
|---|---|---|
@oopsmyops/backstage-plugin-assistant | Frontend | Floating chat widget + model picker |
@oopsmyops/backstage-plugin-assistant-backend | Backend | LLM orchestration + Backstage tools |

Highlights
- Native Amazon Bedrock and Azure AI Foundry, plus any OpenAI-compatible API (no proxy), with an ordered fallback chain — all via the Vercel AI SDK.
- Pick the model from the UI; the choice is remembered per browser.
- Streaming responses, structured result cards, internal entity links, and guided scaffolder runs with an OAuth popup for VCS tokens.
Install the plugins
Published to npmjs.org as public packages — no token or registry config needed to install.
yarn --cwd packages/app add @oopsmyops/backstage-plugin-assistant
yarn --cwd packages/backend add @oopsmyops/backstage-plugin-assistant-backend
// packages/backend/src/index.ts
backend.add(import('@oopsmyops/backstage-plugin-assistant-backend'));
// packages/app/src/App.tsx — new frontend system
import assistantPlugin from '@oopsmyops/backstage-plugin-assistant';
// add `assistantPlugin` to createApp({ features: [...] })
Configure models
assistant:
llm:
fallback: [groq-llama] # tried, in order, if the selected model fails
models:
- id: claude-bedrock
label: Claude Sonnet (Bedrock)
provider: bedrock
model: anthropic.claude-sonnet-4-6
region: us-east-1
apiKey: ${AWS_BEARER_TOKEN_BEDROCK} # optional; omit to use the AWS credential chain
default: true
- id: gpt-azure
label: GPT-5.1 (Azure AI Foundry)
provider: azure
model: gpt-5.1 # Azure deployment name
resourceName: my-foundry-resource
apiKey: ${AZURE_OPENAI_API_KEY}
- id: groq-llama
label: Llama 3.3 70B (Groq)
provider: openai-compatible
model: llama-3.3-70b-versatile
baseUrl: https://api.groq.com/openai/v1
apiKey: ${GROQ_API_KEY}
📖 Full documentation: frontend plugin README · backend plugin README
🔌 Standalone MCP server
A single-file MCP server exposing 11 Backstage tools (catalog search, entity details, API specs, scaffolder templates + tasks, TechDocs) to any MCP client. No Backstage install required — it connects through Backstage's REST APIs.
# Download the latest binary and run it
curl -LO https://github.com/oopsmyops/backstage-mcp/releases/latest/download/backstage-mcp.mjs
BACKSTAGE_BASE_URL=https://your-backstage.example.com \
BACKSTAGE_TOKEN=your-token \
node backstage-mcp.mjs
Build from source instead: npm install && npm run build → dist/backstage-mcp.mjs.
Need a token? Use a static service-account token (recommended) or a guest token.
Connect an MCP client (Claude Desktop, Cursor, VS Code, Windsurf):
{
"mcpServers": {
"backstage-mcp": {
"command": "node",
"args": ["/absolute/path/to/backstage-mcp.mjs"],
"env": {
"BACKSTAGE_BASE_URL": "https://your-backstage.example.com",
"BACKSTAGE_TOKEN": "your-token"
}
}
}
}
For remote/shared use, run with MCP_TRANSPORT=http and point clients at
http://localhost:3000/mcp (health: /health).
Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
BACKSTAGE_BASE_URL | yes | — | Base URL of your Backstage instance |
BACKSTAGE_TOKEN | yes | — | Bearer token for authentication |
MCP_TRANSPORT | no | stdio | stdio or http |
PORT | no | 3000 | HTTP port (when MCP_TRANSPORT=http) |
HOST | no | 127.0.0.1 | HTTP host (when MCP_TRANSPORT=http) |
CACHE_TTL_SECONDS | no | 60 | Entity cache TTL in seconds (0 = disabled) |
REQUEST_TIMEOUT_MS | no | 10000 | Backstage API request timeout |
Contributing
See CONTRIBUTING.md.