Deployment guide

ContextForge on a VPS: an MCP gateway for your AI agents

Deploy on a VPS Cloud →

Tutorial

Self-hosting

ContextForge on a VPS: an MCP gateway for your AI agents

Every AI agent that needs to call your tools asks for its own configuration: one MCP server per service, declared in every client, with its credentials. ContextForge, IBM's open-source MCP gateway, brings all of that together behind a single address. This guide installs it on a VPS with Docker Compose, locks it with API tokens, publishes it over HTTPS behind nginx, turns a REST API into an MCP tool and connects a client to it.

7 min read3 steps
Contents· What ContextForge does1/12
  1. 01What ContextForge does
  2. 02What the gateway brings
  3. 03Wiring each tool or going through ContextForge
  4. 04Prerequisites
  5. 05Install ContextForge with Docker Compose
  6. 06Never disable authentication
  7. 07Publish ContextForge over HTTPS with nginx
  8. 08Log in and create an API token
  9. 09Turn a REST API into an MCP tool
  10. 10Group the tools and connect an MCP client
  11. 11Back up and update
  12. 12One-click installation on ServOrbit

What ContextForge does

ContextForge is a gateway for the Model Context Protocol (MCP), the protocol that lets an AI agent discover and call tools. It sits between your clients — coding assistants, agent frameworks, automations — and the tools they use: remote MCP servers, existing REST or gRPC APIs.

The project is published by IBM under the Apache-2.0 licence. It provides an admin API, a web console, user and token management, and virtual servers: groups of tools, each exposed at its own MCP address. On a VPS, it is the single entry point for your agents.

What the gateway brings

  • One address — your clients connect to the gateway, not to each tool.
  • REST APIs as tools — a URL, a method and an input schema, with no MCP server to write.
  • Virtual servers — one set of tools per agent, project or client.
  • Federation — remote MCP servers registered and exposed in the same place.
  • API tokens — one per client, with an expiry date, revocable one by one.
  • A web console — tools, servers, tokens and users managed from /admin.

Wiring each tool or going through ContextForge

Scroll the table

One MCP server per toolContextForge
Client configurationOne tool to declare in every clientOne address and a token
Service credentialsCopied into every clientKept by the gateway
Existing REST APIAn MCP server to writeDeclared as a tool
Removing accessClient by clientRevoke a token
Tools an agent seesAll those it was configured withThose of its virtual server

Prerequisites

An Ubuntu 24.04 VPS with 2 GB of RAM and 2 vCPUs is enough: with two worker processes, the gateway uses about 800 MB of memory. The data fits in an SQLite database of a few megabytes.

You need Docker with the Compose plugin, nginx and certbot on the host, jq to read API responses, and a name (mcp.example.com in this guide) pointing to the VPS IP.

Install ContextForge with Docker Compose

  1. Generate the secrets

    In a dedicated folder, write a .env file with the domain name, the administrator password and two separate secrets: SECRET_KEY signs the tokens, ENCRYPTION_KEY_HEX64 encrypts the credentials of the servers you register. ContextForge refuses to start with secrets that are too short or left at their example value.

    mkdir -p /opt/contextforge && cd /opt/contextforge
    cat > .env <<EOF
    DOMAIN=mcp.example.com
    ADMIN_PASSWORD=$(openssl rand -base64 18)
    SECRET_KEY=$(openssl rand -hex 32)
    ENCRYPTION_KEY_HEX64=$(openssl rand -hex 32)
    EOF
    chmod 600 .env
  2. Write the docker-compose.yml file

    The image runs as an unprivileged user (uid 10001): the contextforge-init service makes the volume writable before start-up. AUTH_REQUIRED and MCP_REQUIRE_AUTH lock the API and the MCP endpoint, and the port is published on the loopback interface only. DEFAULT_USER_PASSWORD, the temporary password of accounts created without one, is drawn at random on every start.

    services:
      contextforge-init:
        image: ghcr.io/ibm/mcp-context-forge:v1.1.1
        user: "0:0"
        entrypoint: ["chown", "-R", "10001:10001", "/app/data"]
        restart: "no"
        volumes:
          - contextforge-data:/app/data
    
      contextforge:
        image: ghcr.io/ibm/mcp-context-forge:v1.1.1
        restart: unless-stopped
        depends_on:
          contextforge-init:
            condition: service_completed_successfully
        environment:
          HOST: "0.0.0.0"
          PORT: "4444"
          ENVIRONMENT: "production"
          APP_DOMAIN: "https://${DOMAIN}"
          ALLOWED_ORIGINS: "https://${DOMAIN}"
          DATABASE_URL: "sqlite:////app/data/mcp.db"
          CACHE_TYPE: "database"
          GUNICORN_WORKERS: "2"
          MCPGATEWAY_UI_ENABLED: "true"
          MCPGATEWAY_ADMIN_API_ENABLED: "true"
          AUTH_REQUIRED: "true"
          MCP_CLIENT_AUTH_ENABLED: "true"
          MCP_REQUIRE_AUTH: "true"
          EMAIL_AUTH_ENABLED: "true"
          PLATFORM_ADMIN_EMAIL: "[email protected]"
          PLATFORM_ADMIN_PASSWORD: "${ADMIN_PASSWORD}"
          JWT_SECRET_KEY: "${SECRET_KEY}"
          AUTH_ENCRYPTION_SECRET: "${ENCRYPTION_KEY_HEX64}"
        entrypoint: ["/bin/bash", "-c"]
        command:
          - |
            export DEFAULT_USER_PASSWORD="$$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')"
            exec ./docker-entrypoint.sh
        ports:
          - "127.0.0.1:4444:4444"
        volumes:
          - contextforge-data:/app/data
    
    volumes:
      contextforge-data: {}
  3. Start and check

    Start the stack, then query the health endpoint. The first time, ContextForge creates its database and the administrator account; the container turns healthy in under a minute.

    docker compose up -d
    docker compose ps
    curl -s http://127.0.0.1:4444/health

    The expected answer is {"status":"healthy"}. Any other route, /tools or /version for example, answers 401 without a token.

