Everything you need to run MCPlama.

1 What MCPlama is

MCPlama is a self-hosted gateway that sits between your AI clients — Claude Desktop, Cursor, VS Code Copilot, or anything else that speaks MCP — and the actual MCP servers you want them to use. Instead of every teammate juggling their own API keys and configs for every tool, you install servers once in MCPlama, and everyone connects through it.

It gives you one place to see who's connected to what, control which tools people can use, and keep a record of every call — while your AI client only ever sees a single connection link, never the underlying credentials.

2 How a request flows

Every MCP call is authenticated, checked against policy, logged, and forwarded through MCPlama to the selected MCP server.

3 Recommended system requirements

These are recommended starting specifications with additional headroom for the database, audit logs, and MCP server containers. Monitor your workload and scale up as concurrency and log volume grow.

4 Install

MCPlama ships as a single Docker image — backend, database, and dashboard, all bundled. No separate install steps, and nothing to generate yourself.

Pull the image (optional)

The community image is published in the MCPlama registry as mcplama/mcplama:latest. Use a private mirror only when your deployment requires one.

docker pull mcplama/mcplama:latest

The docker run below pulls it automatically if it isn't present locally — running the pull yourself first just makes the first run faster to watch.

Run it

MCPlama creates and manages its Docker network automatically. Mount the Docker socket so MCPlama can start MCP server containers, and keep the named volume so your database and generated keys survive restarts and upgrades. Choose the example that matches how users and MCP clients will reach the gateway.

Local-only access

Use this when MCPlama is accessed from the same host:

docker run -d --name mcplama \
  -p 127.0.0.1:8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v mcplama_pgdata:/var/lib/postgresql \
  -e GATEWAY_URL=http://localhost:8080 \
  mcplama/mcplama:latest

Public access through a proxy

Use this when a reverse proxy, load balancer, or ingress provides the public HTTPS endpoint:

docker run -d --name mcplama \
  -p 127.0.0.1:8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v mcplama_pgdata:/var/lib/postgresql \
  -e GATEWAY_URL=https://[yourdomain].com \
  mcplama/mcplama:latest

In the public example, the proxy must forward the public HTTPS URL to http://127.0.0.1:8080. Do not change GATEWAY_URL to the internal address.

Direct access on all host interfaces

Use this only when you intentionally want MCPlama reachable directly without a reverse proxy. The host firewall must allow the selected port:

docker run -d --name mcplama \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v mcplama_pgdata:/var/lib/postgresql \
  -e GATEWAY_URL=http://[yourdomain].com:8080 \
  mcplama/mcplama:latest

To use another host port, for example 8043, map it to the container's port 8080 and include it in GATEWAY_URL: -p 8043:8080 with http://[yourdomain].com:8043.

For direct access or public exposure through HTTPS, choose the appropriate option in Public access through a proxy.

Finish setup in the browser

For this local example, visit http://localhost:8080. The setup wizard walks you through creating the admin account, naming your gateway, and optionally turning on email.

5 Environment variables

For a local test, the defaults are enough. For a public deployment, set GATEWAY_URL to the URL users and MCP clients actually use. The other variables are optional overrides.

The free community edition includes up to 10 users and 100 installed servers.

Advanced/private installs can also set RUNNER_IMAGE to point npx, uvx, and stdio-based servers at a registry mirror or pinned runner tag. Most installs should leave it unset.

Per-server CPU and memory limits are configured in the Add server or Edit server form. For managed Docker, npx, uvx, and stdio servers, use values such as CPU 1 and memory 256m. The broker clamps these values to both the configured limits and the resources available on the host, including after a VM resize.

Private webhook destinations are blocked by default for SSRF protection. For a trusted LAN-only webhook, add its exact host or IP, for example -e ALLOWED_PRIVATE_WEBHOOK_HOSTS=192.168.1.42. This applies only to policy webhooks; private MCP server URLs remain blocked.

6 Public access through a proxy

For a public deployment, put an HTTPS reverse proxy, load balancer, or ingress in front of MCPlama. The proxy owns the public TLS endpoint; MCPlama listens on a private host port.

https://[yourdomain].com
          ↓
  HTTPS proxy :443
          ↓
  127.0.0.1:8080
          ↓
  MCPlama container

1. Choose the network binding

For a proxy on the same host, bind MCPlama to localhost:

-p 127.0.0.1:8080:8080

For intentional direct access, bind all host interfaces and choose the host port users will call:

-p 8080:8080
# or
-p 8043:8080

The first port is the host port; the second is MCPlama's container port.

2. Set the canonical gateway URL

GATEWAY_URL must exactly match the address users and MCP clients use. Its default is http://localhost:8080. For a proxy, use the public URL such as https://[yourdomain].com. For direct access, include the host port, such as http://[yourdomain].com:8080 or http://[yourdomain].com:8043.

3. Configure the HTTPS proxy

Terminate TLS at the proxy and forward to the private MCPlama address. Preserve the original Host, X-Forwarded-For, and X-Forwarded-Proto headers. MCP connections use streaming, so disable response buffering and allow long-lived read and send timeouts.

4. Complete the security boundary

Use a trusted certificate for the public hostname. Allow only the proxy's public ports through the firewall, and keep the MCPlama host port private when using a proxy. FRONTEND_URL and CORS_ORIGINS are optional overrides for a separate frontend origin; they are not required when the dashboard and gateway share one public origin.

7 Troubleshooting

Setup wizard won't load from another machine

Almost always the host/network firewall, or GATEWAY_URL still pointing at localhost — see Public access through a proxy above.

