MCP in Portal

Portal exposes its plugin capabilities as MCP (Model Context Protocol) tools that any compatible AI agent can discover and use. Whether you're using AiKA, Claude Code, Cursor, or VS Code Copilot, the same tools are available through a standard protocol.

How it works

Portal uses the @backstage/plugin-mcp-actions-backend to expose tools over MCP. Each Portal plugin registers its capabilities with the Actions Registry, and the MCP Actions Backend collects them into a single MCP server endpoint.

┌─────────────────────────────────────────────────┐
│  Portal Backend                                 │
│                                                 │
│  ┌──────────────┐  ┌──────────────────────────┐ │
│  │ Catalog      │──│                          │ │
│  └──────────────┘  │                          │ │
│  ┌──────────────┐  │  Actions    MCP Actions  │ │     ┌────────────┐
│  │ Soundcheck   │──│  Registry → Backend      │─│────▶│ AI Agents  │
│  └──────────────┘  │                          │ │     │ (AiKA,     │
│  ┌──────────────┐  │                          │ │     │  Claude,   │
│  │ Scaffolder   │──│                          │ │     │  Cursor)   │
│  └──────────────┘  └──────────────────────────┘ │     └────────────┘
└─────────────────────────────────────────────────┘

Each plugin backend registers its own tools with the Actions Registry. The MCP Actions Backend exposes them over Streamable HTTP at:

https://<your-portal>/api/mcp-actions/v1

No separate MCP server module is needed — the tools live where the data lives.

Connecting AI agents

External AI agents like Claude Code, Cursor, and VS Code Copilot can connect to Portal's MCP endpoint using the standard MCP client configuration:

{
  "mcpServers": {
    "portal": {
      "url": "https://<your-portal>/api/mcp-actions/v1",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Portal supports two authentication methods for external agents:

• Static tokens — Generate a token and configure it in backend.auth.externalAccess. Best for quick setup and CI environments.
• Dynamic Client Registration (experimental) — Agents request tokens through your Portal instance via OAuth, removing the need for pre-configured secrets. Requires the @backstage/plugin-auth package.

For full authentication setup instructions, see the @backstage/plugin-mcp-actions-backend documentation.

note

The SSE transport (/api/mcp-actions/v1/sse) is deprecated. Use Streamable HTTP (/api/mcp-actions/v1) for all new configurations.

A note on terminology

Portal documentation uses the term Actions for what the MCP specification calls tools. The Actions Registry is the mechanism through which Portal plugins publish MCP tools. These terms are interchangeable:

Portal term	MCP term
Action	Tool
Actions Registry	Tool registry / MCP server
Portal Actions	Built-in MCP tools

What you can do

Depending on your role, start with the page that's most relevant:

• Using agents with Portal data? See Available Tools for the list of built-in MCP tools and what they do.
• Building a Portal plugin? See Registering Tools for how to expose your plugin's capabilities as MCP tools.
• Connecting an AI agent to Portal? See Connecting AI agents above for authentication and setup.
• Connecting external MCP servers? See Third-Party Servers for how to add MCP servers from outside Portal (e.g., GitHub, Linear, custom internal servers).