> ## 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.
# Third-Party MCP Servers
> Add third-party MCP servers to Portal to extend AI agent capabilities beyond built-in tools, with security and operational considerations.
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 Risks**
**Third-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:
```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
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](#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](https://backstage.io/docs/features/software-catalog/descriptor-format#kind-api)
* **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 Specification**
The MCP server definition must adhere to the [Model Context Protocol (MCP) server configuration schema](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json). Portal currently supports schema version `2025-09-29`, which is the latest MCP schema specification.
**Managed by Portal and Entity Overlays**
You 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`
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Namespaced identifier for the MCP server (e.g., "com.spotify/example-mcp") |
| `description` | string | Human-readable description of the server's capabilities |
| `version` | string | Semantic version number (e.g., "0.0.1") |
| `remotes` | array | Connection endpoints for the MCP server. If both `streamable-http` and `sse` are specified, `streamable-http` will be preferred |
| `remotes[].type` | string | Transport protocol: `"streamable-http"` (HTTP streaming, preferred) or `"sse"` (Server-Sent Events) |
| `remotes[].url` | string | Full 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:
* [Auth0](https://backstage.io/docs/auth/auth0/provider)
* [Atlassian](https://backstage.io/docs/auth/atlassian/provider)
* [AWS ALB](https://backstage.io/docs/auth/aws-alb/provider)
* [Azure](https://backstage.io/docs/auth/microsoft/provider)
* [Azure Easy Auth](https://backstage.io/docs/auth/microsoft/easy-auth)
* [Bitbucket](https://backstage.io/docs/auth/bitbucket/provider)
* [Bitbucket Server](https://backstage.io/docs/auth/bitbucketServer/provider)
* [Cloudflare Access](https://backstage.io/docs/auth/cloudflare/provider)
* [GitHub](https://backstage.io/docs/auth/github/provider)
* [GitLab](https://backstage.io/docs/auth/gitlab/provider)
* [Google](https://backstage.io/docs/auth/google/provider)
* [Google IAP](https://backstage.io/docs/auth/google/gcp-iap-auth)
* [Guest](https://backstage.io/docs/auth/guest/provider)
* [Okta](https://backstage.io/docs/auth/okta/provider)
* [OAuth 2 Custom Proxy](https://backstage.io/docs/auth/oauth2-proxy/provider)
* [OneLogin](https://backstage.io/docs/auth/onelogin/provider)
* [VMware Cloud](https://backstage.io/docs/auth/vmware-cloud/provider)
### 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:
| Annotation | Required | Description | Example |
| ----------------------------- | -------- | ----------------------------------------------------------------------------- | --------------------- |
| `mcp.spotify.com/auth-api-id` | Yes | The authentication provider API ID specified in the auth provider source code | `core.auth.github` |
| `mcp.spotify.com/auth-scopes` | No | JSON 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:
| Annotation | Required | Description | Example |
| -------------------------------- | -------- | ---------------------------------------------------------- | ------------- |
| `mcp.spotify.com/auth-plugin-id` | Yes | The plugin ID of the backend plugin hosting the MCP server | `mcp-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
```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
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
```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
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:
### 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"*
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.