# Manage MCP Servers

An **`MCPServer` resource** is Catalyst's connection definition for an [MCP server](https://docs.diagrid.io/concepts/mcp). It records the upstream URL, the transport (`streamable-http`, or the deprecated `sse`), the upstream credential, and optional catalog metadata. Catalyst fronts the connection at `/v1.0/diagrid/mcp/<name>` on the project's HTTP endpoint so agents reach the server through Catalyst rather than directly.

`MCPServer` resources are project-scoped and declared the same way as [Components](https://docs.diagrid.io/operate/project-operations/components), inheriting the same [declarative-management](https://docs.diagrid.io/operate/project-operations/declarative-management) model.

:::info Scope of this page
This page covers managing the inventory of MCP server connections — registering them, browsing the catalog, and curating org-wide entries. To control **which agents can call which tools**, see [Control tool access](https://docs.diagrid.io/develop/mcp/mcp-access-policies); to set the **upstream credential**, see [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication).
:::

## The MCP Catalog

The **MCP Catalog** is the organization-wide library of pre-defined MCP server connections. Each entry is a template that fixes the provider, upstream URL, transport, and default auth shape — you supply a resource name and a credential when you enable it in a project.

Browse the catalog from the CLI:

```bash
# List every entry
diagrid mcpserver catalog list

# Show the full template for one entry
diagrid mcpserver catalog get github-mcpserver -o yaml
```

For the full list of built-in entries and their default endpoints, see the [MCP servers reference](https://docs.diagrid.io/references/mcp-servers).

### Curate org-wide entries

Beyond the built-in entries, global administrators and editors can publish custom catalog entries for the whole organization, and hide entries a project shouldn't use:

```bash
# Publish a custom entry from a template file
diagrid mcpserver catalog add my-internal-mcp -f my-entry.yaml

# Update an entry's metadata or body
diagrid mcpserver catalog update my-internal-mcp -f my-entry.yaml

# Hide an entry (built-in or custom) from your org, or restore it
diagrid mcpserver catalog disable github-mcpserver
diagrid mcpserver catalog enable github-mcpserver

# Remove a custom entry (built-in entries can be disabled, not removed)
diagrid mcpserver catalog remove my-internal-mcp
```

## Enable a catalog entry

Enabling a catalog entry creates an `MCPServer` resource in the active project from the template. You supply a name and a credential; Catalyst takes the upstream URL, transport, and auth shape from the template and records the source so the connection's provenance is traceable.

Use the interactive flow for the guided path:

```bash
diagrid mcpserver create --interactive
```

It walks through picking a catalog entry, naming the resource, and providing credentials. Sensitive values are stored in the project's [secret store](https://docs.diagrid.io/operate/project-operations/secrets) automatically.

For non-interactive use, name the entry and pass the credential as flags:

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

## Declare a custom MCP server

Any MCP server that speaks `streamable-http` can be declared directly. Use a one-shot CLI command or a YAML spec.

The legacy `sse` transport is also accepted, for servers that have not migrated. Prefer `streamable-http` for anything new: the MCP specification deprecated HTTP+SSE in its 2026-07-28 revision with a 12-month removal window, and Catalyst logs a deprecation warning each time a connection uses it.

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

```yaml
# my-mcp.yaml
apiVersion: dapr.io/v1alpha1
kind: MCPServer
metadata:
  name: my-mcp
spec:
  endpoint:
    streamableHTTP:
      url: https://mcp.example.com/mcp
      timeout: 30s
      headers:
        - name: X-API-Key
          value: my-secret
  catalog:
    displayName: My MCP server
    description: Internal MCP server for the analytics team
    tags:
      - internal
```

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

`stdio` is not supported, because Catalyst fronts the server over HTTP. See [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication) for the OAuth 2.0 and SPIFFE auth shapes.

**Transparent secret management.** Credentials entered through `--header`, `--interactive`, or the console are extracted into a Catalyst-managed secret store before the resource is persisted — plaintext values never land in the control-plane database. To use your own secret store instead, see [Managing secrets](https://docs.diagrid.io/operate/project-operations/secrets).

## Control tool access

Registering an `MCPServer` connection does not grant any caller access to it. Every new connection is deny-by-default: Catalyst creates an empty [access policy](https://docs.diagrid.io/develop/mcp/mcp-access-policies) alongside the resource, so every tool call is rejected until you allow it. Grant a caller access to specific tools with `diagrid mcpserver access grant`:

```bash
diagrid mcpserver access grant my-mcp \
  --caller ops-agent \
  --allow-tools list_issues,create_issue \
  --wait
```

See [Control tool access](https://docs.diagrid.io/develop/mcp/mcp-access-policies) for the full per-tool, per-caller authorization model.

## List, inspect, enable, and delete

```bash
# List MCPServer resources in the active project
diagrid mcpserver list

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

# Stop accepting connections without deleting the definition, then restore
diagrid mcpserver disable my-mcp
diagrid mcpserver enable my-mcp

# Delete
diagrid mcpserver delete my-mcp
```

## Update a resource

To change a connection's fields — the URL, transport, headers, or auth — edit the spec and reapply it declaratively:

```bash
diagrid mcpserver get my-mcp -o yaml > my-mcp.yaml
# edit my-mcp.yaml
diagrid apply -f my-mcp.yaml
```

`diagrid apply` is the declarative-update path for `MCPServer` resources and works the same way it does for [Components](https://docs.diagrid.io/operate/project-operations/components).

## Catalog metadata on a resource

Every `MCPServer` resource — catalog-derived or custom — supports a `spec.catalog` section that records human-readable inventory information. The fields are advisory: they surface in the catalog browse view in the console and CLI.

```yaml
spec:
  catalog:
    displayName: My MCP server
    description: Internal MCP server for the analytics team
    tags:
      - internal
      - analytics
    owner:
      team: data-platform
      contact: data-platform@example.com
    links:
      docs: https://wiki.example.com/mcp/my-mcp
      runbook: https://wiki.example.com/runbook/my-mcp
```

The same fields are exposed as `--display-name`, `--description`, `--owner-team`, `--owner-contact`, `--tags`, and `--reference-links name:url` on `diagrid mcpserver create`.

## See also

- [MCP concepts](https://docs.diagrid.io/concepts/mcp) — the MCP Server, MCP Catalog, and access-policy primitives.
- [MCP servers reference](https://docs.diagrid.io/references/mcp-servers) — the built-in catalog entries.
- [Control tool access](https://docs.diagrid.io/develop/mcp/mcp-access-policies) — per-tool, per-caller authorization.
- [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication) — upstream credential configuration.
- [Response caching](https://docs.diagrid.io/develop/mcp/caching) — cache MCP responses at the sidecar to reduce upstream call volume.
- [Declarative management](https://docs.diagrid.io/operate/project-operations/declarative-management) — the `diagrid apply` command.