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 tool | ContextForge | |
|---|---|---|
| Client configuration | One tool to declare in every client | One address and a token |
| Service credentials | Copied into every client | Kept by the gateway |
| Existing REST API | An MCP server to write | Declared as a tool |
| Removing access | Client by client | Revoke a token |
| Tools an agent sees | All those it was configured with | Those 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
Generate the secrets
In a dedicated folder, write a
.envfile with the domain name, the administrator password and two separate secrets:SECRET_KEYsigns the tokens,ENCRYPTION_KEY_HEX64encrypts 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 .envWrite the docker-compose.yml file
The image runs as an unprivileged user (uid 10001): the
contextforge-initservice makes the volume writable before start-up.AUTH_REQUIREDandMCP_REQUIRE_AUTHlock 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: {}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
healthyin under a minute.docker compose up -d docker compose ps curl -s http://127.0.0.1:4444/healthThe expected answer is
{"status":"healthy"}. Any other route,/toolsor/versionfor 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.comLog 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 .idThe 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 .idThen 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 contextforgeTo update, change the image tag in both services after reading the release notes, then:
docker compose pull
docker compose up -dContextForge 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.
servorbit.com/ma-en/blog/self-host-contextforge-vps-mcp-gateway