Backstage MCP Actions

Backstage MCP actions

Expose only intentionally registered and authorized Backstage actions to AI clients.

When to invoke

• "Install the MCP Actions Backend."
• "Register a Backstage action as an MCP tool."
• "Split catalog and scaffolder actions into focused MCP servers."
• "Review Backstage well-known actions and destructive attributes."

Procedure

1. Confirm the Backstage version and that Actions Registry and MCP Actions APIs are available.
2. Read the current well-known action inventory and the repository's registered actions.
3. Register custom actions with input, output, and optional secrets schemas.
4. Set readOnly, idempotent, and destructive attributes explicitly; conservative defaults otherwise treat actions as mutating.
5. Add a basic visibilityPermission when action listing or invocation needs policy control.
6. Install @backstage/plugin-mcp-actions-backend and register it in the backend.
7. Restrict backend.actions.pluginSources and configure include/exclude rules by ID and attributes.
8. Keep namespaced tool names unless backward compatibility requires otherwise.
9. Choose one server or multiple focused servers with capability-oriented descriptions and usage instructions.
10. Configure authentication. Prefer supported OAuth/CIMD for interactive users; treat static tokens as a temporary, restricted external-access mechanism.
11. Test list visibility, schema validation, permission denial, secrets separation, safe read-only invocation, and approval for destructive actions.

Safety

• Secrets schemas stay out of tool definitions and LLM context.
• Denied actions should not be discoverable or invokable.
• Exclude destructive actions from general-purpose servers by default.
• auth.who-am-i requires user credentials, not service or unauthenticated credentials.

Output template

## Backstage MCP actions result

| Server | Included actions | Exclusions | Auth | Endpoint |
| --- | --- | --- | --- | --- |

### Action controls
| Action | Attributes | Permission | Validation |
| --- | --- | --- | --- |

Quality gate

• Action schemas and behavioral attributes are explicit.
• Secrets are separated from ordinary inputs.
• Plugin sources and action filters implement least privilege.
• Permission visibility and denial behavior are tested.
• Server descriptions state capabilities rather than protocol identity.
• Authentication and destructive-action approvals are validated.

References

• MCP Actions Backend
• Well-known actions
• Actions Registry