How to connect Railway MCP with Codex

Get the current authenticated Railway user's profile information

List the Railway workspaces the current user belongs to. Use a workspace ID with create-project to choose where a project is created.

List all Railway projects accessible to the authenticated user

Create a new Railway project

Create a new service from a GitHub repository and trigger its first deployment. The repo must be one the authenticated user has connected via GitHub. Returns the new service; use get-status or list-deployments to follow the deploy. Before calling this tool you MUST have a GitHub repo to deploy. If the user has not provided one, do not guess — first ask them which GitHub repo to deploy (in 'owner/name' form). If they don't have a repo yet, offer to help create one: if you have tools available to create a GitHub repository (e.g. a GitHub MCP server or `gh` CLI), offer to scaffold and push one for them; otherwise point them to create a repo on GitHub and share its 'owner/name'. Only call this tool once a concrete repo has been confirmed.

Create a new service in a project from a Docker image, or an empty service to configure later (e.g. before setting variables and attaching a source). Public images only: credentials for a private registry are not accepted here — the user sets them on the service in the Railway dashboard. Pass staged: true to stage the service in one environment instead of applying it live — it then only becomes real when the staged changes are committed with accept-deploy. To create a service from a GitHub repository, use create-deployment instead.

Update a service's configuration: build/start/pre-deploy commands and pre-deploy timeout, builder, healthcheck, sleep mode, root directory, cron schedule, Dockerfile path, restart policy, config file path, watch patterns, replicas per region, resource limits, deployment overlap/draining, outbound IPv6, and the private network endpoint name. Only the fields you pass are changed. Config changes apply on the service's next deployment (use redeploy to apply immediately); regions and limits scale the running deployment right away, and privateNetworkEndpoint is committed to the environment and redeploys the service. Pass staged: true to stage the update in one environment's pending changes instead of writing it to the service — it then applies when the staged changes are committed with accept-deploy. Source changes are not handled by this tool (use connect-service-source), and private registry credentials are set by the user in the Railway dashboard.

Permanently delete a service: its deployments stop and are removed, along with its domains, variables and deployment triggers. Any volume attached to it is detached and kept — delete-volume removes a volume and its data. By default the service is deleted in every environment that is not a fork; pass an environmentId to delete it in that one environment only. Pass staged: true to stage the removal in one environment instead of applying it live. A service whose creation is itself still staged is taken back out of the pending changes instead. This cannot be undone.

Create a Railway Function: a service that runs one file of TypeScript on the Bun runtime, with no repository, Dockerfile or build step. Use this for webhook receivers, small HTTP APIs, cron jobs and scripts. Pass the complete code — a function with no code deploys nothing. Applies live by default, which deploys the function immediately. Pass staged: true with an environmentId to stage it in that environment's pending changes instead, in which case nothing deploys until the staged changes are committed with accept-deploy. For a service built from a repository use create-deployment, and for one from a Docker image use create-service. To change a function's code afterwards use update-function-source-code; for its other settings (variables, cron schedule, healthcheck) use set-variables and update-service. Writing function code: - One file, TypeScript or TSX. The runtime writes it to `index.tsx` and runs it with Bun — Python, Go, Ruby and other languages will not run. For those, use create-service with an image, or create-deployment from a repo. - Imports are allowed. The runtime scans them, generates a package.json and installs with Bun, including versioned specifiers like `hono@4` and `zod@3`. Do not reference local files other than this one. - An HTTP service must listen: call `Bun.serve`, or default-export a fetch handler or Hono app. Read the port from `Bun.env.PORT`. Use generate-domain to give it a public URL. - If it is not an HTTP service, do not start a server. Write a script; it runs to completion. - Do not schedule work with a top-level `setInterval` — set a cronSchedule with update-service instead. - Prefer Bun globals over Node APIs: `Bun.env` for variables, `Bun.file`/`Bun.write` for file I/O, `Bun.sql` for Postgres, `Bun.s3` for object storage. The function filesystem is not durable — persist to a database or object storage. - Top-level await is available. Await every async call. - JSX needs the pragma, e.g. `/** @jsx jsx */` with `/** @jsxImportSource hono/jsx */`. - Send complete, working code. Placeholders and elided bodies get deployed as written.

