MCP Mesh

What is MCP Mesh about?

MCP Mesh acts as a control plane that sits between MCP clients (such as Cursor, Claude, VS Code, or custom agents) and MCP servers (Salesforce, Slack, GitHub, Postgres, etc.). It consolidates multiple client‑to‑server integrations into a single governed endpoint, handling authentication, policy enforcement, audit logging, and OpenTelemetry tracing.

How to use MCP Mesh?

1. Installation – Clone the repo or run the one‑liner:

   npx @decocms/mesh
   

   This starts a local instance with both the admin UI and the API server.
2. Local Development – After cloning:

   git clone https://github.com/decocms/mesh.git
   bun install
   bun run dev   # launches UI (http://localhost:3000) and API
   

3. Docker / Kubernetes – Use the provided docker-compose.yml for SQLite or PostgreSQL, or apply the manifests in k8s/ for a cluster deployment.
4. Define Tools – Use the defineTool() helper to create typed, auditable MCP tools. Each tool automatically gets input validation, access‑control checks, audit logs, and OpenTelemetry traces.
5. Configure Runtime Strategies – Choose a gateway strategy (full‑context, smart selection, sandboxed code execution) to control how tools are exposed to models.

Key Features of MCP Mesh

• Unified Endpoint – One secure URL for all MCP traffic.
• Fine‑grained RBAC – OAuth 2.1 and API‑key based access control per workspace/project.
• Multi‑tenancy – Isolated configs, credentials, policies, and logs.
• OpenTelemetry Integration – Traces, metrics, and cost analytics for every tool call.
• Pluggable Storage – Kysely ORM with SQLite or PostgreSQL adapters.
• Proxy Layer & Token Vault – Secure bridge to remote MCP servers.
• Virtual MCPs – Compose governed toolsets as new logical MCP servers.
• Event Bus – Pub/sub with at‑least‑once delivery and cron scheduling.
• Extensible Runtime Strategies – Different gateway modes for performance or security.
• Full‑stack Stack – Hono API, Vite/React UI, Tailwind, shadcn components.

Use Cases of MCP Mesh

• Enterprise Integration Hub – Replace dozens of custom client‑to‑server connectors with a single managed gateway.
• Security‑Focused AI Tooling – Enforce policies and audit logs for AI agents calling internal services.
• Cost‑Control for LLM‑Powered Tools – Trace API usage and set spend caps via OpenTelemetry metrics.
• Multi‑tenant SaaS Platforms – Provide each customer its own isolated workspace with separate credentials and policies.
• Developer Experience – Centralize tool definitions, version them, and expose them to any MCP‑compatible editor or IDE.

FAQ from the MCP Mesh

Q: Do I need Docker to run MCP Mesh? A: No. You can run it directly with Bun/Node (bun run dev or npx @decocms/mesh). Docker and Kubernetes options are provided for production deployments.

Q: How does authentication work? A: Better Auth supplies OAuth 2.1 flows and API‑key generation per workspace/project, with token vault encryption for stored secrets.

Q: Can I add my own storage backend? A: Yes. The storage layer uses Kysely, so you can swap SQLite, PostgreSQL, or any supported SQL dialect.

Q: Is MCP Mesh open‑source? A: Yes, under a Sustainable Use License (SUL). Free for internal/self‑hosted use; commercial SaaS requires a paid license.

Q: How do I expose a new tool to agents? A: Create a file using defineTool() with Zod schemas for input/output, implement the handler, and the framework automatically registers the tool with RBAC and observability.

TL;DR:

• Route all MCP traffic through a single governed endpoint
• Enforce RBAC, policies, and audit trails at the control plane
• Full observability with OpenTelemetry — traces, costs, errors
• Runtime strategies as gateways for optimal tool selection
• Self-host with Docker, Bun/Node, Kubernetes, or run locally

---

What is an MCP Mesh?

MCP Mesh is an open-source control plane for MCP traffic. It sits between your MCP clients (Cursor, Claude, Windsurf, VS Code, custom agents) and your MCP servers, providing a unified layer for auth, routing and observability.

It replaces M×N integrations (M MCP servers × N clients) with one production endpoint, so you stop maintaining separate configs in every client. Built for multi-tenant orgs: workspace/project scoping for policies, credentials, and logs.

┌─────────────────────────────────────────────────────────────────┐
│                         MCP Clients                             │
│         Cursor · Claude · VS Code · Custom Agents               │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                         MCP MESH                                │
│       Gateway · Policy Engine · Observability · Token Vault     │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                       MCP Servers                               │
│      Salesforce · Slack · GitHub · Postgres · Your APIs         │
└─────────────────────────────────────────────────────────────────┘

---

Quick Start

# Clone and install
git clone https://github.com/decocms/mesh.git
bun install

# Run locally (client + API server)
bun run dev

→ runs at http://localhost:3000 (client) + API server

Or use npx @decocms/mesh to instantly get a mesh running.

---

Runtime strategies as gateways

As tool surfaces grow, “send every tool definition to the model on every call” gets expensive and slow. The mesh models runtime strategies as gateways: one endpoint, different ways of exposing tools.

Examples:

• Full-context: expose everything (simple and deterministic for small toolsets)
• Smart selection: narrow the toolset before execution
• Code execution: load tools on demand and run code in a sandbox

Gateways are configurable and extensible. You can add new strategies and also curate toolsets (see Virtual MCPs).

---

Core Capabilities