Never disable authentication

An open MCP gateway hands anyone the tools you plugged into it — and the credentials that come with them. Keep AUTH_REQUIRED and MCP_REQUIRE_AUTH at true, the port on 127.0.0.1, and leave nginx alone facing the Internet.

Publish ContextForge over HTTPS with nginx

Create a server block in /etc/nginx/sites-available/ and enable it. X-Forwarded-Proto matters: the console compares the origin of the login form with the request address, and refuses the login if they differ. proxy_buffering off lets the MCP protocol's streamed responses through.

server {
    server_name mcp.example.com;

    location / {
        proxy_pass http://127.0.0.1:4444;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

Check the configuration, then request the certificate:

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d mcp.example.com

Log in and create an API token

Open https://mcp.example.com/admin and log in with [email protected] and the password from the .env file. The console can create tokens; so can the API. The login returns a short-lived session token, used to create a named API token, valid for 30 days here:

SESSION=$(curl -s https://mcp.example.com/auth/email/login -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"YOUR_PASSWORD"}' | jq -r .access_token)
TOKEN=$(curl -s https://mcp.example.com/tokens -H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
  -d '{"name":"agent-1","expires_in_days":30}' | jq -r .access_token)

Create one token per client or agent: you can revoke one without touching the others.

Turn a REST API into an MCP tool

A REST tool is declared by its URL, its method and the schema of its parameters. The example below exposes GitHub's public zen API, which returns a sentence and expects no parameter:

curl -s https://mcp.example.com/tools -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"tool":{"name":"github_zen","url":"https://api.github.com/zen","integration_type":"REST","request_type":"GET","input_schema":{"type":"object","properties":{}}}}' \
  | jq -r .id

The command prints the tool's ID. On the MCP side, its name becomes github-zen. For an internal API, replace the URL and describe its parameters in input_schema: that schema is what the agent reads to know how to call it.

Group the tools and connect an MCP client

A virtual server groups tools under one MCP address. Create it with the tool's ID:

curl -s https://mcp.example.com/servers -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"server":{"name":"demo","associated_tools":["TOOL_ID"]}}' | jq -r .id

Then check, as a client would, that the tool is listed:

curl -s https://mcp.example.com/servers/SERVER_ID/mcp -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In your MCP client, declare the virtual server's address and the token. The exact form depends on the client; many accept an entry like this one:

{
  "mcpServers": {
    "contextforge": {
      "type": "http",
      "url": "https://mcp.example.com/servers/SERVER_ID/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Back up and update

What to back up: the contextforge-data volume, which holds the SQLite database — tools, servers, users and tokens — and the .env file. Without ENCRYPTION_KEY_HEX64, the encrypted credentials in the database can no longer be read. Stop the service while copying:

cd /opt/contextforge
docker compose stop contextforge
docker compose cp contextforge:/app/data ./backup-$(date +%F)
docker compose start contextforge

To update, change the image tag in both services after reading the release notes, then:

docker compose pull
docker compose up -d

ContextForge applies its database migrations on start-up: take the backup first.

One-click installation on ServOrbit

On a ServOrbit VPS, ContextForge installs from the Marketplace: the script deploys the official image, generates the administrator password and the secrets, locks the instance against any request without a token and configures nginx over HTTPS. The address is a subdomain of one of your domains or the VPS's free subdomain, certificate included, and the password is shown in your client area.

Share this articleservorbit.com/ma-en/blog/self-host-contextforge-vps-mcp-gateway