Data disappeared after a restart

Stopping or restarting the container does not normally remove data. The -v mcplama_pgdata:/var/lib/postgresql volume is what makes your data persistent when the container is recreated or upgraded. Without it, everything lives inside the container's writable layer and is gone when the container is removed.

Saved credentials or OAuth logins stopped working

MCPlama stores its generated encryption keys in the same mcplama_pgdata volume as the database. Restore the database and volume together; restoring only one side can leave encrypted credentials unreadable.

A Docker-based server won't start

If the host running MCPlama can't reach the registry that contains the server image, installation will fail. Make sure the host is logged in to the registry, or mirror the image somewhere it can reach.

An npx, uvx, or stdio server won't start

Those server types use the MCPlama runner image. MCPlama pulls it automatically when needed, but the host still needs registry access. In restricted networks, mirror the runner image and set RUNNER_IMAGE to that mirrored image.

A server fails with a CPU or memory Docker error

The broker automatically caps CPU and memory requests to the resources available on the host. If Docker still reports a resource error, edit the server and lower the matching limit (practical starting points are CPU 1 and memory 256m). Use Docker memory formats such as 256m or 1g, not a bare number or 6mb.

8 The built-in catalog

MCPlama includes a built-in catalog page for ready-to-install MCP servers. Use the search, category filters, and details drawer to find the server you need, then install it from the dashboard. Don't see what you need? Add a custom server by hand — see below.

9 Custom server types

Custom servers let you put internal tools, private packages, and third-party servers behind the same MCPlama controls as the catalog entries. Choose the runtime, add required environment variables or user credential fields, then publish it for your team.

For Docker, NPX, and UVX servers, the Add server and Edit server forms also let you set optional CPU and memory limits. If a server fails to start because Docker rejects its resources, edit the server and lower those values. Whichever type you pick, it ends up behind the same /connect/{token} link as everything else — your AI client doesn't need to know or care how a server actually runs.

10 Shared vs. per-user credentials

When you install a server, its Authorization tab asks you to pick one of two credential modes before anyone can connect through it:

For servers that support OAuth, MCPlama discovers the authorization server automatically and runs the full login flow — users click "Authorize" and sign in with the real provider directly. MCPlama never sees their password, and your AI client only ever holds a connection link you can revoke in one click.

11 Inviting team members

From Users in the dashboard, an admin can invite someone by email and pick their role — admin (full dashboard access) or member (Member Portal only, see below). Each invite is a link that's valid for 7 days.

If email (SMTP) is configured, MCPlama can send the invite for you. If not, just copy the invite link and send it yourself — either way works.

12 The Member Portal

Regular users never touch the admin dashboard. They get their own Member Portal instead — a simple, self-service way to get connected:

1. Browse — every server an admin has enabled shows up in their portal, with no admin login needed.
2. Request access — one click sends a request. An admin approves or denies it; the status flips from Pending to Ready right there.
3. Connect — for per-user servers, they add their own API key or authorize their own OAuth login, then copy their personal connection link into their AI client.

13 Access policies

Policies let admins control exactly what a connection is allowed to do, beyond just "approved or not." You can scope a policy to a specific server, user, or role.

Webhook policy details

MCPlama sends the webhook a JSON payload before each tool call. The endpoint must return a JSON object with allowed set to true or false. A false response blocks the call and can include a user-facing reason.

Request
{
  "server_id": 7,
  "user_id": 42,
  "tool_name": "delete_file",
  "request": { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "delete_file" } }
}

Allow:  { "allowed": true }
Deny:   { "allowed": false, "reason": "Destructive tools require approval" }

You can also return mutated_request with a rewritten JSON-RPC request. Webhook failures, timeouts, non-2xx responses, and malformed responses fail closed and block the call. The policy’s general “Action when violated” setting does not apply to webhook policies—the webhook response is the decision.

A blocked call comes back to the AI client as a normal failed tool call, not a broken connection — so the assistant can explain it rather than just hanging.

14 Email (SMTP)

Optional, but recommended. Configuring an outbound mail server lets MCPlama send email for:

• Team invites — send the invite link directly instead of copy-pasting it yourself.
• Alert notifications — get emailed when an alert rule you've set up fires.
• Admin password reset — the self-service "Forgot password?" link on the login page only works if SMTP is configured. Without it, a locked-out admin has no way back in on their own.

You can turn it on during the setup wizard, or any time afterward from Settings → Email / SMTP. All it needs is a host, port, and credentials for any standard SMTP provider (Gmail, SES, Postmark, your own mail server, etc.).

15 Environment & secrets checklist

Use this short checklist before putting a deployment into regular use. The detailed URL and HTTPS guidance is in Public access through a proxy; variable meanings and defaults are in Environment variables.

16 Best practices

• Prefer per-user credentials for personal accounts. Use shared credentials only for genuinely team-wide tools — see Shared vs. per-user credentials.
• Set up policies for anything destructive. A tool_block or tool_allow rule is cheap insurance against an AI client calling something it shouldn't.
• Turn on email and configure alerts. You'll hear about problems (like a spike in failed calls) instead of finding them later in the audit log.
• Review the audit log periodically. Every call is recorded — who, what tool, when, and whether it succeeded.
• Keep MCPlama updated. Pull the latest image periodically to get security and bug fixes.
• Isolation is built in. The parts of MCPlama that handle your requests never touch the Docker daemon directly — a separate internal component does that on their behalf, so a bug in request handling doesn't translate into control over your host's containers.