Capability	What it does
MeshContext	Unified runtime interface providing auth, storage, observability, and policy control
defineTool()	Declarative API for typed, auditable, observable MCP tools
AccessControl	Fine-grained RBAC via Better Auth — OAuth 2.1 + API keys per workspace/project
Multi-tenancy	Workspace/project isolation for config, credentials, policies, and audit logs
OpenTelemetry	Full tracing and metrics for tools, workflows, and UI interactions
Storage Adapters	Kysely ORM → SQLite / Postgres, easily swapped
Proxy Layer	Secure bridge to remote MCP servers with token vault + OAuth
Virtual MCPs	Compose and expose governed toolsets as new MCP servers
Event Bus	Pub/sub between connections with scheduled/cron delivery and at-least-once guarantees
Bindings	Capability contracts (ex.: agents, workflows, views) so apps target interfaces instead of specific MCP implementations

---

Define Tools

Tools are first-class citizens. Type-safe, audited, observable, and callable via MCP.

import { z } from "zod";
import { defineTool } from "~/core/define-tool";

export const CONNECTION_CREATE = defineTool({
  name: "CONNECTION_CREATE",
  description: "Create a new MCP connection",
  inputSchema: z.object({
    name: z.string(),
    connection: z.object({
      type: z.enum(["HTTP", "SSE", "WebSocket"]),
      url: z.string().url(),
      token: z.string().optional(),
    }),
  }),
  outputSchema: z.object({
    id: z.string(),
    scope: z.enum(["workspace", "project"]),
  }),
  handler: async (input, ctx) => {
    await ctx.access.check();
    const conn = await ctx.storage.connections.create({
      projectId: ctx.project?.id ?? null,
      ...input,
      createdById: ctx.auth.user!.id,
    });
    return { id: conn.id, scope: conn.projectId ? "project" : "workspace" };
  },
});

Every tool call automatically gets: input/output validation, access control checks, audit logging, and OpenTelemetry traces.

---

Project Structure

├── apps/
│   ├── mesh/                # Full-stack MCP Mesh (Hono API + Vite/React)
│   │   ├── src/
│   │   │   ├── api/         # Hono HTTP + MCP proxy routes
│   │   │   ├── auth/        # Better Auth (OAuth + API keys)
│   │   │   ├── core/        # MeshContext, AccessControl, defineTool
│   │   │   ├── tools/       # Built-in MCP management tools
│   │   │   ├── storage/     # Kysely DB adapters
│   │   │   ├── event-bus/   # Pub/sub event delivery system
│   │   │   ├── encryption/  # Token vault & credential management
│   │   │   ├── observability/  # OpenTelemetry tracing & metrics
│   │   │   └── web/         # React 19 admin UI
│   │   └── migrations/      # Kysely database migrations
│   └── docs/                # Astro documentation site
│
└── packages/
    ├── bindings/            # Core MCP bindings and connection abstractions
    ├── runtime/             # MCP proxy, OAuth, and runtime utilities
    ├── ui/                  # Shared React components (shadcn-based)
    ├── cli/                 # CLI tooling (deco commands)
    ├── create-deco/         # Project scaffolding (npm create deco)
    └── vite-plugin-deco/    # Vite plugin for Deco projects

---

Development

# Install dependencies
bun install

# Run dev server (client + API)
bun run dev

# Run tests
bun test

# Type check
bun run check

# Lint
bun run lint

# Format
bun run fmt

Mesh-specific commands (from apps/mesh/)

bun run dev:client     # Vite dev server (port 4000)
bun run dev:server     # Hono server with hot reload
bun run migrate        # Run database migrations

---

Deploy Anywhere

# 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
bun run build:client && bun run build:server
bun run start

# Kubernetes
kubectl apply -f k8s/

Runs on any infrastructure — Docker, Kubernetes, AWS, GCP, or local Bun/Node runtimes. No vendor lock-in.

---

Tech Stack

Layer	Tech
Runtime	Bun / Node
Language	TypeScript + Zod
Framework	Hono (API) + Vite + React 19
Database	Kysely → SQLite / PostgreSQL
Auth	Better Auth (OAuth 2.1 + API keys)
Observability	OpenTelemetry
UI	React 19 + Tailwind v4 + shadcn
Protocol	Model Context Protocol (MCP)

---

Roadmap

• Multi-tenant admin dashboard
• MCP bindings (swap providers without rewrites)
• Version history for mesh configs
• NPM package runtime
• Edge debugger / live tracing
• Cost analytics and spend caps
• MCP Store — discover and install pre-built MCP apps

---

Part of deco CMS

The MCP Mesh is the infrastructure layer of decoCMS.

Layer	What it does
MCP Mesh	Connect, govern, and observe MCP traffic
MCP Studio (coming soon)	Package durable MCP capabilities into shareable apps (SDK + no-code admin)
MCP Store (coming soon)	Discover, install (and eventually monetize) pre-built MCP apps.

---

License

The MCP Mesh ships with a Sustainable Use License (SUL). See LICENSE.md.

• ✅ Free to self-host for internal use
• ✅ Free for client projects (agencies, SIs)
• ⚠️ Commercial license required for SaaS or revenue-generating production systems

Questions? contact@decocms.com

---

Contributing

We welcome contributions! Run the following before submitting a PR:

bun run fmt      # Format code
bun run lint     # Check linting
bun test         # Run tests

See AGENTS.md for detailed coding guidelines and conventions.

---