> ## 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.

# MCP in Portal

> How Portal exposes plugin capabilities as MCP tools that AI agents like AiKA, Claude Code, Cursor, and VS Code Copilot can discover and use.

Portal exposes its plugin capabilities as [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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`](https://www.npmjs.com/package/@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:

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "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 following our [static token guide](../../guides/Admin/create-api-key). Best for quick setup and CI environments.
* **CIMD (Client-Initiated Metadata Discovery)** *(beta)* — Agents authenticate through your Portal instance via OAuth, removing the need for pre-configured secrets. See [Connecting AI Agents](./connecting-agents) for setup instructions.

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

## 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](./available-tools) for the list of built-in MCP tools and what they do.
* **Building a Portal plugin?** See [Registering Tools](./registering-tools) for how to expose your plugin's capabilities as MCP tools.
* **Connecting an AI agent to Portal?** See [Connecting AI Agents](./connecting-agents) for CIMD setup, client configuration, and security considerations.
* **Connecting external MCP servers?** See [Third-Party Servers](./third-party-servers) for how to add MCP servers from outside Portal (e.g., GitHub, Linear, custom internal servers).