mesh

MCP Mesh provides a single secure endpoint to route and manage MCP traffic between clients (like Cursor, Claude, Windsurf, VS Code, and custom agents) and your MCP servers. It offers authentication, access control, observability, and policy enforcement at a centralized control plane, while exposing flexible runtime strategies as Virtual MCPs to tailor tool access per workflow. With Mesh you get RBAC, auditing, and OpenTelemetry tracing across all tool interactions, plus the ability to compose multiple tool surfaces into governed MCP endpoints. Use it to simplify client configurations and gain visibility over tool usage, costs, and errors across your MCP ecosystem.

To get started, you can run Mesh locally or deploy it in Docker, Bun/Node, Kubernetes, or other environments. The Quick Start outlines how to launch Mesh quickly and verify it is serving both the client-facing UI and the API proxy. Once running, you can explore Virtual MCPs to expose curated toolsets, configure AccessControl for workspace/project scopes, and connect your MCP servers behind the secure Mesh proxy for unified routing and auditing.

Prerequisites

• Node.js and/or Bun installed on your system (Mesh is designed to run with Bun or Node environments)
• Git installed
• Optional: Docker if you plan to deploy with Docker Compose

Installation steps

1. Clone the repository and install dependencies

git clone https://github.com/decocms/mesh.git
cd mesh
bun install

2. Run the development server locally (client + API)

bun run dev

This will start the client UI and the API server. By default, you can access the client at http://localhost:3000.

3) Alternatively, run via npx (instant Mesh instance)
```bash
npx @decocms/mesh

4. Deploy options

• Docker Compose (SQLite):

docker compose -f deploy/docker-compose.yml up

• Docker Compose (PostgreSQL):

docker compose -f deploy/docker-compose.postgres.yml up

• Self-host with Bun (build and start):

bun run build:client && bun run build:server
bun run start

• Kubernetes: apply the manifests in k8s/ directory

kubectl apply -f k8s/

Prerequisites noted above may vary slightly based on your environment; consult the docs for any environment-specific steps.

Notes and tips:

• If you enable worktrees for multi-tenant development, Mesh will route each workspace to its own subdomain, allowing isolated RBAC and policy auditing per workspace.
• When using Virtual MCPs, you can add new strategies or toolsets without redeploying the entire Mesh stack.
• Ensure OpenTelemetry is enabled in your deployment to collect traces and metrics across tool calls, workflows, and the UI.
• For persistent storage, configure the Storage Adapter (SQLite, Postgres, etc.) per your deployment (default is SQLite for local/dev).
• Common issues: port conflicts when running client and API separately; use worktree mode or adjust ports as needed. Review logs for authentication and token vault errors if you see access issues.
• Environment variables you may encounter include RBAC settings, workspace/project identifiers, and token vault configuration; these should be defined per your deployment environment.