mcpexpress/mcp-express repository overview

⁠MCP Express

MCP Express helps you create and deploy Model Context Protocol (MCP)⁠ servers on your own infrastructure. You don't need to write an MCP server from scratch.

MCP Express is in alpha. Today you can:

• Create MCP servers from a web UI. Each server gets its own endpoint on your instance, for example http://localhost:3000/weather/mcp.
• Make a server public, or protect it with an API key that MCP Express generates for you and that you can rotate at any time.
• Turn servers on and off, and delete them.
• Copy ready-made connection settings for Claude Code, Cursor and VS Code.

Building MCP tools from your existing code and API endpoints is in development.

⁠Quick start

⁠1. Pull the image

docker pull mcpexpress/mcp-express:latest

Each release is also tagged with its version number, for example mcpexpress/mcp-express:0.1.0. Use a version tag to stay on a specific release.

⁠2. Run the container

docker run -d \
  --name mcp-express \
  -p 3000:3000 \
  -v mcp-express-data:/app/data \
  --restart unless-stopped \
  mcpexpress/mcp-express:latest

ENCRYPTION_KEY must be at least 32 characters. To generate one:

openssl rand -base64 32

⁠Using Docker Compose

services:
  mcp-express:
    image: mcpexpress/mcp-express:latest
    ports:
      - '3000:3000' # change the left side to use a different host port
    environment:
      # - ENCRYPTION_KEY=<your-key> # optional, see the table above
      # - BASE_URL=https://mcp.example.com # optional, see the table above
    volumes:
      - mcp-express-data:/app/data
    restart: unless-stopped

volumes:
  mcp-express-data:

docker compose up -d

⁠Getting started with the app

1. Open the app. Go to http://localhost:<host-port> in your browser, where <host-port> is the port you mapped with -p. For example, with -p 8080:3000 the address is http://localhost:8080.
2. Create your account. Enter your email address and accept the terms and conditions.
3. Set your password. Choose a password for your account.
4. Sign in. Sign in with your email and password.
5. Create an MCP server. Open MCP servers, select New server, and enter a title, a name and a description. The name becomes part of the endpoint. Choose Public or API key security.

⁠Connecting an MCP client

Each server is reachable at:

http://<your-address>/<name>/mcp

Clients connect over the Streamable HTTP transport. Open a server and go to its Integration tab for settings you can copy for Claude Code, Cursor and VS Code. For example, with Claude Code:

claude mcp add --transport http weather http://localhost:3000/weather/mcp

If the server uses an API key, clients must send it as a bearer token:

Authorization: Bearer <api-key>

Copying a snippet from the Integration tab fills in the full key. When you rotate a key, the old one stops working immediately, so update your clients with the new one.

⁠Updating

docker pull mcpexpress/mcp-express:latest
docker rm -f mcp-express
# then run the same `docker run` command as above

If you mounted the /app/data volume (and, if you set it, keep the same ENCRYPTION_KEY), your data and API keys are kept.

Upgrading from a version that used JWT_SECRET: rename it to ENCRYPTION_KEY, keeping the same value. If you leave it out, a new key is generated and existing sessions, API keys and Environment Secrets stop working. Database migrations run automatically when the container starts.

⁠Troubleshooting

• The container stops right after starting. If you set ENCRYPTION_KEY, make sure it is at least 32 characters. Check the logs with docker logs mcp-express.
• The page doesn't load. Check that the host port you mapped isn't used by another service, and that you're opening that host port, not 3000, if you changed it.
• You're logged out, or clients are refused, after recreating the container. Mount the same /app/data volume, and if you set ENCRYPTION_KEY, use the same value each time. Changing it ends existing sessions and makes existing API keys unreadable. If it has changed, rotate each server's key on its Integration tab and update your clients.
• The endpoints in the app show the wrong address. Set BASE_URL to the address your clients use, for example when MCP Express runs behind a reverse proxy.
• A client gets an error from an endpoint. 401 means the API key is missing or wrong (or was rotated), 404 means no server uses that name, and 503 means the server is turned off. Turn it back on with the switch at the top of the server's page.
• Your data isn't saved with a host folder mount. The app runs as user ID 1001. If you mount a host folder instead of a named volume, make sure that user can write to it, for example with sudo chown -R 1001 ./data.