Skip to main content

Manage MCP Servers

An MCPServer resource is Catalyst's connection definition for an MCP server. 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, inheriting the same declarative-management model.

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; to set the upstream credential, see 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:

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

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:

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

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

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

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.

diagrid mcpserver create my-mcp \
  --project my-project \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --header "X-API-Key:my-secret"
# 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
diagrid apply -f my-mcp.yaml

stdio is not supported, because Catalyst fronts the server over HTTP. See 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.

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 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:

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

See Control tool access for the full per-tool, per-caller authorization model.

List, inspect, enable, and delete​

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

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.

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.

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​

Last updated on