MCP Depot Documentation

MCP Depot is a self-hosted hub that lets any MCP-compatible AI assistant (Claude, OpenCode, Cursor, Zed) connect to all your tools through a single endpoint - running entirely on your own infrastructure.

Installation

MCP Depot supports three deployment options. Choose the one that fits your setup:

• npm — zero config, single command, SQLite, ideal for personal use
• Docker Compose — recommended for teams, PostgreSQL included
• Kubernetes (Helm) — production-grade, scalable, ingress-ready

Option 1 — npm

Prerequisites: Node.js 18+. No Docker required. Data stored in SQLite — ideal for personal use.

npx mcp-depot

Opens the admin UI at http://localhost:3000. Admin credentials are printed to the console on first run.

Option 2 — Docker Compose

Prerequisites: Docker and Docker Compose. Recommended for teams — includes PostgreSQL.

1. Clone the repository

   bash Copy

   git clone https://github.com/mcp-depot/mcp-depot.git
   cd mcp-depot

2. Configure environment variables

   Copy the example env file and set your values:

   bash Copy

   cp .env.example .env

   At minimum, set JWT_SECRET and ENCRYPTION_KEY to strong random strings. See Environment Variables for the full reference.

3. Start the stack

   bash Copy

   docker compose up -d

   The admin UI will be available at http://localhost:5173.

Option 3 — Kubernetes (Helm)

Prerequisites: kubectl and helm installed, a running Kubernetes cluster (Rancher Desktop, minikube, k3s, EKS, GKE, etc.), and Docker images built locally or pushed to a registry. Ideal for production-grade, scalable deployments.

Install

Pre-built images are published to GitHub Container Registry on every release. No local build needed:

helm install mcp-depot oci://ghcr.io/mcp-depot/helm/mcp-depot \
  --namespace mcp-depot \
  --create-namespace

Or install from a local clone:

helm install mcp-depot ./helm/mcp-depot \
  --namespace mcp-depot \
  --create-namespace

Access the UI

Port-forward (quickest, no ingress controller needed):

kubectl port-forward -n mcp-depot svc/mcp-depot-client 8080:80
# Open http://localhost:8080

Ingress (persistent, requires an ingress controller such as Traefik or NGINX):

helm upgrade mcp-depot ./helm/mcp-depot \
  --namespace mcp-depot \
  --set ingress.enabled=true \
  --set ingress.className=traefik \
  --set ingress.host=mcp-depot.local

Then add 127.0.0.1 mcp-depot.local to your /etc/hosts (or C:\Windows\System32\drivers\etc\hosts on Windows) and open http://mcp-depot.local.

Key values

Upgrade & uninstall

# Upgrade
helm upgrade mcp-depot ./helm/mcp-depot --namespace mcp-depot

# Uninstall (PVCs are not deleted automatically)
helm uninstall mcp-depot --namespace mcp-depot
kubectl delete namespace mcp-depot

First Login

On first startup, MCP Depot creates a default admin account. You will be prompted to change the password on first login.

1. Open the admin UI in your browser. The URL depends on your deployment method:

   Deployment	URL
   npm	http://localhost:3000
   Docker Compose	http://localhost:5173
   Kubernetes — port-forward	http://localhost:8080 (or whichever local port you forwarded)
   Kubernetes — ingress	http://<your-ingress-host> (e.g. http://mcp-depot.local)

2. Log in with the default credentials shown in the startup logs (or set via ADMIN_EMAIL / ADMIN_PASSWORD env vars).
3. Go to Settings → API Keys to generate your personal API key. You will need this to configure your AI clients.

Connecting a Client

MCP Depot exposes an MCP endpoint at /mcp. You connect your AI client by installing the mcp-depot CLI proxy, which acts as a stdio bridge to your server.

Step 1 - Install the CLI

npm install -g mcp-depot

Step 2 - Authenticate

Run this once per machine. It saves your server URL and API key locally so the MCP proxy can connect on startup.

mcp-depot --login

