2 - Dapr MCP server configuration reference

The Dapr MCP server takes a few command-line flags and reads everything else from environment variables. The server checks authentication settings at startup and exits with an error if they are invalid or incomplete, rather than starting without protection.

Command-line flags

Server and Dapr connection

The DAPR_* connection variables are read by the Dapr Go SDK that the server uses.

HTTP transport

These settings apply only when the server runs with --http.

The server always serves /livez, /readyz, and /startupz without authentication; see Health endpoints. MCP requests are served on every other path, so http://<host>:<port>/ is the MCP endpoint. The one exception is /dapr/subscribe, which returns an empty subscription list for the Dapr sidecar and also needs no authentication.

Authentication

Authentication applies to the HTTP transport. See Authentication for how the modes work and for examples.

Telemetry

Telemetry is off until an OTLP endpoint is set. See Observability for what the server emits.

3 - Authenticating clients of the Dapr MCP server

The Dapr MCP server can require a valid token on every MCP request it serves over streamable HTTP. Authentication is off by default. Set AUTH_MODE to turn it on:

Authentication only applies to the HTTP transport. Over stdio, the MCP client starts the server as a local process, and there is no network listener to protect.

The server checks the settings for the selected mode at startup. If a required variable is missing or a value can’t be parsed, it exits with an error that names the variable. An unrecognized AUTH_MODE value is also rejected at startup.

Sending a token

Clients send the token in the Authorization header, either as Bearer <token> or as the raw token. If DAPR_SENTRY_TOKEN_HEADER names another header, the server checks that header first, in every mode, and expects the raw token there.

A request with no token, or with a token that no enabled method accepts, gets 401 Unauthorized. The server doesn’t say which check failed. Set DAPR_MCP_SERVER_LOG_LEVEL=debug to log the reason on the server.

OIDC

Use oidc for tokens issued to users or applications by an identity provider such as Microsoft Entra ID, Okta, Auth0, Keycloak, or Google.

export AUTH_MODE=oidc
export OIDC_ISSUER_URL=https://login.example.com/realms/agents
export OIDC_CLIENT_ID=dapr-mcp-server
dapr run --app-id dapr-mcp-server --resources-path ./components -- dapr-mcp-server --http 0.0.0.0:8080

SPIFFE

Use spiffe for service-to-service calls between workloads that get JWT-SVIDs from a SPIFFE implementation such as SPIRE. The server connects to the Workload API at startup to get trust bundles, waiting up to 10 seconds.

export AUTH_MODE=spiffe
export SPIFFE_TRUST_DOMAIN=example.org
export SPIFFE_SERVER_ID=spiffe://example.org/dapr-mcp-server
export SPIFFE_ENDPOINT_SOCKET=unix:///run/spire/sockets/agent.sock
export SPIFFE_ALLOWED_CLIENTS=spiffe://example.org/ns/agents/sa/planner

Dapr Sentry

Use dapr-sentry when the callers are Dapr apps. Dapr Sentry can issue each app a JWT whose subject is the app’s SPIFFE ID, and publish the signing keys as a JWKS. To turn this on in Sentry, enable JWT issuing and the OIDC server, using the Sentry Helm values shown in Authenticating with a Federated Identity Credential. The Microsoft Entra ID steps on that page don’t apply. The JWKS is served at /jwks.json on the Sentry OIDC port. Each calling app requests a token for the audience you set in DAPR_SENTRY_AUDIENCE with the dapr.io/sentry-request-jwt-audiences annotation, or the --sentry-request-jwt-audiences flag in self-hosted mode.

An MCPServer resource with auth.spiffe.jwt sends such a token on every call, so this mode pairs naturally with declaring the Dapr MCP server as an MCPServer.

export AUTH_MODE=dapr-sentry
export DAPR_SENTRY_JWKS_URL=https://dapr-sentry.dapr-system.svc.cluster.local:9080/jwks.json
export DAPR_SENTRY_TRUST_DOMAIN=public
export DAPR_SENTRY_AUDIENCE=mcp://dapr-mcp-server
export DAPR_SENTRY_ISSUER=https://sentry.example.com

