Skip to main content

Enable an MCP server

The MCP Catalog is your organization's library of MCP servers — pre-defined entries for popular third-party servers (GitHub, Linear, Atlassian, Stripe, and others) plus any internal MCP servers your platform team publishes. Each entry comes with its URL, transport, and authentication method already filled in. To make an MCP server available to clients in a project, you enable the catalog entry for that project and supply any project-specific credentials it needs.

note

Enabling a catalog entry adds connection metadata to your project. It does not by itself govern runtime calls — those flow through the MCP server's App ID and the access policies attached to it. Pair the two: enable the catalog entry for visibility and reuse, and run the MCP server as a Catalyst app for governance.

This page shows how to enable an MCP server from the Catalyst console, the CLI, and a YAML manifest, and how to publish a custom catalog entry for an MCP server your organization runs itself.

Prerequisites​

  • A Catalyst project. If you do not have one, see Create a project.
  • The endpoint URL of the MCP server you want to enable, plus any credentials it requires.
  • For CLI or YAML workflows, the Diagrid CLI installed and authenticated: 
    diagrid login

Enable a catalog entry​

From the Catalyst console​

  1. Open the Catalyst console and select your project.

  2. From the sidebar, open MCP Servers.

  3. Click Create. Pick a card from the Catalog for a common MCP server (github-mcpserver, linear-mcpserver, atlassian-mcpserver, stripe-mcpserver) — the URL, transport, and authentication method are pre-filled — or start from scratch to publish a custom entry (see Publish a custom catalog entry).

  4. Fill in the form:

    • Name — unique within the project.
    • Transport — streamableHTTP (recommended for production) or sse. (stdio is local-only and must be created via the CLI.)
    • URL — the MCP server endpoint (catalog entries pre-fill this).
    • Authentication — pick Headers, OAuth 2.0, or SPIFFE. For unauthenticated (none) servers, use the CLI or YAML instead.
    • Catalog metadata (optional) — display name, description, owner team and contact, tags, and links. Useful for service catalogs and operator portals.

    Paste credentials directly into the form. Catalyst stores any plaintext value you submit as a managed secret in your project's secret store.

  5. Click Save.

From the CLI​

List the catalog:

diagrid mcpserver catalog list

Enable an entry from the catalog:

diagrid mcpserver create --from-catalog github-mcpserver --name my-github

You provide:

  • A unique name for the entry within the project.
  • The credentials the catalog entry requires.

Built-in entries currently include github-mcpserver, linear-mcpserver, atlassian-mcpserver, and stripe-mcpserver.

Publish a custom catalog entry​

For an MCP server your organization runs itself, or a third-party server that is not in the built-in catalog, publish a custom catalog entry your team can enable in any project.

From the CLI​

diagrid mcpserver create

The CLI guides you through:

  • Name — unique within the project.
  • Transport — streamableHTTP, sse, or stdio (local development only).
  • URL — the MCP server endpoint.
  • Authentication — record what the upstream MCP server expects: none, headers (static API keys), oauth2, or spiffe. These fields describe the upstream server's contract. Runtime auth between an MCP client and server in Catalyst is enforced separately by bearer middleware attached to the MCP server's own App ID (see the Authentication tutorial).

From a YAML manifest​

# my-github.yaml
apiVersion: dapr.io/v1alpha1
kind: MCPServer
metadata:
  name: my-github
spec:
  endpoint:
    streamableHTTP:
      url: https://api.githubcopilot.com/mcp/
      headers:
        - name: Authorization
          secretKeyRef:
            name: github-token
            key: token
      auth:
        secretStore: kubernetes
diagrid apply -f my-github.yaml

View and manage enabled servers​

From the console​

On the MCP Servers list, open the entry you enabled. The detail view is organized into editable sections:

  • Connection — transport, URL, and timeout metadata.
  • Authentication — the configured auth mode and its parameters.
  • Catalog — display name, description, tags, owner, and links.

Click the pencil icon next to a section to open its edit dialog.

From the CLI​

List enabled servers in your project:

diagrid mcpserver list

Inspect a specific server:

diagrid mcpserver get my-github

Update a server (rotate credentials, change the URL):

diagrid mcpserver update my-github

Remove a server:

diagrid mcpserver delete my-github

Annotate with catalog metadata​

spec.catalog carries informational fields that are useful for service catalogs, internal portals, ownership tracking, and compliance tooling. Populate them when publishing a custom catalog entry so operators across your organization can see who owns each MCP server and where to find documentation.

The console exposes these under the Catalog section. The CLI flags on diagrid mcpserver create and update are --display-name, --description, --catalog-owner-team, --catalog-owner-contact, --catalog-tag (repeatable), and --catalog-link name:url (repeatable).

In YAML:

spec:
  catalog:
    displayName: Payments MCP
    description: Tools for charging customers and issuing refunds.
    owner:
      team: payments-platform
      contact: payments-oncall@example.com
    tags: ["payments", "production", "pii"]
    links:
      docs: https://wiki.internal/payments-mcp
      runbook: https://wiki.internal/payments-mcp/runbook
      dashboard: https://grafana.internal/d/payments-mcp

Govern runtime MCP calls​

Enabling a catalog entry is independent of runtime governance. To govern who can actually call an MCP server:

  1. Run the MCP server as a Catalyst app with its own App ID.
  2. Attach a Configuration with accessControl to that App ID — see the MCP access policies tutorial.
  3. Add bearer middleware to the App ID's HTTP pipeline for OAuth 2.0 — see the MCP authentication tutorial.

What's next​

Last updated on