Railway Sandbox MCP

A small remote MCP server that exposes Railway Sandboxes as a development execution environment.

The intended loop is:

ChatGPT -> remote MCP /mcp -> Railway Sandbox MCP -> Railway SDK -> Railway Sandbox -> git / PHP / Composer / Artisan / npm / tests

This keeps development infrastructure separate from the application repositories being worked on.

Tools

Related MCP server: AICre8 MCP Server

Requirements

• Node.js 22+

• A Railway project/environment with Sandbox access

• A Railway project token or account API token with access to that environment

• An MCP client that supports remote Streamable HTTP

Environment

Copy .env.example and configure MCP_AUTH_TOKEN, RAILWAY_TOKEN, RAILWAY_ENVIRONMENT_ID, and optionally ALLOWED_HOSTS. PORT is supplied by Railway. Do not commit real credentials.

Run locally

npm install
npm run check
npm run test
npm run build
MCP_AUTH_TOKEN=change-me RAILWAY_TOKEN=... RAILWAY_ENVIRONMENT_ID=... npm start

The MCP endpoint is http://localhost:3000/mcp and the health endpoint is http://localhost:3000/health.

Persistent repository Sandboxes

The repository-aware workflow uses one persistent Railway Sandbox per repository. The Sandbox survives MCP process restarts and is discovered again with Sandbox.list() and Sandbox.connect().

repository -> repository_prepare
                 |
                 +-> existing usable Sandbox -> reconnect -> synchronize -> checkout issue branch
                 |
                 +-> no usable Sandbox -> create -> install toolchain -> clone -> persist marker -> checkout

The development template provisions Git, Node.js 22, PHP 8.4, and Composer 2. The repository marker is /root/.railway-sandbox-mcp/repository.json and contains repository metadata plus the Sandbox ID. Credentials are never stored there.

Each issue uses a normal Git branch inside the same persistent repository worktree. Before preparing an issue, the manager fetches remote state, resets the worktree to origin/HEAD, removes untracked files, and checks out the requested branch. If that branch does not exist remotely, it is created from the default branch.

A repository-specific in-process lock prevents concurrent preparation of the same repository within one MCP instance. It is not distributed across multiple MCP replicas.

Repository Sandboxes are persistent by default. An explicit idle timeout can still be supplied, subject to Railway plan limits.

Development loop

repository_prepare -> persistent Sandbox -> issue branch
       -> inspect -> implement -> test -> lint/static analysis -> diff
       -> commit -> push -> GitHub Actions
       -> merge, or diagnose root cause and fix
       -> next issue -> same Sandbox

The high-level repository_prepare tool is the preferred entry point for repository development. The lower-level sandbox_* tools remain available for direct Sandbox administration and troubleshooting.

Security model

• The MCP endpoint requires a bearer token before MCP requests reach the handler.

• Railway credentials remain only in the MCP service environment.

• Sandbox command execution occurs inside Railway Sandbox infrastructure.

• Command execution and file writes have bounded input sizes/timeouts.

• Repository markers contain no credentials.

• Repository preparation uses isolated network mode by default unless private Railway service access is explicitly requested.

Deployment

Create a Railway service from this repository, configure the required environment variables, generate a public domain, and use the resulting /mcp endpoint as the remote MCP endpoint. Set ALLOWED_HOSTS to the generated hostname when host allow-listing is desired.