---
title: "Deploy ContextForge MCP Gateway"
description: "Self-hosted IBM registry, proxy and admin UI for MCP servers and REST APIs"
category: "AI/ML"
url: https://railway.com/deploy/contextforge-mcp-g-1
---

# Deploy ContextForge MCP Gateway

Self-hosted IBM registry, proxy and admin UI for MCP servers and REST APIs

**[Deploy ContextForge MCP Gateway on Railway](https://railway.com/template/contextforge-mcp-g-1)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/contextforge-mcp-g-1/manifest.json

- **Creator:** ProCode
- **Category:** AI/ML
- **Total deploys:** 1

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### ContextForge https://github.com/IBM.png

- **Image:** ghcr.io/ibm/mcp-context-forge:v1.0.10
- **Health check:** /health
- **Public domain:** Yes

## Documentation

# Deploy and Host ContextForge MCP Gateway on Railway

ContextForge is IBM's open-source MCP gateway, registry and proxy: one endpoint that every AI client
and agent points at, federating your MCP servers, A2A agents and REST APIs behind a single address
with shared discovery, authentication and access control. It replaces the per-client config files
where Claude Desktop, Cursor and each of your own agents keeps its own private server list. Standing
it up yourself means running a PostgreSQL database alongside it and working through an example
environment file documenting more than 900 settings. This template brings up the gateway and its
database already wired to each other, on versions I deploy and test as a set, with every secret and
password generated for you at deploy time.

## About Hosting ContextForge MCP Gateway

The gateway runs as a single container against PostgreSQL, and both arrive configured. The database
connection is assembled from live references to the database service, so it survives any later change
to those credentials, and schema migrations run on every boot. The JWT signing key, the credential
encryption secret and all three passwords are generated at deploy time, and the admin UI's allowed
origin is bound to the public domain Railway issues you. Worker count and the rate limiter are sized
for a single instance, so an idle gateway sits under a gigabyte of memory. You supply one value, the
email address for your administrator account, and deploy.

## Common Use Cases

- **One endpoint for every AI client.** Register your MCP servers once, then point Claude Desktop,
  Cursor, Windsurf and your own agents at a single gateway URL.
- **A private tool registry for a team.** Share a curated, access-controlled catalog of internal
  tools so teammates consume the same vetted set instead of each wiring their own.
- **Wrap REST APIs as MCP tools.** Expose services that were never built for agents through a
  protocol-compliant endpoint, without touching the upstream service.
  ([REST passthrough](https://ibm.github.io/mcp-context-forge/latest/using/rest-passthrough/))
- **A control point for agent traffic.** Put authentication, rate limiting, observability and
  guardrails in front of tool calls that would otherwise go out direct and unlogged.

## How to Use ContextForge After Deployment

**Railway asks you for `PLATFORM_ADMIN_EMAIL` before it will deploy.** Enter your own address. It is
the login of your administrator account, and there is no default.

1. Wait for both services to go green. The gateway applies its database migrations on first boot.
2. Open the **ContextForge** service, then **Settings**, then **Networking**. The generated domain
   there is your gateway URL. Add a custom domain on the same screen if you have one.
3. On that service's **Variables** tab, copy the generated `PLATFORM_ADMIN_PASSWORD`.
4. Visit your gateway URL and sign in with the address you entered as `PLATFORM_ADMIN_EMAIL` and the copied password.
5. The gateway sends you to a change-password screen. The generated password is single use; the one
   you set here is what lives in your database from then on. This first sign-in has to happen in the
   admin UI, because the JSON login API refuses the bootstrap password.
6. Register your first MCP server from the admin UI, then point a client at your gateway. The
   [Claude Desktop guide](https://ibm.github.io/mcp-context-forge/latest/using/clients/claude-desktop/)
   and the [quick start](https://ibm.github.io/mcp-context-forge/latest/overview/quick_start/) cover
   the client side.

## Is ContextForge Free?

The software is free and open source under Apache 2.0, and this template adds no licence cost. You pay
Railway for the infrastructure it runs on. There are no third-party API charges: the gateway proxies
calls to servers you already have.

## ContextForge vs Per-Client Config and Hosted MCP Gateways

| | ContextForge | Per-client config files | Hosted MCP gateways |
|---|---|---|---|
| Where the server list lives | One registry, shared | Duplicated per client | Vendor's cloud |
| Your credentials | Your database | Scattered across machines | Vendor holds them |
| Access control | Users, teams, tokens, RBAC | None | Vendor's model |
| Wrap REST APIs | Yes | No | Varies |
| Cost model | Your infrastructure | Free | Per seat or per call |
| Runs private or offline | Yes | Yes | No |

## FAQ

**Do I need Redis, and can I run more than one replica?** No Redis, and one replica. Redis is only
used for caching, distributed rate limiting, LLM Chat sessions spanning worker processes and
multi-instance federation. This template runs a single worker and keeps session state in the database.
Scaling out later means adding a Redis service and following the
[scaling guide](https://ibm.github.io/mcp-context-forge/latest/manage/scale/), which covers the
shared-state variables, worker counts and pool sizes involved.

**Where is my data, and how do I back it up?** Everything the gateway knows lives in the bundled
PostgreSQL: registered servers, virtual servers, tools, user accounts and API tokens. That database has
a persistent volume and survives redeploys. The gateway also ships an
[export and import](https://ibm.github.io/mcp-context-forge/latest/manage/export-import/) tool for
moving a configuration between instances. For direct `psql` access, enable a TCP proxy on the Postgres
service's settings; nothing is exposed publicly by default.

**Which LLM Chat providers work?** The built-in
[LLM Chat](https://ibm.github.io/mcp-context-forge/latest/using/clients/llm-chat/) console works with
OpenAI, Azure OpenAI, OpenAI-compatible endpoints and Ollama, whose libraries ship in the official
image. The other six entries in its provider list do not work on this release: Anthropic, AWS Bedrock
and IBM watsonx have no library in the image, and Google Vertex AI, Cohere and Mistral have no
implementation behind them.

**The deploy log warns at startup about a legacy API sunset and suggests `LEGACY_API_ENABLED=false`. Should I set it?**
Not on this version. The date only changes the wording of the warning; nothing switches off by itself.
This release's admin UI still calls the unversioned paths, so disabling them would break the UI. If you
call the API yourself, use the `/v1/...` paths.

**Can I add single sign-on and teams?** Yes. Set `SSO_ENABLED=true` plus your provider's variables for
GitHub, Google, Okta, Microsoft Entra ID, Keycloak, ADFS or generic OIDC; it is off by default. Teams
and role-based access control are built in and managed from the admin UI.
([SSO](https://ibm.github.io/mcp-context-forge/latest/manage/sso/),
[RBAC](https://ibm.github.io/mcp-context-forge/latest/manage/rbac/))

## Dependencies for ContextForge Hosting

- **PostgreSQL 18**: stores registered servers, virtual servers, tools, users, teams and API tokens.

### Deployment Dependencies

- [ContextForge documentation](https://ibm.github.io/mcp-context-forge/)
- [Source on GitHub (Apache 2.0)](https://github.com/IBM/mcp-context-forge)
- [Container image on GHCR](https://github.com/IBM/mcp-context-forge/pkgs/container/mcp-context-forge)

### Implementation Details

The gateway runs `ghcr.io/ibm/mcp-context-forge:v1.0.10`, pinned. This project publishes its 1.0 line
with a `v` prefix, so a plain `1.0.10` tag does not exist. The database URL uses the
`postgresql+psycopg` scheme because the gateway is built on psycopg 3.

`REQUIRE_USER_IN_DB` is false, which is what keeps the administrator bootstrap login available. Leave
it false until your admin account exists. `SSRF_ALLOW_PRIVATE_NETWORKS` is true, so you can register
MCP servers running as sibling services in the same Railway project by their `railway.internal`
hostnames. Every other setting is in the
[configuration reference](https://ibm.github.io/mcp-context-forge/latest/manage/configuration/) and can
be added as a variable on the ContextForge service.

**How to Upgrade:** change the image tag on the service and redeploy. Migrations apply on boot. You can
also let Railway do it, since both images come from ghcr.io: open the service's Settings, find Source,
and use Configure Auto Updates with a maintenance window. Turn it on for the gateway and the database
together or for neither, because versions tested as a set are the point of this template. The
pre-update volume backup is a Pro plan feature, so take your own backup first on Hobby, and detection
can lag a new release by a few hours.

## Why Deploy ContextForge on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your
infrastructure so you don't have to deal with configuration, while allowing you to vertically
and horizontally scale it.

By deploying ContextForge on Railway, you are one step closer to supporting a complete full-stack
application with minimal burden. Host your servers, databases, AI agents, and more on Railway.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/contextforge-mcp-g-1