Replace a Railway Function's source code. Send the complete file — this overwrites the function's code, it does not patch it, so anything you leave out is gone. Read the current code with get-function-source-code first if you are modifying rather than rewriting. Applies live by default, which deploys the new code immediately. Pass staged: true to stage it in the environment's pending changes instead, in which case the current code keeps running until the staged changes are committed with accept-deploy. Updates one environment: the one you name, or the default environment. Code is the thing a function is, and a live update deploys it, so this does not fan out across every environment the way update-service does — call it per environment if you need that. For a function's other settings (variables, cron schedule, healthcheck, domains) use set-variables, update-service and generate-domain. For a service built from a repo or image, this is the wrong tool: use connect-service-source or redeploy. Writing function code: - One file, TypeScript or TSX. The runtime writes it to `index.tsx` and runs it with Bun — Python, Go, Ruby and other languages will not run. For those, use create-service with an image, or create-deployment from a repo. - Imports are allowed. The runtime scans them, generates a package.json and installs with Bun, including versioned specifiers like `hono@4` and `zod@3`. Do not reference local files other than this one. - An HTTP service must listen: call `Bun.serve`, or default-export a fetch handler or Hono app. Read the port from `Bun.env.PORT`. Use generate-domain to give it a public URL. - If it is not an HTTP service, do not start a server. Write a script; it runs to completion. - Do not schedule work with a top-level `setInterval` — set a cronSchedule with update-service instead. - Prefer Bun globals over Node APIs: `Bun.env` for variables, `Bun.file`/`Bun.write` for file I/O, `Bun.sql` for Postgres, `Bun.s3` for object storage. The function filesystem is not durable — persist to a database or object storage. - Top-level await is available. Await every async call. - JSX needs the pragma, e.g. `/** @jsx jsx */` with `/** @jsxImportSource hono/jsx */`. - Send complete, working code. Placeholders and elided bodies get deployed as written.

Get a Railway Function's source code and runtime in an environment. Works for a function that is deployed and for one that exists only as a staged change — `code` is whichever is current, `deployedCode` is what is actually running, and `staged` says whether a commit is pending. Read this before update-function-source-code, which replaces the whole file. For a function's other configuration use get-service-config, and for its variables use list-variables. If environmentId is omitted, the default environment is used.

List the ids and names of all services and environments in a Railway project. Prefer describe-environment for what is actually in an environment: it includes volumes, buckets, deployments and staged changes.

Inventory of everything in a Railway environment — services, volumes, buckets, shared variable names — with staged changes applied. Each resource carries a `state`: live, staged-create (exists only in the pending patch), staged-delete, or live-with-staged-changes. Includes each service's source, regions, replicas, cron, volume mounts and latest deployment, and a `staged` summary of the pending patch. Pass `region` to keep only resources in that region. For per-field staged diffs use get-staged-changes; for one service's full config use describe-service; for runtime health use environment-status. If environmentId is omitted, the production environment is used.

Everything about one service in an environment: its config with staged changes applied (source, build, deploy, networking, volume mounts), the per-field staged changes pending on it, mounted volumes, live domains and TCP proxies, the latest deployment, and its tracing state. `state` says whether the service is live, staged-create, staged-delete, or live-with-staged-changes. Variable names are listed but values are not — use list-variables for values. If environmentId is omitted, the production environment is used.

Show the changes staged in a Railway environment that accept-deploy would commit: per resource (service, volume, bucket, group) the action — create, delete, update — and each changed field with its live and staged value. Variable values and registry credentials are redacted to names. Also reports whether the patch is destructive and whether a commit is already applying. Review this before calling accept-deploy. If environmentId is omitted, the production environment is used.

