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

Configuration

Environment Variables

Core Configuration

OpenTelemetry Configuration

Authentication Configuration

OIDC Configuration

SPIFFE Configuration

Dapr Sentry Configuration

Health Endpoints

Kubernetes-compatible health endpoints:

OpenTelemetry

Metrics

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 for details.