Skip to main content

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 — 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 and governs it with an access policy.

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.

Prerequisites​

  • A Catalyst project. If you don't have one, see Create a project.
  • The Diagrid CLI, 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:

diagrid mcpserver catalog list

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

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, and creates the connection. See the MCP servers reference 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:

diagrid mcpserver create

Or pass the details as flags:

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:

# 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
diagrid apply -f my-mcp.yaml

Catalyst supports the streamable-http and sse transports. stdio is not supported, because Catalyst fronts the server over HTTP. For the full authentication options, see Authentication.

Manage a connection​

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

Last updated on