Prefer describe-service: it applies the staged changes onto the live config for you and adds mounted volumes, domains, TCP proxies and the latest deployment. Get a service's configuration in an environment: source (repo/image), build settings, deploy settings (start command, healthcheck, replicas, cron, restart policy), networking, and volume mounts. `config` is what is live; `staged` holds the not-yet-deployed changes for this service, or null when nothing is staged. A service created with `staged: true` has an empty `config` until accept-deploy commits it. Variable names are listed but values are not included — use list-variables for values. If environmentId is omitted, the production environment is used.

Get resource usage metrics (CPU, memory, disk, network) for a service, summarized as current/average/min/max over a time window. Defaults to CPU_USAGE and MEMORY_USAGE_GB over the last hour. If environmentId is omitted, the production environment is used.

List all environment variables for a service, fully rendered (reference variables like ${{Postgres.DATABASE_URL}} are resolved). With a Railway session or API token, values are returned in plaintext and may contain secrets. Connected OAuth apps receive variable names only. Sealed variables are always listed by name with no value — they are set, but nobody can read them back, so never recreate one. If environmentId is omitted, the production environment is used.

Set one or more environment variables on a service (or environment-wide shared variables when serviceId is omitted). Existing variables with the same name are overwritten; others are left unchanged. Reference syntax like ${{Postgres.DATABASE_URL}} is supported. Affected services are redeployed unless skipDeploys is true. Pass staged: true to stage the variables in the environment's pending changes instead of setting them live — nothing is written or redeployed until the staged changes are committed with accept-deploy.

Create a persistent volume in a project and optionally attach it to a service at a mount path. The attach and redeploy are committed together so the service comes up with the mount applied. Pass staged: true to stage the volume in one environment instead of provisioning it live.

Update a volume's name, mount path, or which service it is attached to. Pass serviceId with mountPath to attach or move the volume; pass serviceId: null to detach it from its service, keeping the data. Every mount change redeploys the affected service so it takes effect. Only the fields you pass are changed. Pass staged: true with an environmentId to stage the mount change in that environment's pending changes instead of applying it live; the volume's name is not environment-scoped and cannot be staged.

Permanently delete a volume and its data. The volume is unmounted from any service it is attached to (redeploying that service). By default it is removed from every environment; pass an environmentId to remove it from that one environment only. Pass staged: true to stage the removal in one environment instead of applying it live. Deleting from every environment is irreversible.

Create an S3-compatible object storage bucket in a project and provision it in an environment. Default region is sjc. Pass staged: true to stage the bucket in the environment's pending changes instead of provisioning it live — it then only becomes real when the staged changes are committed with accept-deploy.

Rename a bucket. The name is project-wide (not per environment) and takes effect immediately. Reference variables address the bucket by name (${{BucketName.ACCESS_KEY_ID}} and so on), so after a rename update any service variables that reference the old name and redeploy those services. The S3 bucket name and credentials do not change.

Permanently delete an object storage bucket and its contents. By default it is removed from every environment it is provisioned in; pass an environmentId to remove it from that one environment only. Pass staged: true to stage the removal in one environment instead of applying it live. Deleting from every environment is irreversible.

Get the S3-compatible connection details for a bucket in an environment: endpoint, bucket name, region, URL style, access key and secret. With a Railway session or API token the access key and secret are returned in plaintext; connected OAuth apps receive the connection details only. Services in the same project should normally not copy these values but reference them as variables (${{BucketName.ENDPOINT}}, ${{BucketName.BUCKET}}, ${{BucketName.REGION}}, ${{BucketName.ACCESS_KEY_ID}}, ${{BucketName.SECRET_ACCESS_KEY}}), which also survive a credential reset. To rotate the credentials use reset-bucket-credentials. If environmentId is omitted, the production environment is used.

Regenerate the S3-compatible credentials for a bucket in an environment and return the new ones. The current access key stops working immediately; bucket data is not affected. Every client using the old key needs the new values, and services that reference the bucket through variables keep the old key until redeployed — the result lists them so you can follow up with redeploy. With a Railway session or API token the new access key and secret are returned in plaintext; connected OAuth apps receive the connection details only. If environmentId is omitted, the production environment is used.

