Backstage v1.51.0-next.2, Microsoft Graph Ingestion and an MCP Glossary

👋 Welcome to Backstage Weekly 133.

TL;DR

Backstage v1.51.0-next.2 shipped May 6 with cursor-based Microsoft Graph ingestion for large Azure AD tenants and air-gapped TechDocs support. v1.50.4 delivered security patches for the catalog unprocessed-entities plugins - apply before moving to the v1.51 cycle. We published a working glossary for MCP and context engineering, defining the vocabulary platform teams need as they connect service catalogs to AI agents.

Backstage v1.51.0-next.2

The second pre-release of the v1.51 cycle landed May 6 with two substantive additions for catalog operators and TechDocs users.

The new @backstage/plugin-catalog-backend-module-msgraph-incremental module (v0.1.0-next.0) introduces cursor-based ingestion for Microsoft Graph. Rather than pulling entire user and group datasets into memory, it processes up to 999 users or 100 groups per burst and persists @odata.nextLink cursors so a pod restart picks up where it left off. Worth evaluating as a lower-memory alternative if you run large Azure Active Directory tenants in your Backstage user catalog.

TechDocs also gets air-gapped support: a new --disableExternalFonts flag on techdocs-cli generate and a matching techdocs.generator.mkdocs.disableExternalFonts app-config option, both stopping MkDocs from reaching Google Fonts during the build step - the missing piece for isolated networks.

From the v1.51.0-next.1 drop (April 28): the Header component's main CSS class was removed (breaking change for custom styles), and it gains sticky, description, tags, and metadata props with breadcrumbs deprecated. The upgrade helper at backstage.github.io/upgrade-helper/?to=1.51.0-next.2 covers the full migration. v1.50.4 (April 29) delivered security patches for the catalog unprocessed-entities plugins - apply before moving to the v1.51 cycle.

From the Roadie blog

We published a working glossary this week for the vocabulary collision happening as platform teams start connecting their service catalogs to AI agents. The piece works through three concept clusters - agents, context, and MCP - that teams regularly conflate when discussing how to make internal developer portals agent-accessible.

The core definitions: an agent is an LLM-driven system that plans and executes multi-step work by combining reasoning with tool use. Context is the structured, scoped information an agent gets at inference time - a curated bundle assembled from your platform's knowledge graph, scoped to the query at hand. MCP (Model Context Protocol) is the interface layer, standardizing how agents call tools and how those tools respond.

For Backstage users, the mapping is direct. Configured as an MCP Server, your service catalog exposes typed entity data to agents in a queryable form. The ownership graph, SLA annotations, deployment records, and cost data in your catalog are exactly the business context agents need to produce accurate responses rather than plausible-sounding ones. The glossary also defines context planes, context bundles, skills, and agent identity - terms circulating in the community without agreed-upon meaning.

Worth a read if you're in conversations about making your Backstage instance agent-accessible, or fielding questions about MCP from engineering leadership. Context, Agents, MCP: A Working Glossary for Platform Teams

Community this week

🗂️ Issue #34154 (May 7, @koalaty-code) details how /api/catalog/entity-facets generates WHERE IN (subquery) queries that force full table scans on the search table. On PostgreSQL 16 with millions of rows, a single facets request can run 10+ seconds and spike CPU to 100% under concurrent load. The proposed fix is to replace the subquery with an INNER JOIN so the planner scans the smaller filtered entity set first. Worth following if you run large catalogs on PostgreSQL.

🐛 @drodil filed issue #34146 on May 7 after entities created programmatically with null values in metadata.annotations triggered a Cannot read properties of null (reading 'match') TypeError in OverviewPage.tsx. Fix is already in PR #34171 ; the open question of whether null annotations should be rejected at ingestion rather than crash the UI is still being discussed.

📋 @deiga's issue #34134 (May 5) is a nine-point checklist of frontend migration gaps from a real production migration: no decision guidance on extension overrides versus blueprints versus extension config, the App Visualizer buried in troubleshooting rather than promoted as a debugging tool, manual plugin imports silently suppressing auto-discovery, and a double-header rendering bug in hybrid mode. Useful field reference if you're mid-migration.

What shipped

• @backstage/[email protected] - new cursor-based Microsoft Graph ingestion module
• @techdocs/[email protected] - --disableExternalFonts flag for air-gapped TechDocs builds
• @backstage/[email protected] - techdocs.generator.mkdocs.disableExternalFonts app-config option
• @backstage/[email protected] - Combobox component, Card keyboard focus fixes, searchDebounceMs and filterDebounceMs on useTable
• @backstage/[email protected] - Header sticky, description, tags, metadata props; breadcrumbs deprecated (breaking: main header CSS class removed)
• @backstage/[email protected] - stable DOM markers for Page and Header layouts
• @backstage/[email protected] - GitLab fetch mode fix; transient network error retry
• @backstage/[email protected] - ConfigContent migrated from Material UI to Backstage UI
• @backstage/[email protected] - no-self-package-imports lint rule
• v1.50.4 (April 29) - security patches for the catalog unprocessed-entities plugins