# MCP on Catalyst

Catalyst puts a proxy endpoint in front of every [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server your agents use. Your agent points its existing MCP client at one Catalyst URL; Catalyst forwards the call to the real upstream server, injects the upstream credentials, and enforces a per-tool access policy on the way through.

Because the proxy endpoint speaks plain MCP over HTTP, **off-the-shelf MCP clients and agent frameworks work unchanged** — there is no Catalyst-specific MCP SDK to adopt. The agent only ever sees the Catalyst endpoint and a token; it never holds the upstream server's URL or credentials.

Looking for the other direction — Catalyst's *own* management tools inside your AI coding assistant? That is [`diagrid mcp serve`](https://docs.diagrid.io/develop/local-development/assistant-mcp), a server that runs on your machine and is unrelated to the project resources described here.

## How it works

You register an upstream MCP server once as an [`MCPServer`](https://docs.diagrid.io/operate/project-operations/mcp-servers) connection — from the [MCP Catalog](https://docs.diagrid.io/references/mcp-servers) or your own URL. Catalyst exposes it on your project's HTTP endpoint at a stable path keyed by the connection name:

```
https://<project-http-endpoint>/v1.0/diagrid/mcp/<mcp-server-name>
```

The agent (the MCP client) connects to that URL and authenticates with its API token in the `dapr-api-token` header. Catalyst resolves the connection, applies the [access policy](https://docs.diagrid.io/develop/mcp/mcp-access-policies) attached to it, and — if the call is allowed — forwards it to the upstream server with the configured upstream credentials attached.

```mermaid
flowchart LR
  CLIENT(Agent / MCP client)
  subgraph Catalyst
    API(Proxy endpoint
    /v1.0/diagrid/mcp/&lt;name&gt;)
    POLICY{MCP access policy}:::decision
  end
  SERVER(Upstream MCP server)

  CLIENT-- dapr-api-token -->API
  API-->POLICY
  POLICY-- allow + inject upstream auth -->SERVER
  POLICY-. 403 / filtered .->CLIENT

  classDef decision stroke:#ed8936
```

For each call, Catalyst:

- Authenticates the caller by its API token
- Filters tool discovery (`tools/list`) down to the tools the caller is allowed to use
- Rejects unauthorized tool calls (`tools/call`) with `403` before they reach the server
- Injects the upstream server's credentials so they never live in agent code
- Captures logs, metrics, and traces for the call

## What you control

| Concern | How |
|---|---|
| **Which upstream server** | An [`MCPServer`](https://docs.diagrid.io/operate/project-operations/mcp-servers) connection — enabled from the [catalog](https://docs.diagrid.io/references/mcp-servers) or declared with your own URL and transport. |
| **Who can call which tools** | An [`MCPServerAccessPolicy`](https://docs.diagrid.io/develop/mcp/mcp-access-policies) — a deny-by-default, per-tool, per-caller allow-list managed with `diagrid mcpserver access`. |
| **Upstream credentials** | Configured on the `MCPServer` (static headers, OAuth 2.0, or SPIFFE) and stored in your project's secret store. See [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication). |
| **Response caching** | An opt-in TTL cache at the sidecar that serves repeated tool calls from memory. See [Response caching](https://docs.diagrid.io/develop/mcp/caching). |

## Get started

- [Connect an MCP client](https://docs.diagrid.io/develop/mcp/connect) — Point a standard MCP client at Catalyst's MCP proxy endpoint and discover tools.
- [Add an MCP server](https://docs.diagrid.io/develop/mcp/mcpserver-getting-started) — Enable a catalog entry or register your own MCP server connection.
- [Control tool access](https://docs.diagrid.io/develop/mcp/mcp-access-policies) — Grant and revoke per-tool, per-caller access with a deny-by-default policy.
- [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication) — Authenticate the client to Catalyst and Catalyst to the upstream MCP server.