List all domains (Railway-generated service domains and custom domains) for a service in an environment. If environmentId is omitted, the production environment is used.

Get detailed status for one domain on a service, by hostname, URL, or domain ID: required DNS records and whether they currently match, ownership verification, certificate status, and any certificate error. Use list-domains first if you do not know which domains exist. If environmentId is omitted, the production environment is used.

Expose a service publicly. Without `domain`, generates a Railway *.up.railway.app service domain (if the service already has domains, they are returned instead of creating another). With `domain`, attaches a custom domain you own and returns the DNS records the user must create for it to verify. If environmentId is omitted, the production environment is used.

Repoint or rename an existing domain on a service. targetPort changes which container port the domain routes to (for a service listening on several ports). subdomain renames a Railway-generated service domain to <subdomain>.up.railway.app; custom domains cannot be renamed — delete the old one and add the new one with generate-domain. The change applies live. If environmentId is omitted, the production environment is used.

Remove a domain from a service: a Railway-generated *.up.railway.app service domain or a custom domain. Requests to that hostname stop being routed to the service as soon as the removal applies. Pass staged: true to stage the removal of a service domain in the environment's pending changes instead of applying it live. Custom domain removal always applies live. If environmentId is omitted, the production environment is used.

Request a new TLS certificate for a custom domain whose issuance failed. Use domain-status first: it reports the certificate error and whether a retry can help (certificate.retryable). A retry cannot succeed until the domain's DNS records point at Railway. Railway-generated service domains have their certificates managed by Railway and need no retry. If environmentId is omitted, the production environment is used.

Search the Railway documentation (docs.railway.com) for features, configuration, guides, and tutorials. Returns matching sections with URLs — use fetch-docs to read a full page.

Fetch the full markdown content of a Railway documentation page by URL or slug (e.g. 'https://docs.railway.com/quick-start' or 'reference/variables'). Use search-docs first to find the right page.

Search the Railway template marketplace by name, description or keyword — databases (postgres, mysql, mongo, redis, clickhouse), their high-availability variants, and application templates. Returns published templates ranked by relevance. Use describe-template to read a result's inputs before deploying it with deploy-template.

Read one Railway template: its name, description, README, the services it creates, every env-var input it takes (which are required and which are optional), and — for clustered database templates like postgres-ha — the HA topology counts deploy-template can size. Call this before deploy-template so required inputs are collected from the user rather than guessed.

Deploy a Railway template into a project — a database (postgres, mysql, redis, mongo), a clustered high-availability database, or an application template. Creates every service the template declares, wired together, and deploys them. Pass staged: true to stage them for the user to review instead. Call describe-template first: it lists the env-var inputs the template requires and the HA counts it accepts. This tool does not take secrets: never ask the user for, or pass, a password, API key, token or other credential. Use `variables` only for non-secret settings such as names, regions or public URLs. Omit optional inputs to keep the template's defaults — database passwords and other secrets the template declares as generated are created by Railway at deploy time. If a template requires a secret the user must supply, do not deploy it here: give the user the template's dashboard link (in the error this tool returns) so they enter it there.

List Railway feature flags (Signals) for a project and optionally the parent workspace. Project flags are editable with admin access; workspace flags are read-only from project context.

Get a Railway feature flag (Signal) by name for a project or its parent workspace scope.

Create a project-scoped feature flag or update its default value, optionally replacing its targeting rules. Use list-feature-flags and get-feature-flag to inspect existing flags first.

Delete a project-scoped feature flag. Workspace-scoped flags cannot be deleted from project context.

List recent deployments for a Railway project, optionally filtered by environment, service, or status. Returns the most recent first, with who triggered each one, its regions, and whether it can be redeployed or rolled back.

Prefer describe-environment: it also lists services that exist only in the staged patch, unattached volumes, and each resource's staged state. Get the deployment status of a Railway project environment. Returns project + environment metadata, whether the environment has undeployed staged changes, the environment's buckets, and for each live service its latest deployment status, replica count, cron schedule, and attached volumes. Also includes `pendingWork`: the environment's pending (staged/applying) work that is not live yet — a staged patch or a commit still rolling out (poll until the operation leaves this list). If environmentId is omitted, the project's `production` environment is used when present, otherwise the oldest environment.

