Deploy and Host MetaMCP on Railway

MetaMCP is a self-hosted MCP aggregator, orchestrator, middleware, and gateway in one Docker container. It manages multiple MCP servers through a single GUI, aggregating tools, prompts, and resources into unified endpoints that any MCP client can connect to — Claude Desktop, Cursor, Windsurf, or anything that speaks MCP.

About Hosting MetaMCP

Deploying MetaMCP requires two services: the MetaMCP application container (ghcr.io/metatool-ai/metamcp:latest) and a PostgreSQL database for persistent storage. The application runs both the web GUI (Next.js) and the MCP proxy engine (Express) in a single container. Seven environment variables configure the MetaMCP service — three are auto-generated secrets, two reference the public domain, one points to Postgres, and one sets the Node environment. Postgres needs a persistent volume at /var/lib/postgresql/data. Once deployed, you register the first account through the web UI (there is no default admin), generate an API key, and point your MCP clients at the Railway URL.

Common Use Cases

Centralizing MCP servers — one dashboard to manage GitHub, Slack, database, and custom MCP servers instead of per-developer configs scattered across machines.
Namespace isolation — separate namespaces for different projects or environments, each exposing its own endpoint with its own set of MCP servers and tools.
Multi-tenant access — each team member gets their own account, API keys, and namespace assignments with controlled access.
Middleware and tool filtering — intercept MCP requests to filter inactive tools, add annotations, rename tools, or log usage before they reach the underlying server.
Enterprise SSO — lock down access with Google, Azure AD, Okta, or any OIDC provider instead of managing local passwords.
Exposing STDIO servers over HTTP — turn local STDIO-only MCP servers into remote SSE or Streamable HTTP endpoints accessible from cloud-based tools.

Dependencies for MetaMCP Hosting

MetaMCP (ghcr.io/metatool-ai/metamcp:latest) — the application container running the web GUI, API, and MCP proxy engine.
PostgreSQL (ghcr.io/railwayapp-templates/postgres-ssl) — stores users, MCP server configs, namespaces, endpoints, and API keys. Requires a persistent volume at /var/lib/postgresql/data.

No external dependencies are required. Both services communicate over Railway's private network — no database ports are exposed to the internet unless you explicitly enable the TCP proxy.

Deployment Dependencies

Implementation Details

MetaMCP service variables:

Variable	Value	Notes
`APP_URL`	`https://${{RAILWAY_PUBLIC_DOMAIN}}`	Public URL. CORS enforced on this URL only.
`DATABASE_URL`	`postgresql://postgres:${{Postgres.PGPASSWORD}}@${{Postgres.PGHOST}}:${{Postgres.PGPORT}}/railway`	Auto-configured. Do not edit.
`BETTER_AUTH_URL`	`https://${{RAILWAY_PUBLIC_DOMAIN}}`	Must match APP_URL. Session cookies and redirects.
`BETTER_AUTH_SECRET`	`${{secret(32)}}`	Signs auth tokens. Do not change after first deploy.
`ENCRYPTION_KEY`	`${{secret(32)}}`	Encrypts API keys/credentials. Do not change after first deploy.
`NODE_ENV`	`production`	Leave as production.
`LOG_LEVEL`	`warn`	Options: error, warn, info, debug.

Postgres service variables:

Variable	Value
`PGDATA`	`/var/lib/postgresql/data`
`PGPORT`	`5432`
`POSTGRES_DB`	`railway`
`POSTGRES_USER`	`postgres`
`POSTGRES_PASSWORD`	`${{ secret(32, "a-zA-Z") }}`
`SSL_CERT_DAYS`	`820`
`RAILWAY_DEPLOYMENT_DRAINING_SECONDS`	`30`

Remaining Postgres variables (PGHOST, PGUSER, PGDATABASE, PGPASSWORD, DATABASE_URL, DATABASE_PUBLIC_URL) are auto-references to the values above. Do not edit.

First-Time Setup

Deploy the template. Railway auto-generates secrets and provisions Postgres.
Wait for both services to show "Online."
Visit your app URL (e.g. https://metamcp-production-XXXX.up.railway.app).
Register the first account. No default admin — the first user you create is your admin.
Go to API Keys in the sidebar to generate a key for connecting MCP clients.

Connecting MCP Clients

Claude Desktop — add this to your Claude Desktop config:

{
  "mcpServers": {
    "MetaMCP": {
      "command": "npx",
      "args": ["-y", "@metamcp/mcp-server-metamcp@latest"],
      "env": {
        "METAMCP_API_KEY": "",
        "METAMCP_API_BASE_URL": "https://your-railway-url.up.railway.app"
      }
    }
  }
}

Cursor / Streamable HTTP clients — point directly to your endpoint: https://your-railway-url.up.railway.app/metamcp//mcp

Adding OIDC / SSO

MetaMCP supports OpenID Connect for enterprise SSO, working alongside default email/password auth. The setup is the same for any provider (Google, Azure AD, Okta, Keycloak, Auth0, Authentik):

Create an OAuth/OIDC application in your identity provider.
Set the redirect URI to https:///api/auth/callback/oidc
Add these variables to the MetaMCP service:

Variable	Example (Google)
`OIDC_CLIENT_ID`	Your OAuth client ID
`OIDC_CLIENT_SECRET`	Your OAuth client secret
`OIDC_DISCOVERY_URL`	`https://accounts.google.com/.well-known/openid-configuration`
`OIDC_AUTHORIZATION_URL`	`https://accounts.google.com/o/oauth2/v2/auth`
`OIDC_PROVIDER_ID`	`google`
`OIDC_SCOPES`	`openid email profile`
`OIDC_PKCE`	`true`

Redeploy. A "Login with OIDC" button appears on the login page.
Go to Settings inside MetaMCP to control whether email/password registration stays enabled alongside SSO.

Updating MetaMCP

Go to MetaMCP service → Settings → Docker image section. If Railway detects a newer image digest, click Update to redeploy. You can also enable automatic image updates with a maintenance window in the service settings.

Troubleshooting

CORS blocked / blank page: Browser URL doesn't match APP_URL. If using a custom domain, update both APP_URL and BETTER_AUTH_URL to match.

Auth errors or can't register: Check that BETTER_AUTH_SECRET and ENCRYPTION_KEY are not empty strings. Both must contain actual secret values.

Database connection errors: Verify Postgres is online and check MetaMCP deploy logs for connection errors.

OIDC login fails: Redirect URI must match exactly: https:///api/auth/callback/oidc. Ensure OIDC_AUTHORIZATION_URL is set — MetaMCP doesn't fully auto-discover endpoints from the discovery URL alone.

Why Deploy MetaMCP 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 MetaMCP 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.