Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Portal supports integration with third-party MCP (Model Context Protocol) servers to extend the tools available to AI agents beyond built-in Portal capabilities. These servers can be added to your Software Catalog and then manually enabled by users.
Security and Operational RisksThird-party MCP servers introduce significant risks:
  • Automatic Execution: AI agents execute server actions without user confirmation, making servers that modify or delete data particularly risky
  • Data Exposure: Third-party servers may log, store, or transmit your queries and organizational data
  • External Dependencies: We cannot guarantee the availability, reliability, or security of third-party services
Users accept full responsibility for third-party server usage and must comply with external provider terms and agreements.Best Practice: Only enable read-only servers from trusted sources.

​
Adding MCP Servers to the Catalog

MCP servers can be made available by adding them to the Software Catalog as API entities with specific configuration.

​
Example: Unauthenticated MCP Server

Here’s an example YAML file for an unauthenticated MCP server. Adding this entity makes the MCP server available to AI agents: 
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  title: Example MCP Server
  name: example-mcp
  description: Provides example functionality for demonstration.
  annotations:
    mcp.spotify.com/schema-version: '2025-09-29'
spec:
  type: mcp-server
  lifecycle: production
  owner: platform-team
  definition: |
    name: com.spotify/example-mcp
    description: "Provides example functionality for demonstration."
    version: "0.0.1"
    remotes:
      - type: streamable-http
        url: "https://example-mcp.spotify.net/mcp"
This example shows an unauthenticated MCP server. For authenticated servers, see the Configuring Authentication for MCP Servers section below.

​
Schema Requirements

To register an MCP server, create a catalog entity with:
  • Valid API Entity: Must be a valid API entity according to Backstage OSS
  • Entity Type: Set kind: API and spec.type: mcp-server in the catalog entity
  • Required Annotation: Add mcp.spotify.com/schema-version: '2025-09-29' to specify the schema version
  • Definition Field: YAML-formatted string containing the required fields below
Schema SpecificationThe MCP server definition must adhere to the Model Context Protocol (MCP) server configuration schema. Portal currently supports schema version 2025-09-29, which is the latest MCP schema specification.
Managed by Portal and Entity OverlaysYou can use Managed by Portal or Entity Overlays to manage your MCP server entities in the Software Catalog. As long as the final catalog entity represents a valid MCP server according to the specifications above, it doesn’t matter where the information comes from. The catalog is the source of truth.

​
Required Fields in definition

FieldTypeDescription
namestringNamespaced identifier for the MCP server (e.g., “com.spotify/example-mcp”)
descriptionstringHuman-readable description of the server’s capabilities
versionstringSemantic version number (e.g., “0.0.1”)
remotesarrayConnection endpoints for the MCP server. If both streamable-http and sse are specified, streamable-http will be preferred
remotes[].typestringTransport protocol: "streamable-http" (HTTP streaming, preferred) or "sse" (Server-Sent Events)
remotes[].urlstringFull URL endpoint for the MCP server
MCP servers registered in the catalog with type: mcp-server and spec.lifecycle: production are available for selection. Users must manually enable the servers they want to use.

​
Configuring Authentication for MCP Servers

MCP servers can be configured with authentication to access protected external services. This allows AI agents to securely interact with third-party APIs on behalf of users.

​
Prerequisites

Before configuring authentication for an MCP server:
  1. Backstage OSS Compatibility: Any authentication provider that is compatible with Backstage OSS can be used, including custom providers or community-contributed providers
  2. Authentication Provider Must Be Installed: The required authentication provider must be pre-installed and configured on your Portal instance

​
Common Authentication Providers

Portal supports any Backstage OSS-compatible authentication provider for MCP servers. The following are commonly used providers:

​
Configuring Authentication Annotations

Portal supports two authentication methods for MCP servers:

​
1. External OAuth Provider Authentication

For external MCP servers that require OAuth authentication, add these annotations:
AnnotationRequiredDescriptionExample
mcp.spotify.com/auth-api-idYesThe authentication provider API ID specified in the auth provider source codecore.auth.github
mcp.spotify.com/auth-scopesNoJSON array of OAuth scopes required by the MCP server["repo","read:org"]
When using OAuth provider authentication:
  • Tokens are automatically obtained from the configured provider on behalf of the user
  • Tokens are injected as Bearer tokens in the Authorization header for all requests to the MCP server

​
2. Backend Plugin Authentication

For MCP servers hosted as Backstage backend plugins, use plugin-to-plugin authentication:
AnnotationRequiredDescriptionExample
mcp.spotify.com/auth-plugin-idYesThe plugin ID of the backend plugin hosting the MCP servermcp-actions
When using backend plugin authentication:
  • The MCP server URL should point to your Portal instance (e.g., https://your-portal.spotifyportal.com/api/mcp-actions/v1)
  • Authentication tokens are obtained automatically using Backstage’s plugin-to-plugin authentication
  • Bearer tokens are automatically injected in the Authorization header
You can only use one authentication method per MCP server - either OAuth provider authentication or backend plugin authentication, not both.

​
Example: GitHub MCP Server with OAuth Authentication

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  title: GitHub MCP Server
  name: github-mcp
  description: This server provides access to GitHub repositories and data.
  annotations:
    mcp.spotify.com/schema-version: '2025-09-29'
    mcp.spotify.com/auth-api-id: 'core.auth.github'
    mcp.spotify.com/auth-scopes: '["repo","read:packages","read:org"]'
spec:
  type: mcp-server
  lifecycle: production
  owner: platform-team
  definition: |
    name: com.spotify/github-mcp
    description: "This server provides access to GitHub repositories and data."
    version: "0.0.1"
    remotes:
      - type: streamable-http
        url: "https://api.githubcopilot.com/mcp"

​
Example: Backend Plugin MCP Server with Plugin Authentication

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  title: MCP Actions Server
  name: mcp-actions
  description: Backstage portal actions exposed via MCP protocol.
  annotations:
    mcp.spotify.com/schema-version: '2025-09-29'
    mcp.spotify.com/auth-plugin-id: 'mcp-actions'
spec:
  type: mcp-server
  lifecycle: production
  owner: platform-team
  definition: |
    name: com.spotify/mcp-actions
    description: "Backstage portal actions exposed via MCP protocol."
    version: "0.0.1"
    remotes:
      - type: streamable-http
        url: "https://your-portal.spotifyportal.com/api/mcp-actions/v1"
This example is for demonstration purposes. The mcp-actions server is automatically registered in Portal and does not need to be manually installed.
When an MCP server requires OAuth authentication, users will be prompted to authenticate with the configured provider the first time they use the server. Backend plugin authentication happens automatically without user prompts.

​
Using Third-Party MCP Servers

Once enabled, MCP servers can be used in AI agent conversations.

​
Server Selection and Management

Users can select which MCP servers to enable through the Portal MCP Servers dialog. Click “Add server” to choose from available catalog entries:
MCP Servers Configuration

​
Server Use

Users simply ask questions in plain English. AI agents automatically select and use relevant enabled MCP servers to provide comprehensive answers. Example: Code Search Request When a user asks: “Please search for TypeScript files that define Backstage plugins”
AI Agent Using MCP Server
The agent calls the CodeSearch MCP Server to find TypeScript files and returns file paths, repositories, and GitHub links while showing progress as each action completes.