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)
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.

Wait for both services to go green. The gateway applies its database migrations on first boot.
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.
On that service's Variables tab, copy the generated PLATFORM_ADMIN_PASSWORD.
Visit your gateway URL and sign in with the address you entered as PLATFORM_ADMIN_EMAIL and the copied password.
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.
Register your first MCP server from the admin UI, then point a client at your gateway. The Claude Desktop guide and the 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, 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 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 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, RBAC)

Dependencies for ContextForge Hosting

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

Deployment Dependencies

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 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.