The server fetches the JWKS at startup and exits if it can’t. Afterwards it refreshes the keys on the configured interval, and also when a token arrives signed with a key it doesn’t have, at most once every 30 seconds. If Sentry can’t be reached, the server keeps using the cached keys for up to 24 hours. Only asymmetric signing algorithms are accepted, the token must have an exp claim, and exp, nbf, and iat are checked with one minute of clock-skew leeway.

Hybrid

hybrid accepts tokens from more than one method. Turn on each method you want with its *_ENABLED variable, and set that method’s required variables. At least one method must be on.

export AUTH_MODE=hybrid

export OIDC_ENABLED=true
export OIDC_ISSUER_URL=https://login.example.com/realms/agents
export OIDC_CLIENT_ID=dapr-mcp-server

export DAPR_SENTRY_ENABLED=true
export DAPR_SENTRY_JWKS_URL=https://dapr-sentry.dapr-system.svc.cluster.local:9080/jwks.json
export DAPR_SENTRY_TRUST_DOMAIN=public
export DAPR_SENTRY_AUDIENCE=mcp://dapr-mcp-server

The server tries the enabled methods in the order OIDC, SPIFFE, Dapr Sentry, and accepts the request as soon as one of them validates the token. The *_ENABLED variables are ignored in single-method modes.

Unauthenticated paths

The health endpoints /livez, /readyz, and /startupz are always served without authentication, as is /dapr/subscribe, which only tells the sidecar the server has no subscriptions. Every other path is MCP and needs a token. There is no setting to exempt more paths.

Related links

• Configuration reference
• MCP security posture

4 - Dapr MCP server tool reference

The Dapr MCP server exposes 17 tools. Three are always registered. The rest are registered only while the sidecar has at least one component of the matching type, so an agent never sees tools it can’t use.

The schema the server sends when a client connects is the authoritative definition of each tool. This page is a readable summary of it.

Call get_components first

Component-specific tools take a component name as input, such as storeName or pubsubName. An agent should call get_components first to learn the names that exist, rather than guess. The server’s instructions to the model say the same thing, and tell it to pass metadata fields as JSON objects ({}), never as strings ("{}").

Safety properties

Each tool carries the MCP annotations readOnlyHint, destructiveHint, and idempotentHint, which MCP clients can use to decide whether to ask a person before a call. The tables below show them as:

• Read-only: reads data and changes nothing.
• Idempotent: calling it again with the same inputs has no further effect, so it is safe to retry.
• Destructive: may delete or overwrite data, or trigger an action that can’t be undone. Consider asking a person to confirm the first call.
• Side effect: changes state or triggers an action somewhere.

Every tool except get_components also sets openWorldHint, because it reaches systems outside the server.

Tools at a glance

Tools follow the components loaded in the sidecar. When component hot reloading adds the first component of a type, the server registers that type’s tools the next time a client lists tools or calls get_components, and notifies connected clients that the tool list changed. When the last one is removed, its tools are removed too. Clients that read the tool list only once need to reconnect to see the change.

A tool that fails, because an input is missing or the sidecar returns an error, returns a result marked as an error with a message the model can read, rather than failing the MCP request.

Metadata

get_components

Lists the components loaded in the sidecar, with each one’s name, type, version, and capabilities. Only component types the server has tools for are listed. The list is read live from the sidecar on every call.

Inputs: none.

Service invocation

invoke_service

Calls a method on another Dapr app through service invocation and returns the response body.

Actors

invoke_actor_method

Calls a method on a virtual actor and returns its response.

State management

save_state

Saves one key-value pair to a state store.

get_state

Reads the value of one key. Reports found: false when the key doesn’t exist.

delete_state

Deletes one key.

execute_transaction

Runs several saves and deletes as one atomic transaction. The state store must support transactions.

Publish and subscribe

publish_event

Publishes a message to a topic on a pub/sub component.

publish_event_with_metadata

Same as publish_event, with publish metadata such as ttlInSeconds.

Bindings

invoke_output_binding

Invokes an operation on an output binding, such as an HTTP endpoint, a queue, or object storage, and returns the response.

Secrets

Secret values are returned to the model in the tool result. Expose only secret stores the agent should read, and narrow them with secret scopes.

get_secret

Reads one secret from a secret store.

get_bulk_secrets

Reads every secret the app can access in a secret store. The tool description tells the model to use it only when the user explicitly asks for all secrets.

Conversation

converse_with_llm

