# Add an MCP server

To let your agents use an MCP server, register it once as an `MCPServer` connection in your project. You can enable a pre-defined entry from the [MCP Catalog](https://docs.diagrid.io/references/mcp-servers) — GitHub, Linear, Stripe, and others, with the URL, transport, and auth shape already filled in — or register your own server by URL. Either way, Catalyst then fronts it at a [MCP proxy endpoint](https://docs.diagrid.io/develop/mcp/connect) and governs it with an [access policy](https://docs.diagrid.io/develop/mcp/mcp-access-policies).

This page covers the quick path to get a server in place. For more advanced operations - catalog curation or declarative configuration — see [Manage MCP Servers](https://docs.diagrid.io/operate/project-operations/mcp-servers).

## Prerequisites

- A Catalyst project. If you don't have one, see [Create a project](https://docs.diagrid.io/operate/platform-operations/projects).
- The [Diagrid CLI](https://docs.diagrid.io/references/catalyst/catalyst-cli-intro), authenticated with `diagrid login`.
- The credential the upstream server requires (an API key, OAuth client, and so on).

## Enable a catalog entry

Browse the built-in catalog:

```bash
diagrid mcpserver catalog list
```

Enable an entry, giving the connection a name and supplying the credential it needs:

```bash
diagrid mcpserver create my-github \
  --from-catalog github-mcpserver \
  --header "Authorization:Bearer <github-token>"
```

Catalyst takes the upstream URL, transport, and auth shape from the catalog template, stores your credential in the project [secret store](https://docs.diagrid.io/operate/project-operations/secrets), and creates the connection. See the [MCP servers reference](https://docs.diagrid.io/references/mcp-servers) for every built-in entry and the credential each one expects.

## Register a custom server

For a server that isn't in the catalog, register it by URL. The interactive flow walks you through name, URL, transport, and authentication:

```bash
diagrid mcpserver create
```

Or pass the details as flags:

```bash
diagrid mcpserver create my-mcp \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --header "X-API-Key:my-secret"
```

You can also declare the connection as YAML and apply it:

```yaml
# my-mcp.yaml
apiVersion: dapr.io/v1alpha1
kind: MCPServer
metadata:
  name: my-mcp
spec:
  endpoint:
    streamableHTTP:
      url: https://mcp.example.com/mcp
      headers:
        - name: X-API-Key
          value: my-secret
```

```bash
diagrid apply -f my-mcp.yaml
```

Use `streamable-http`. Catalyst also accepts the legacy `sse` transport for servers that have not migrated yet, but the MCP specification deprecated HTTP+SSE in its 2026-07-28 revision with a 12-month removal window, and a connection that uses it logs a deprecation warning on every call. `stdio` is not supported, because Catalyst fronts the server over HTTP. For the full authentication options, see [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication).

## Manage a connection

```bash
# List connections in the project
diagrid mcpserver list

# Inspect one (add --show-sensitive-values to reveal masked credentials)
diagrid mcpserver get my-mcp

# Temporarily stop accepting connections without deleting the definition
diagrid mcpserver disable my-mcp
diagrid mcpserver enable my-mcp

# Remove a connection
diagrid mcpserver delete my-mcp
```

## What's next

A new MCP server denies all access until you grant it, so finish the setup with these two steps:

- [Control tool access](https://docs.diagrid.io/develop/mcp/mcp-access-policies) — grant your agent access to the tools it needs.
- [Connect an MCP client](https://docs.diagrid.io/develop/mcp/connect) — point your agent at the server's Catalyst endpoint.