Linkerd2 MCP

> ⚠️ This project is a Work In Progress (WIP) and is still under active development. Features and APIs may change at any time.
>
> ℹ️ The vast majority of this project has been built with the help of AI agents.

This project aims to expose a Model Context Protocol (MCP) server, enabling you to "talk" to your Linkerd2 service mesh. By building on top of Linkerd and Linkerd-viz, it provides an API for fetching high-level aggregated mesh data and for making changes—such as applying authorization policy updates—directly to your mesh.

A lightweight, fault-tolerant control plane for Linkerd-powered service meshes, exposing a gRPC MCP API for mesh introspection and safe policy mutation.

Project Structure

cmd/
  mcp-server/      → main.go (MCP API server)
  collector/       → main.go (Collector)
proto/             → *.proto + buf.yaml (gRPC contracts)
internal/
  graph/           → in-memory mesh model
  redis/           → Redis helpers (snapshot, delta, election)
docs/              → project docs
helm/              → chart/
Makefile           → convenience commands

Getting Started

Prerequisites

- Go 1.22+
- Docker or Podman
- kubectl 1.30+
- kind (for local k8s)
- Linkerd CLI 2.15+
- Prometheus (comes with Linkerd viz)
- Buf CLI 1.29+
- Helm 3.14+

Build

go build -o bin/collector ./cmd/collector
go build -o bin/mcp-server ./cmd/mcp-server

Running End-to-End (local kind cluster)

1. Start a kind cluster and install Linkerd + Prometheus:

   kind create cluster --name mcp-dev

   linkerd install | kubectl apply -f -

   linkerd viz install | kubectl apply -f -

   linkerd check

   

2. Deploy Redis (Valkey) and the MCP stack (see helm/ for chart):

   helm install mcp ./helm --namespace mcp --create-namespace --set redis.enabled=true

   

3. Port-forward MCP server and test the gRPC API:

   kubectl -n mcp port-forward svc/mcp 10900:10900

   grpcurl -plaintext localhost:10900 mcp.v1.MeshContext/GetMeshGraph

   

4. Apply a policy mutation via gRPC:

   grpcurl -plaintext -d '{"namespace":"default","name":"allow-foo","json_spec":"{\"foo\": \"bar\"}"}' localhost:10900 mcp.v1.MeshContext/ApplyAuthorizationPolicy

   

5. Verify AuthorizationPolicy CRs in the cluster:

   kubectl get authorizationpolicies.policy.linkerd.io -A

   

Development Workflow

- Edit proto contracts in proto/, run buf lint
- Implement business logic in cmd/ and internal/
- Use kind and helm for local testing
- Run unit tests: go test ./...
- See docs/progress.md for current status and next steps

Roadmap

- Integration testing and error handling
- Helm chart, CI/CD, documentation
- E2E tests and further enhancements

License

Apache 2.0