Get logs from Railway — deploy (runtime), build, http (proxy request), network-flow (per-connection egress/ingress) and dns (name lookups) streams. Pass a deploymentId to read one deployment, or serviceId (+ optional environmentId) to read the service's logs across its recent deployments in that environment. Use `types` to choose which streams to return (default: ['deploy']).

List distributed traces of an environment, newest first — one row per request that has at least one span matching the filter. Use it to find slow or failing requests across services, then call get-trace with a traceId for the spans. Defaults to the last hour. If environmentId is omitted, the production environment is used.

Get the spans of one distributed trace, as a tree from the edge down through every service that handled the request. Find trace IDs with list-traces. Only spans belonging to the environment are returned. If environmentId is omitted, the production environment is used.

Read the tracing settings of an environment's services: whether each is traced and its auto-instrumentation switch. Pass serviceId for one service, omit it for every service in the environment. Tracing is set per service and environment; if environmentId is omitted, the production environment is used. Change it with set-service-tracing; use list-traces to see whether spans are arriving.

Report what one service's own instrumentation covers: the spans its app exported in the window, by span kind, by the remote system they name (database, cache, queue, RPC or HTTP client) and by the instrumentation library that emitted them. Use it after instrumenting a service to prove that its database queries and outgoing calls produce spans, not just its incoming requests. Defaults to the last hour. If environmentId is omitted, the production environment is used.

Enable or disable tracing and auto-instrumentation for one service in one environment, each independently. tracingEnabled switches whether the edge traces requests to the service and whether its next deploy gets the OpenTelemetry exporter variables. autoInstrumentationEnabled switches eBPF (OBI) instrumentation of the service's processes, which only takes effect while tracing is enabled. No redeploy is needed for the edge or auto-instrumentation. If environmentId is omitted, the production environment is used. Read the current state with get-tracing.

Get HTTP request counts for a service, bucketed over time and split by response status class (2xx/3xx/4xx/5xx). Use this for traffic volume and the mix of successful versus failing responses. Defaults to the last hour. If environmentId is omitted, the production environment is used.

Get the HTTP error rate for a service over time — the share of requests answered with a 5xx. Use this for reliability and to locate error spikes. 4xx responses are reported separately and are not counted in the rate, since a 404 or a rejected payload is usually the caller's doing. Defaults to the last hour. If environmentId is omitted, the production environment is used.

Get HTTP latency percentiles (p50, p90, p95, p99) for a service, bucketed over time, in milliseconds. Use this for performance and to find slow requests. Defaults to the last hour. If environmentId is omitted, the production environment is used.

Re-run the most recent deployment of a service in a given environment, reusing that deployment's existing build. Pass deploymentId to redeploy an earlier deployment's build instead (list-deployments has the ids). Only works on a service that has already deployed in that environment — check with list-deployments if you are unsure. This does NOT give a service its first deployment: if it has never deployed, nothing here can deploy it — use the Railway CLI (`railway up --project <id> --environment <id> --service <id>`), or attach a GitHub repo to the service in the dashboard. create-deployment would build a separate new service from a GitHub repo rather than deploying this one.

Restart a service's running deployment in place — the containers restart without rebuilding the image, and no new deployment is created (use redeploy for a fresh build copy). Restarting causes brief downtime; do NOT restart database services (Postgres, MySQL, Redis, MongoDB) or services with attached volumes unless the user explicitly asked, as it can interrupt in-flight queries and transactions.

Get the AI-generated diagnosis for a failed deployment: root cause category, analysis, and suggested fixes, along with deployment context (service config, source repo, branch, commit, PR, failure stage and error). Diagnoses run automatically when a deployment fails — if one isn't available yet, fall back to get-logs to inspect the failure directly.