Step 3 - Configure your AI client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mcp-depot": {
      "command": "mcp-depot",
      "args": ["--mcp"],
      "env": {
        "MCP_DEPOT_URL": "http://localhost:3000",
        "MCP_DEPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add mcp-depot -- mcp-depot --mcp \
  --env MCP_DEPOT_URL=http://localhost:3000 \
  --env MCP_DEPOT_API_KEY=your-api-key-here

Claude Code (CLI)

claude mcp add mcp-depot -- mcp-depot --mcp

Cursor

Add to .cursor/mcp.json in your project (same JSON format as Claude Desktop above).

Architecture

MCP Depot sits between your AI clients and all your tools — one hub, one configuration, any number of clients.

AI clients connect directly to MCP Depot over stdio, SSE, or HTTP — no extra proxy needed. The hub handles:

• Tool Registry — define REST-backed tools once; all clients see them immediately
• Skills & Personas — reusable prompt templates, saved contexts, and per-persona configurations
• Session Manager — per-client tracking, usage analytics, channels, and context store
• Credentials on the server — API keys and tokens never leave your infrastructure

Transport layer

MCP Depot supports all three MCP transport types from a single server process. You choose the transport per AI client — they can all coexist on the same instance.

Tool types

Every tool exposed over MCP is one of four internal types. The MCP Router determines which executor to call based on how the tool was registered.

External MCP proxy

The External MCP Proxy is what lets you use MCP Depot as a hub for other MCP servers — Jira, GitHub, Bitbucket, or any custom MCP server you run.

• Connection pool — connections are established at startup and kept alive. Tool calls go through the pool without reconnecting on each request.
• stdio and HTTP transports — HTTP servers are reached over the network. stdio servers are spawned as child processes in an isolated mcp-runner sidecar container (Docker Compose and Kubernetes) — not the main server container, which holds your database credentials and encryption key. Both transports are supported side-by-side.
• Tool namespacing — each external server's tools are prefixed with its configured name (e.g. jira__get_issue) to avoid collisions.
• Managed tools — individual tools from an external server can be enabled or disabled without removing the server.

Request flow — REST tool call

Step-by-step trace of what happens when an AI client calls a REST-backed tool:

1. Transport receives the call — the AI client sends a tools/call MCP request over its active transport (stdio, SSE, or Streamable HTTP).
2. Auth middleware validates — the request carries a JWT bearer token or API key. The middleware verifies it before the request proceeds; unauthenticated calls are rejected immediately.
3. MCP Router dispatches — the router looks up the tool by its namespaced name, determines it is a REST tool, and hands off to the REST Tool Executor.
4. Credentials injected — the Tool Executor loads the integration's encrypted credentials from the database (decrypted in memory, never written to logs), assembles the outbound HTTP request, and injects the stored auth header.
5. Integration API called — the request is sent to the configured endpoint (e.g. Jira, GitHub, your own API). AI-provided parameters are mapped to query params, path segments, or the request body per the tool definition.
6. Response transformed — the API response is converted into MCP content format (text, JSON, or error) and returned to the router.
7. Session logged — the Session Manager records the call: tool name, client ID, latency, and success/failure. Visible in the Monitoring dashboard.
8. Result returned — the MCP response travels back over the same transport to the AI client.

Data & security

Tools

A Tool in MCP Depot is an MCP-callable action backed by an HTTP endpoint. You define it once in the admin UI; all connected AI clients can then call it.

Creating a tool

1. In the admin UI, go to Tools → New Tool.
2. Enter the tool name (snake_case, e.g. get_user_profile) and description - the description is what the AI sees when deciding which tool to use, so make it clear and specific.
3. Set the endpoint: method (GET/POST/PUT/DELETE), URL, and any required headers (e.g. Authorization: Bearer ...).
4. Define parameters - the inputs the AI can provide. Each parameter has a name, type, and optional description.
5. Save and the tool is immediately available to connected clients.

Tool parameters

Integrations

An Integration is a group of tools sharing a base URL and common auth. For example, a Jira integration holds the Jira URL and API token - all Jira tools inherit these automatically.

External MCP Server integrations

Beyond HTTP tools, MCP Depot can proxy entire external MCP servers. Under Integrations → New MCP Server, provide:

• Command - the executable (e.g. npx)
• Args - arguments (e.g. @modelcontextprotocol/server-github)
• Env - environment variables (e.g. GITHUB_PERSONAL_ACCESS_TOKEN=...)

MCP Depot starts and manages the server process — in Docker Compose and Kubernetes deployments, this happens inside the isolated mcp-runner sidecar (see External MCP proxy) rather than the main server container — proxying all its tools through your unified endpoint.

Sessions

A session is an active connection between an AI client and MCP Depot. Sessions are tracked automatically when an AI client connects via the CLI proxy.

The Connected Clients panel in the admin UI shows all active sessions with the client name (e.g. claude-code, cursor), version, and connection time. Stale sessions expire automatically after ~150 seconds of inactivity.

Session Channels

Session Channels are append-only message streams that any AI session or human can post to and read from. They are designed for coordination between AI assistants and team members - posting progress updates, sharing findings, or leaving instructions for the next session.

Common use cases

• A developer AI posts a bug report to dev-notes; a reviewer AI reads it later
• A human posts instructions to a channel; the AI reads them on next connection
• Two AI sessions running in parallel coordinate via a shared channel
• Long-running task progress is logged to a channel for async review

Channel MCP Tools

append-to-channel

Post a message to a named channel. Creates the channel if it does not exist.

// Input
{ "channel": "dev-notes", "message": "Build passed. Deployed to staging." }

// Output
{ "id": "abc123", "channel": "dev-notes", "createdAt": "2026-05-04T09:00:00Z" }

read-channel

Read messages from a channel. Pass since to get only new messages - useful for incremental reads in long sessions.

// Input
{ "channel": "dev-notes", "since": "2026-05-04T08:00:00Z" }

// Output
{ "messages": [...], "count": 3 }

list-channels

List all existing channels with message count and last activity.

clear-channel

Delete all messages from a channel. Irreversible - use with care.

watch-channel

Long-poll a channel until a new message arrives, then return it. Use this when you want the AI to wait for a reply without polling repeatedly. Returns { timedOut: true } if no message arrives within the timeout.

// Input
{ "channel": "dev-notes", "timeout": 60 }

// Output (when message arrives)
{ "message": "...", "postedAt": "2026-05-04T09:01:00Z", "timedOut": false }

// Output (if timeout expires)
{ "timedOut": true }

Session Contexts

Session Contexts let AI sessions save named snapshots of their working state - the current task, relevant file paths, decisions made, questions to follow up on. Contexts persist across sessions and can be shared with other AI clients.

How it works

• Each context has a name, content, and optional TTL
• Default TTL is 7 days - writing a context resets the clock, reading does not
• Set ttlHours: 0 to pin a context permanently (never expires)
• Contexts are private by default - only visible to the session that created them
• Set shared: true to make a context visible to all users

Context MCP Tools

store-session-context

Save a named context. Overwrites if a context with the same name already exists.

{
  "name": "current-task",
  "content": "Working on the pool balance API. PR #47 pending review.",
  "ttlHours": 48,
  "shared": false
}

get-session-context

Retrieve a context by name.

list-session-contexts

List all contexts visible to the current user (own + shared). Includes TTL countdown.

delete-session-context

Delete a context by name.

Environment Variables

SSO / OIDC

MCP Depot supports single sign-on via any OIDC-compatible provider — Keycloak, Okta, Auth0, Azure AD, and others. When enabled, a Login with SSO button appears on the login page alongside email/password login.

Required env vars

Kubernetes (Helm) example — Keycloak

Create a Secret with the client secret, then pass OIDC vars via extraEnv and extraEnvFrom:

kubectl create secret generic mcp-depot-oidc \
  --namespace mcp-depot \
  --from-literal=OIDC_CLIENT_SECRET=<your-secret>

helm upgrade mcp-depot ./helm/mcp-depot \
  --namespace mcp-depot \
  --reuse-values \
  --set "extraEnv[0].name=OIDC_ENABLED" \
  --set-string "extraEnv[0].value=true" \
  --set "extraEnv[1].name=OIDC_ISSUER_URL" \
  --set "extraEnv[1].value=http://keycloak.mcp-depot.svc.cluster.local:8080/realms/myrealm" \
  --set "extraEnv[2].name=OIDC_ISSUER_PUBLIC_URL" \
  --set "extraEnv[2].value=https://auth.yourcompany.com/realms/myrealm" \
  --set "extraEnv[3].name=OIDC_CLIENT_ID" \
  --set "extraEnv[3].value=mcp-depot-client" \
  --set "extraEnv[4].name=OIDC_DISPLAY_NAME" \
  --set "extraEnv[4].value=Login with Keycloak" \
  --set "extraEnv[5].name=CLIENT_URL" \
  --set "extraEnv[5].value=https://mcp-depot.yourcompany.com" \
  --set "extraEnvFrom[0].secretRef.name=mcp-depot-oidc"

Docker Compose example

services:
  server:
    environment:
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: http://keycloak:8080/realms/myrealm        # internal
      OIDC_ISSUER_PUBLIC_URL: https://auth.yourcompany.com/realms/myrealm  # browser
      OIDC_CLIENT_ID: mcp-depot-client
      OIDC_CLIENT_SECRET: <your-secret>
      OIDC_DISPLAY_NAME: Login with Keycloak
      CLIENT_URL: https://mcp-depot.yourcompany.com

MCP Client Configuration Reference

Environment variables for the CLI proxy

All supported clients

{
  "mcpServers": {
    "mcp-depot": {
      "command": "mcp-depot",
      "args": ["--mcp"],
      "env": {
        "MCP_DEPOT_URL": "https://your-server.com",
        "MCP_DEPOT_API_KEY": "your-api-key"
      }
    }
  }
}

claude mcp add mcp-depot -- mcp-depot --mcp \
  --env MCP_DEPOT_URL=https://your-server.com \
  --env MCP_DEPOT_API_KEY=your-api-key

FAQ

Do I need Docker?

Docker Compose is the recommended way to run MCP Depot. You can also run the Node.js server and React frontend directly if you prefer - see the repository's CONTRIBUTING.md for the development setup.

Can I use a remote server?

Yes. Set MCP_DEPOT_URL to your server's public URL (HTTPS recommended). The CLI proxy on each client machine connects to the remote server.

Is SQLite suitable for production?

SQLite works well for personal and small-team use. For larger teams with concurrent write-heavy workloads, set the DATABASE_URL environment variable to a PostgreSQL connection string - MCP Depot will use it automatically instead of SQLite.

How are credentials protected?

All integration credentials (API keys, tokens, passwords) are encrypted at rest with AES-256-GCM using the ENCRYPTION_KEY you provide. They are never sent to AI clients or logged.

What happens when I disconnect an AI client?

Session entries are cleaned up automatically - direct HTTP sessions are removed immediately on disconnect, and CLI proxy sessions expire within ~150 seconds if the heartbeat stops.

Can multiple users share the same MCP Depot instance?

Yes. Each user has their own account and API key. Tool access is scoped per user. Session contexts are private by default but can be shared. Channels are accessible to all users.