Adding Third-Party MCP Servers to AiKA

Overview

AiKA supports integration with third-party MCP (Model Context Protocol) servers to extend its capabilities beyond built-in Portal Actions. These servers can be added to your Software Catalog and then manually enabled for use with AiKA.

Security and Operational Risks

Third-party MCP servers introduce significant risks:

• Automatic Execution: AiKA executes 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 to AiKA 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 AiKA:

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"

note

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 with AiKA, 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 Specification

The 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 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

note

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 AiKA to use.

Configuring Authentication for MCP Servers

MCP servers can be configured with authentication to access protected external services. This allows AiKA 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
• Atlassian
• AWS ALB
• Azure
• Azure Easy Auth
• Bitbucket
• Bitbucket Server
• Cloudflare Access
• GitHub
• GitLab
• Google
• Google IAP
• Guest
• Okta
• OAuth 2 Custom Proxy
• OneLogin
• VMware Cloud

Configuring Authentication Annotations

AiKA 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:

• AiKA obtains OAuth tokens from the configured provider on behalf of the user
• Tokens are automatically 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)
• AiKA automatically obtains authentication tokens using Backstage's plugin-to-plugin authentication
• Bearer tokens are automatically injected in the Authorization header

note

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"

note

This example is for demonstration purposes. The mcp-actions server is automatically registered in Portal and does not need to be manually installed.

tip

When an MCP server requires OAuth authentication, users will be prompted to authenticate with the configured provider the first time they use the server in AiKA. Backend plugin authentication happens automatically without user prompts.

Using Third-Party MCP Servers

Once enabled, MCP servers can be used in AiKA 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. AiKA automatically selects and uses 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"

AiKA calls the CodeSearch MCP Server to find TypeScript files and returns file paths, repositories, and GitHub links while showing progress as each action completes.