backstage

n8n community node to query Backstage software catalog and TechDocs via MCP (Model Context Protocol)

Package Information

Released: 3 mo ago
Downloads: 30 weekly / 324 monthly
Latest Version: 0.1.0
Author: Javier Solana

Available Nodes

Backstage icon
Backstage
Query Backstage software catalog and TechDocs via MCP
Backstage AI Tool icon
Backstage AI Tool
Query Backstage catalog and TechDocs as an AI Agent tool via MCP

Documentation

n8n-nodes-backstage

Query your Backstage software catalog, TechDocs, and service dependency graphs directly from n8n workflows and AI Agents — powered by the backctl MCP server.

Installation

Install this community node in your n8n instance:

npm install n8n-nodes-backstage

Or via the n8n UI: Settings → Community Nodes → Install → n8n-nodes-backstage

Prerequisites

A running backctl MCP server accessible via HTTP (Streamable HTTP transport). The server exposes Backstage catalog data through the Model Context Protocol.

Credentials

Configure the Backstage MCP API credential with:

Field Description
MCP Server URL Full URL of the backctl MCP endpoint (e.g. http://backctl-mcp:8080/mcp)
Bearer Token Optional. Required when the MCP server is behind an auth gateway (OIDC/Keycloak). Leave empty for unauthenticated access.

Nodes

Backstage

A regular n8n node for workflow automation. Supports usableAsTool: true so it can also be attached to AI Agents directly.

Operations:

Operation Description Key Parameters
Search Free-text search across catalog and TechDocs query, searchType, limit
Get Entity Get full entity details by ref ref (e.g. component:default/my-service)
List Entities List/filter catalog entities kind, filter, limit, cursor
Get TechDocs Page Fetch a documentation page as text ref, path
List TechDocs Pages Table of contents for an entity ref
Get Relationships Traverse dependency graph ref, direction, relationType, depth
Execute Command Run any backctl CLI subcommand command

Backstage AI Tool

An AI Tool sub-node designed for use with n8n's AI Agent node. It exposes selected Backstage operations as LangChain-compatible tools that the agent can invoke autonomously during conversations.

Configure which operations the agent can access via the Available Operations multi-select.

Usage Examples

Workflow Automation

  1. Catalog Audit — Use a Schedule trigger + Backstage (List Entities) to periodically check for components missing ownership or lifecycle annotations.
  2. Dependency Impact Analysis — When a service is updated, use Get Relationships to find all downstream consumers and notify their owners.
  3. TechDocs Sync — Fetch documentation pages and push them to Confluence or Notion.

AI Agent (RAG)

Connect the Backstage AI Tool node to an AI Agent. The agent can then answer questions like:

  • "Who owns the payment-gateway service?"
  • "What APIs does the ride-service consume?"
  • "Show me the onboarding docs for the driver platform"

Development

# Install dependencies
npm install

# Build (TypeScript + esbuild bundling)
make build

# Lint
make lint

# Run n8n locally with the node loaded (builds + Docker image + starts container)
# Access n8n at http://localhost:5678
make run

# Clean build artifacts, node_modules, Docker image, and dev volume
make clean

Make targets

Target Description
make build Compile TypeScript and bundle with esbuild (npm run build)
make lint Run linter (npm run lint)
make docker Build + create Docker dev image (n8n-backstage-dev)
make run Build + Docker + run n8n at localhost:5678 (data persisted in a Docker volume)
make release Lint + build + interactive release (bump version, tag, push, publish via CI)
make info Show published package info from npm registry
make clean Remove dist/, node_modules/, Docker container, image, and dev volume

License

MIT

Discussion