Sends a prompt to another LLM through a conversation component and returns the reply, along with a context_id to continue the conversation.

Cryptography

encrypt_data

Encrypts text with a key held by a cryptography component and returns the cipher text, base64-encoded.

decrypt_data

Decrypts cipher text produced by encrypt_data and returns the plain text.

Distributed lock

Always pair acquire_lock with release_lock, and set an expiry so a lock isn’t held forever if the agent stops.

acquire_lock

Tries to acquire a distributed lock on a resource. If another owner holds it, the call succeeds with lock_acquired: false.

release_lock

Releases a lock. Fails if the lock doesn’t exist or belongs to a different owner.

5 - Dapr MCP server observability

The Dapr MCP server exports traces, metrics, and logs over the OpenTelemetry Protocol (OTLP), and serves health endpoints for probes when it runs over HTTP.

Turn on telemetry

Telemetry is off until you set an OTLP endpoint. Point the server at an OpenTelemetry Collector, or any backend that accepts OTLP:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=dapr-mcp-server
dapr run --app-id dapr-mcp-server --resources-path ./components -- dapr-mcp-server --http localhost:8080

An endpoint without a scheme, such as otel-collector:4317, uses TLS. Add OTEL_EXPORTER_OTLP_INSECURE=true to send plaintext to an endpoint like that, or give the scheme explicitly. To use OTLP over HTTP instead of gRPC, set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf and use the HTTP port, usually 4318.

All three signals go to the same endpoint unless you override one with its OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_* variables. See the configuration reference for every setting. If the exporters can’t be set up, the server logs a warning and keeps running without telemetry.

For a collector to receive the data, see Using OpenTelemetry Collector.

Traces

The server creates:

• A server span for each HTTP request, named after the method and route, for example POST /. It continues the caller’s trace when the request carries a W3C traceparent header.
• A span for each tool call, named after the tool, for example save_state. It has the attributes mcp.tool.name, mcp.tool.package, and, where the tool targets a component, dapr.component.name, plus details such as the state key or topic. Failed calls are marked with an error status.

The tool span’s trace context is passed to the Dapr sidecar with each gRPC call, so spans from the sidecar, and from any app it calls, join the same trace when Dapr tracing exports to the same backend.

Metrics

Metrics are exported every 10 seconds by default (OTEL_METRIC_EXPORT_INTERVAL). Set DAPR_MCP_SERVER_METRICS_ENABLED=false to turn them off while keeping traces.

Tool metrics carry only bounded attributes: tool.name and tool.package, plus outcome (success or error) on the invocation and duration metrics and error.type on the error counter. Values the agent supplies, such as component names, app IDs, and actor types, are kept off metrics and recorded on the tool’s span instead. HTTP metrics carry http.request.method, http.response.status_code, and http.route. The HTTP metrics cover MCP requests only, not the health endpoints.

Logs

The server writes structured JSON logs to stderr, never stdout, so logs can’t corrupt the stdio transport. Every record includes the service name and version. Set the level with DAPR_MCP_SERVER_LOG_LEVEL (debug, info, warn, or error; default info).

When an OTLP endpoint is set, the same records are also exported as OpenTelemetry logs, correlated with the active trace. Set DAPR_MCP_SERVER_LOGS_OTEL_ENABLED=false to keep logs on stderr only.

At debug level the server logs incoming request headers, with Authorization, Cookie, X-Api-Key, and the configured token header redacted. Each successful tool call is logged at info, and each failure at warn, with its target, such as the store name and key, but never with payloads or secret values.

Health endpoints

With --http, the server serves three endpoints on the same address as MCP. They never require authentication, and each returns JSON with a status of healthy or unhealthy and the server version.

{
  "status": "healthy",
  "checks": [
    { "status": "healthy", "component": "dapr", "message": "sidecar connected", "latency": "1.2ms" }
  ],
  "version": "v0.0.1"
}

On SIGTERM or SIGINT, /readyz starts returning 503, open server-sent event streams are closed, and in-flight requests get up to 15 seconds to finish before the server exits.

The --health-check flag runs the same liveness check from the command line. It requests /livez on the address from --health-check-addr, or from --http, or localhost:8080, and exits with 0 or 1. The container image uses it as its HEALTHCHECK.

Over stdio there is no HTTP listener, so these endpoints aren’t available.