Skip to main content

MCPServer authentication fields

The MCPServer resource records the authentication method an MCP server expects, plus the parameters and secret references needed to connect to it.

Workflow-client path

These fields are consumed at runtime only when calling the MCP server through the Dapr workflow client (see MCP Guardrails). On the recommended Catalyst path — agents speaking MCP through service invocation to a registered App ID — bearer middleware on the App ID's HTTP pipeline enforces auth instead, and these fields function as inventory metadata.

Pick the mode that matches what the MCP server expects.

ModeWhen to useSupported in
NoneLocal development, internal services on a trusted network.Console, CLI, YAML
HeadersServers that accept static credentials in HTTP headers (API keys, personal access tokens, vendor-specific schemes).Console, CLI, YAML
OAuth 2.0Servers that support the OAuth 2.0 client credentials grant.Console, CLI, YAML
SPIFFEServers that validate a SPIFFE-issued JWT (SVID) — typically other workloads in the same trust domain.CLI, YAML (not yet in the console UI)

Secret material is resolved from your project's secret store. You can reference secrets explicitly from the store when you want to share a single secret across resources or rotate it out of band.

None​

No credentials are recorded.

apiVersion: dapr.io/v1alpha1
kind: MCPServer
metadata:
  name: local-tools
spec:
  endpoint:
    stdio:
      command: python
      args: ["-m", "my_tools.py"]

stdio transport is only valid in self-hosted (local) mode. An MCPServer with stdio transport is rejected when running in Kubernetes.

Headers​

Use the headers field for any scheme that authenticates via a static HTTP header.

spec:
  endpoint:
    streamableHTTP:
      url: https://api.githubcopilot.com/mcp/
      headers:
        - name: Authorization
          secretKeyRef:
            name: github-token
            key: token
      auth:
        secretStore: kubernetes

auth.secretStore names the secret store used to resolve secretKeyRef entries. It defaults to kubernetes.

If you paste a literal token into the console's header form — or the OAuth client secret into the OAuth form — the value is stored as a managed secret in your project's secret store automatically and resolved back when needed. You only need to create a secret-store entry yourself when you want to share a value across resources or manage rotation out of band.

OAuth 2.0​

spec:
  endpoint:
    streamableHTTP:
      url: https://payments-mcp.internal/mcp
      auth:
        secretStore: kubernetes
        oauth2:
          issuer: https://auth.company.com
          clientID: my-client-id
          audience: mcp://payments
          scopes:
            - payments.read
            - payments.refund
          secretKeyRef:
            name: payments-mcp-oauth
            key: clientSecret

Required fields under auth.oauth2:

  • issuer — base URL of the OAuth provider. Token and JWKS endpoints are discovered from .well-known/openid-configuration.
  • clientID — OAuth client ID.
  • secretKeyRef — reference to the client secret in your secret store.

Optional fields:

  • audience — token audience claim required by the MCP server.
  • scopes — scopes requested from the issuer.

SPIFFE​

spec:
  endpoint:
    streamableHTTP:
      url: https://payments-mcp.internal/mcp
      auth:
        spiffe:
          jwt:
            header: Authorization
            headerValuePrefix: "Bearer "
            audience: mcp://payments

Required fields under auth.spiffe.jwt:

  • header — HTTP header that carries the SVID, typically Authorization.
  • audience — audience claim the MCP server validates the SVID against.

Optional:

  • headerValuePrefix — string prepended to the SVID in the header, typically "Bearer ".

Choosing a mode​

  • The MCP server is public or runs on localhost. Use none.
  • The MCP server uses an API key or PAT. Use headers with a secretKeyRef.
  • The MCP server supports OAuth and is hosted by a SaaS vendor. Use oauth2.
  • The MCP server is your own workload and you already use SPIFFE/mTLS between services. Use spiffe.

Next steps​

  • MCP Guardrails — the workflow-client flow that actually consumes these fields at runtime.
  • Enable an MCP server — enable a catalog entry from the Catalyst console, CLI, or YAML.
Last updated on