Dapr Mcp

dapr-mcp

A Model Context Protocol (MCP) server that exposes Dapr's microservices building blocks as tools for AI agents.

Overview

dapr-mcp bridges AI agents with Dapr's powerful microservices APIs, enabling:

• State Management: Save, retrieve, and delete state with transactional support
• Pub/Sub Messaging: Publish events to message brokers
• Service Invocation: Call other Dapr-enabled services
• Secrets Management: Securely access secrets from configured stores
• Distributed Locking: Coordinate access to shared resources
• Bindings: Interact with external systems (databases, queues, etc.)
• Conversation AI: Delegate tasks to external LLMs via Dapr
• Cryptography: Encrypt and decrypt sensitive data

Features

• Full OpenTelemetry observability (traces, metrics, logs)
• OAuth2.0/OIDC and SPIFFE authentication support
• Kubernetes-ready health endpoints
• Dynamic component discovery
• Comprehensive safety rules for AI agents

Installation

From Source

go install github.com/dapr/dapr-mcp-server/cmd/dapr-mcp-server@latest

From Release

Download pre-built binaries from the Releases page.

Docker

docker pull ghcr.io/dapr/dapr-mcp-server:latest
docker run -p 8080:8080 ghcr.io/dapr/dapr-mcp-server:latest

Quick Start

1. Initialize Dapr:

dapr init

1. Run the MCP server:

dapr run --app-id dapr-mcp-server --resources-path components -- dapr-mcp-server --http localhost:8080

1. Connect your AI agent to http://localhost:8080

Tool Status

| Category | Tool | Status | Notes | |----------|------|--------|-------| | actors | invokeactormethod | Beta | Virtual actor method invocation | | bindings | invokeoutputbinding | Stable | External system interactions | | conversation | conversewithllm | Stable | Delegate to external LLMs | | crypto | encryptdata | Experimental | May be blocked by some models | | crypto | decryptdata | Experimental | May be blocked by some models | | invoke | invokeservice | Beta | Service-to-service calls | | lock | acquirelock | Stable | Distributed locking | | lock | releaselock | Stable | Distributed locking | | metadata | getcomponents | Stable | Component discovery | | pubsub | publishevent | Stable | Event publishing | | pubsub | publisheventwithmetadata | Stable | Event publishing with headers | | secrets | getsecret | Stable | Single secret retrieval | | secrets | getbulksecrets | Stable | Bulk secret retrieval | | state | savestate | Stable | State persistence | | state | getstate | Stable | State retrieval | | state | deletestate | Stable | State deletion | | state | execute_transaction | Stable | Atomic state operations |

Configuration

Environment Variables

Core Configuration

| Variable | Description | Default | |----------|-------------|---------| | DAPR_MCP_SERVER_LOG_LEVEL | Log level: DEBUG, INFO, WARN, ERROR | INFO |

OpenTelemetry Configuration

| Variable | Description | Default | |----------|-------------|---------| | OTEL_EXPORTER_OTLP_ENDPOINT | OTLP endpoint for all signals | (none - disabled) | | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Override for traces endpoint | uses OTEL_EXPORTER_OTLP_ENDPOINT | | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Override for metrics endpoint | uses OTEL_EXPORTER_OTLP_ENDPOINT | | OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Override for logs endpoint | uses OTEL_EXPORTER_OTLP_ENDPOINT | | OTEL_EXPORTER_OTLP_PROTOCOL | Protocol: grpc, http/protobuf | grpc | | OTEL_EXPORTER_OTLP_HEADERS | Headers (key=value,key2=value2) | (none) | | OTEL_SERVICE_NAME | Service name for telemetry | dapr-mcp-server | | OTEL_SERVICE_VERSION | Service version | v1.0.0 | | DAPR_MCP_SERVER_METRICS_ENABLED | Enable metrics export | true | | DAPR_MCP_SERVER_LOGS_OTEL_ENABLED | Export logs via OTEL | true |

Authentication Configuration

| Variable | Description | Default | |----------|-------------|---------| | AUTH_ENABLED | Enable authentication | false | | AUTH_MODE | Mode: disabled, oidc, spiffe, dapr-sentry, hybrid | disabled | | AUTH_SKIP_PATHS | Paths to skip auth (comma-separated) | /livez,/readyz,/startupz |

OIDC Configuration

| Variable | Description | Default | |----------|-------------|---------| | OIDC_ENABLED | Enable OIDC authentication | false | | OIDC_ISSUER_URL | OIDC provider URL | (required if OIDC enabled) | | OIDC_CLIENT_ID | Expected audience (aud claim) | (required if OIDC enabled) | | OIDC_ALLOWED_ALGORITHMS | Allowed signing algorithms | RS256,ES256 | | OIDC_SKIP_ISSUER_CHECK | Skip issuer validation (dev only) | false |

SPIFFE Configuration

| Variable | Description | Default | |----------|-------------|---------| | SPIFFE_ENABLED | Enable SPIFFE authentication | false | | SPIFFE_TRUST_DOMAIN | SPIFFE trust domain | (required if SPIFFE enabled) | | SPIFFE_SERVER_ID | This server's SPIFFE ID | (required if SPIFFE enabled) | | SPIFFE_ENDPOINT_SOCKET | Workload API socket path | SPIFFE_ENDPOINT_SOCKET env | | SPIFFE_ALLOWED_CLIENTS | Allowed client SPIFFE IDs | (none - all allowed) |

