# Dapr Mcp

> MCP Server for Dapr APIs

- **Type:** MCP server
- **Install:** `agentstack add mcp-caspergn-dapr-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CasperGN](https://agentstack.voostack.com/s/caspergn)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [CasperGN](https://github.com/CasperGN)
- **Source:** https://github.com/CasperGN/dapr-mcp

## Install

```sh
agentstack add mcp-caspergn-dapr-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

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

### From Release

Download pre-built binaries from the [Releases](https://github.com/dapr/dapr-mcp-server/releases) page.

### Docker

```bash
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:
```bash
dapr init
```

2. Run the MCP server:
```bash
dapr run --app-id dapr-mcp-server --resources-path components -- dapr-mcp-server --http localhost:8080
```

3. Connect your AI agent to `http://localhost:8080`

## Tool Status

| Category | Tool | Status | Notes |
|----------|------|--------|-------|
| actors | invoke_actor_method | Beta | Virtual actor method invocation |
| bindings | invoke_output_binding | Stable | External system interactions |
| conversation | converse_with_llm | Stable | Delegate to external LLMs |
| crypto | encrypt_data | Experimental | May be blocked by some models |
| crypto | decrypt_data | Experimental | May be blocked by some models |
| invoke | invoke_service | Beta | Service-to-service calls |
| lock | acquire_lock | Stable | Distributed locking |
| lock | release_lock | Stable | Distributed locking |
| metadata | get_components | Stable | Component discovery |
| pubsub | publish_event | Stable | Event publishing |
| pubsub | publish_event_with_metadata | Stable | Event publishing with headers |
| secrets | get_secret | Stable | Single secret retrieval |
| secrets | get_bulk_secrets | Stable | Bulk secret retrieval |
| state | save_state | Stable | State persistence |
| state | get_state | Stable | State retrieval |
| state | delete_state | 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

```bash
# 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)

```bash
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

```bash
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:

```bash
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):

```bash
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`:

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

### Claude Desktop

Add to your Claude Desktop configuration:

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

## Development

### Prerequisites

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

### Building

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

### Testing

```bash
go test -v -race ./...
```

### Linting

```bash
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](https://github.com/CasperGN)
- **Source:** [CasperGN/dapr-mcp](https://github.com/CasperGN/dapr-mcp)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-caspergn-dapr-mcp
- Seller: https://agentstack.voostack.com/s/caspergn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.