Dapr MCP server on Dapr Docs

Getting started with the Dapr MCP server

Mon, 01 Jan 0001 00:00:00 +0000

This guide installs the Dapr MCP server, runs it next to a Dapr sidecar with two in-memory components, and connects an MCP client to it.

Prerequisites

Dapr CLI, with Dapr initialized in self-hosted mode
An MCP client, such as Claude Desktop, Cursor, or Claude Code

Step 1: Install the server

Pick one of the following.

Each GitHub release publishes a binary per platform, named dapr-mcp-server-<os>-<arch>, with a checksums.txt file. Builds are available for linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, and windows-amd64 (with an .exe suffix).

Dapr MCP server configuration reference

Mon, 01 Jan 0001 00:00:00 +0000

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

Flag	Default	Description
`--http <addr>`	Not set (stdio)	Serve streamable HTTP on this address, for example `localhost:8080` or `0.0.0.0:8080`, instead of stdio. The health endpoints are served on the same address.
`--version`	`false`	Print the version and exit.
`--health-check`	`false`	Request `/livez` from a running server and exit with `0` on a `200` response, `1` otherwise. The container image uses this for its `HEALTHCHECK`.
`--health-check-addr <host:port>`	From `--http`, else `localhost:8080`	Address that `--health-check` probes. A wildcard host such as `0.0.0.0` is probed as `localhost`.

Server and Dapr connection

Variable	Default	Description
`DAPR_GRPC_PORT`	`50001`	Port of the Dapr sidecar’s gRPC API on `127.0.0.1`. `dapr run` and the Kubernetes sidecar injector set this for you.
`DAPR_GRPC_ENDPOINT`	Not set	Full address of the sidecar’s gRPC API. Takes precedence over `DAPR_GRPC_PORT`.
`DAPR_API_TOKEN`	Not set	Token sent to the sidecar when it requires API token authentication.
`DAPR_CLIENT_TIMEOUT_SECONDS`	`5`	Timeout for each attempt to connect to the sidecar. The server makes up to five attempts, two seconds apart, then exits.
`DAPR_MCP_SERVER_LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, or `error`. Logs are JSON on stderr. At `debug`, request headers are logged with credential headers redacted.

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

Authenticating clients of the Dapr MCP server

Mon, 01 Jan 0001 00:00:00 +0000

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:

`AUTH_MODE`	Accepts
Not set, or `disabled`	Any request. Use only on `localhost`.
`oidc`	ID or access tokens (JWTs) from an OpenID Connect provider
`spiffe`	SPIFFE JWT-SVIDs, validated with trust bundles from the SPIFFE Workload API
`dapr-sentry`	JWTs issued by Dapr Sentry for a Dapr app
`hybrid`	Any combination of the three above

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.

Dapr MCP server tool reference

Mon, 01 Jan 0001 00:00:00 +0000

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 ("{}").

Dapr MCP server observability

Mon, 01 Jan 0001 00:00:00 +0000

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.

Dapr MCP server on Dapr Docs

Getting started with the Dapr MCP server

Prerequisites

Step 1: Install the server

Dapr MCP server configuration reference

Command-line flags

Server and Dapr connection

Authenticating clients of the Dapr MCP server

Dapr MCP server tool reference

Call get_components first

Dapr MCP server observability

Turn on telemetry

Call `get_components` first