Health overview of every service in an environment in one call: current LIVE (settled) deployment state, replica status, recent failures, unresolved warnings/criticals, and cron execution results. Also includes `pendingWork`: the environment's pending (staged/applying) work that is not live yet — a staged patch or a commit still rolling out (poll until the operation leaves this list). By default only services with issues are returned — pass includeSuccessful to see everything. For error details, follow up with get-logs on the deployment IDs returned here.

List the TCP proxies exposing a service over the public internet on a raw TCP port (e.g. a database's public endpoint). Returns the public endpoint (host:port) and the application port each proxy forwards to.

Expose a service on the public internet over a raw TCP port (e.g. make a database reachable externally). Creates a TCP proxy forwarding a public endpoint to the given application port, applied through the environment config so the service redeploys with it active. Pass staged: true to stage the proxy in the environment's pending changes instead — it is only provisioned, and only gets a public endpoint, once the staged changes are committed with accept-deploy. A service can have at most one TCP proxy.

Remove a service's TCP proxy, taking its public endpoint offline. Anything connecting through that endpoint (e.g. external database clients) loses access. Pass staged: true to stage the removal in the environment's pending changes instead — that is also how a proxy that is itself only staged gets dropped again.

Attach a source to an existing service: a GitHub repository (deploys on push, builds immediately) or a Docker image. This is how a service that has never deployed gets its first deployment, and how an existing service's source is switched. Provide exactly one of repo or image. Pass commitSha with repo to pin the service to one commit instead of following the branch. Images must be public: credentials for a private registry are not accepted here — the user sets them on the service in the Railway dashboard. By default it applies to the service in all environments; pass staged: true with an environmentId to stage the source in that one environment's pending changes instead, in which case nothing builds until the staged changes are committed with accept-deploy.

List a project's webhooks: for each, the URL Railway POSTs to, the deployment, monitor and volume-alert events that trigger it, whether it covers preview (PR) environments, the names of its custom headers (values are write-only), and its ID for update-webhook and delete-webhook.

Create a project webhook: Railway POSTs a JSON payload to the URL whenever one of the chosen deployment, monitor or volume-alert events happens in the project. Defaults to the deployment failure events (failed, crashed, out of memory) across regular and preview environments. This tool does not take custom headers or other secrets: if the endpoint needs an auth or signature header, the user adds it to the webhook in the Railway dashboard. Discord and Slack incoming-webhook URLs are detected and receive a formatted message. Use test-webhook first to check the URL accepts the payload.

Change a project webhook's URL, the events that trigger it, or whether it covers preview (PR) environments. Only the fields passed change; eventTypes replaces the whole set. Custom headers the user set in the Railway dashboard are kept as they are — this tool does not take header values or other secrets. Get the webhook ID from list-webhooks.

Delete a project webhook so Railway stops POSTing to its URL. Get the webhook ID from list-webhooks. This cannot be undone; create-webhook makes a new one.

POST a sample event payload to a URL and report the HTTP status it answered with, to check a webhook endpoint before creating or after updating a webhook. Pass a URL to try a new endpoint, or a webhookId to send to an existing webhook with its stored URL and any custom headers the user set on it in the dashboard. This tool does not take header values or other secrets. Nothing is stored. Discord and Slack incoming-webhook URLs receive a formatted message, like a real event would.

DESTRUCTIVE: Commits all staged changes in a Railway environment and triggers a deploy. Only use this when the user has explicitly confirmed they want to deploy.

Hand a multi-step task in one project environment to Railway's own AI agent, for work too open-ended for the direct tools: investigating a failing deploy across services, or planning and making a set of related changes. The agent reads the environment's config, logs, metrics and linked GitHub repository, and searches the web and Railway docs. It can also change the environment as the calling user: create, update and remove services, volumes, buckets and webhooks, set variables, restart services, deploy its staged changes, and open pull requests on the linked repository. Describe the task in plain language and say what it may change; do not put passwords, API keys or other secrets in the message. A call waits up to 4 minutes; if the agent is still working it returns early with a threadId — pass it back as threadId to continue the same conversation, which also works for follow-up questions. For a single read or change, use the direct tool instead (get-logs, set-variables, update-service and so on).