Dapr Sentry Configuration

| Variable | Description | Default | |----------|-------------|---------| | DAPR_SENTRY_ENABLED | Enable Dapr Sentry authentication | false | | DAPR_SENTRY_JWKS_URL | Dapr Sentry JWKS endpoint | (required if enabled) | | DAPR_SENTRY_TRUST_DOMAIN | Expected SPIFFE trust domain | (required if enabled) | | DAPR_SENTRY_AUDIENCE | Expected audience claim | (none - not validated) | | DAPR_SENTRY_TOKEN_HEADER | Header containing the JWT | Authorization | | DAPR_SENTRY_JWKS_REFRESH_INTERVAL | JWKS cache refresh interval | 5m |

Health Endpoints

Kubernetes-compatible health endpoints:

| Endpoint | Purpose | |----------|---------| | GET /livez | Liveness probe - server is running | | GET /readyz | Readiness probe - server can accept traffic | | GET /startupz | Startup probe - initialization complete |

OpenTelemetry

Metrics

| Metric | Type | Description | |--------|------|-------------| | dapr-mcp-server.tool.invocations | Counter | Total tool invocations | | dapr-mcp-server.tool.errors | Counter | Failed tool invocations | | dapr-mcp-server.tool.duration | Histogram | Execution time (ms) | | dapr-mcp-server.tool.in_progress | UpDownCounter | Currently executing tools |

Span Attributes

Each tool span includes:

• tool.name: The tool being invoked
• tool.package: The package containing the tool
• dapr.operation: Dapr operation type
• dapr.component.type: Component type being used
• outcome: success or error

Example: Jaeger Setup

# Start Jaeger
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Configure dapr-mcp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Run server
dapr run --app-id dapr-mcp-server --resources-path components -- dapr-mcp-server --http localhost:8080

Authentication Setup

OIDC (OAuth2.0)

export AUTH_ENABLED=true
export AUTH_MODE=oidc
export OIDC_ENABLED=true
export OIDC_ISSUER_URL=https://accounts.google.com
export OIDC_CLIENT_ID=your-client-id

SPIFFE

export AUTH_ENABLED=true
export AUTH_MODE=spiffe
export SPIFFE_ENABLED=true
export SPIFFE_TRUST_DOMAIN=example.org
export SPIFFE_SERVER_ID=spiffe://example.org/dapr-mcp
export SPIFFE_ENDPOINT_SOCKET=unix:///tmp/spire-agent/public/api.sock

Dapr Sentry

For Dapr environments using Sentry without full SPIRE infrastructure:

export AUTH_ENABLED=true
export AUTH_MODE=dapr-sentry
export DAPR_SENTRY_ENABLED=true
export DAPR_SENTRY_JWKS_URL=http://dapr-sentry:8080/jwks.json
export DAPR_SENTRY_TRUST_DOMAIN=public
export DAPR_SENTRY_AUDIENCE=public  # Optional

Note: Dapr Sentry JWTs have SPIFFE IDs in the sub claim but no iss claim, which is why they require this dedicated authenticator instead of OIDC.

Hybrid Mode

Accept multiple authentication methods (OIDC, SPIFFE, and/or Dapr Sentry):

export AUTH_ENABLED=true
export AUTH_MODE=hybrid
export OIDC_ENABLED=true
export OIDC_ISSUER_URL=https://accounts.google.com
export OIDC_CLIENT_ID=your-client-id
export SPIFFE_ENABLED=true
export SPIFFE_TRUST_DOMAIN=example.org
export SPIFFE_SERVER_ID=spiffe://example.org/dapr-mcp
# Optionally add Dapr Sentry as well:
# export DAPR_SENTRY_ENABLED=true
# export DAPR_SENTRY_JWKS_URL=http://dapr-sentry:8080/jwks.json
# export DAPR_SENTRY_TRUST_DOMAIN=public

IDE Integration

VS Code

Add .vscode/mcp.json:

{
  "servers": {
    "dapr-mcp": {
      "type": "http",
      "url": "http://localhost:8080"
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "dapr-mcp": {
      "url": "http://localhost:8080"
    }
  }
}

Development

Prerequisites

• Go 1.21+
• Dapr CLI
• Docker (optional, for local testing)

Building

go build -o dapr-mcp-server ./cmd/dapr-mcp-server

Testing

go test -v -race ./...

Linting

golangci-lint run

Architecture

cmd/dapr-mcp-server/          # Main entry point
pkg/
  actors/             # Virtual actor tools
  auth/               # Authentication (OIDC, SPIFFE)
  bindings/           # Output binding tools
  conversation/       # LLM conversation tools
  crypto/             # Encryption/decryption tools
  health/             # Health check endpoints
  invoke/             # Service invocation tools
  lock/               # Distributed lock tools
  metadata/           # Component discovery
  mocks/              # Test mocks
  pubsub/             # Pub/Sub tools
  secrets/            # Secret management tools
  state/              # State management tools
  telemetry/          # OTEL instrumentation

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run golangci-lint run and go test ./...
5. Submit a pull request

License

Apache 2.0 - See [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CasperGN
• Source: CasperGN/dapr-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.