Story (Required)

As a developer / platform engineer interacting with RHDH via an MCP client, I should be able to use the tool to register new catalog entities. Likewise, I should be able to use it to unregister catalog entities that are no longer needed.

This story enables AI clients to manage catalog entity registration through MCP tools, providing the ability to add remote catalog-info YAML files to the Backstage catalog and remove entities when they are no longer needed. The goal is to allow developers and platform engineers to programmatically manage catalog entity lifecycle through natural language interactions while maintaining proper authentication and permission controls for write operations.

Background (Required)

The Backstage Software Catalog supports registering entities from remote sources like GitHub repositories containing catalog-info.yaml files, and unregistering entities when they are no longer relevant. Currently, this is done through the Backstage UI or direct API calls. By providing MCP tools for entity registration and unregistration, we enable AI assistants to help manage catalog lifecycle operations, making it easier for developers to onboard new services and clean up deprecated entities while ensuring proper authentication through static tokens with catalog write permissions.

Out of scope

Creation or deletion of actual catalog entities, modification of existing entity metadata, bulk registration operations, automatic discovery of catalog entities, integration with CI/CD pipelines for automated registration, user permission management

Approach (Required)

1. Implement MCP tool for catalog entity registration using Backstage Catalog API
2. Implement MCP tool for catalog entity unregistration
3. MCP tools implemented as Backstage plugins, and registered via the action registry (as outlined in https://github.com/backstage/backstage/tree/master/plugins/mcp-actions-backend)
4. Configure authentication using static token with catalog write permissions and document process.
5. If required: Support registration from remote catalog-info.yaml URLs (GitHub, GitLab, etc.)
6. Stretch: Validate catalog-info.yaml format before registration attempts
7. Handle registration conflicts and provide meaningful error messages

Dependencies

Backstage Catalog API write access, MCP server implementation, Backstage 1.40+ with MCP server plugin configured

Acceptance Criteria (Required)

1. MCP tool successfully registers catalog entities from remote YAML URLs
2. Registration operations properly authenticated using configured static token
3. MCP tool successfully unregisters entities by reference or location URL
4. Proper error handling
5. Tools registered in ActionRegistry and discoverable by AI clients
6. Unit test coverage
7. Evaluation data with known-good questions and responses from the tool

8. Elicitation / permission prompting to the user from the llm

Edge cases to consider:

• Invalid or unreachable catalog-info.yaml URLs
• Malformed YAML content or missing required fields
• Registration of entities that already exist in catalog
• Unregistration of entities with dependencies
• Authentication token expiration or invalid permissions
• Large catalog-info.yaml files with multiple entities
• Unregistration of non-existent entities
• Concurrent registration/unregistration operations

(✓) documentation updates (design docs, release notes etc)
(✓) demo needed
SOP required
education module update (Filled by RHDHPAI team only)
R&D label required (Filled by RHDHPAI team only)

Done Checklist

Code is completed, reviewed, documented and checked in
Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
Continuous Delivery pipeline(s) is able to proceed with new code included
Customer facing documentation, API docs, design docs etc. are produced/updated, reviewed and published
Acceptance criteria are met
If the Grafana dashboard is updated, ensure the corresponding SOP is updated as well