Railway MCP Server: Install, Tools and Security

Railway's MCP server lets an AI agent create projects, deploy templates, pull variables and redeploy services on Railway. It no longer ships as a standalone package. The old @railway/mcp-server repo is archived, and the server is now built into the Railway CLI as railway mcp. Run railway mcp install to configure your agent. We checked Railway's docs and repos on 31 October 2026.

Quick facts

Where the old server went

If you found a Railway MCP guide that says npx -y @railway/mcp-server, it is out of date. The GitHub repo railwayapp/railway-mcp-server is archived, and its README now starts with "@railway/mcp-server is deprecated". It says the npm package no longer contains the TypeScript server. It is a compatibility shim that launches railway mcp, and it exits with migration steps if the CLI is missing.

That matters for two reasons. Old configs keep working only if the Railway CLI is installed. And the tool list changed: the original server and the hosted one are not the same product, so a prompt that depended on an old tool name may not map one to one.

The migration is short:

1. Install or upgrade the CLI (bash <(curl -fsSL https://railway.com/install.sh), from the README).
2. Run railway mcp install.
3. Delete any old entry that runs npx -y @railway/mcp-server.

There is also a community project, jason-tan-swe/railway-mcp, which describes itself as unofficial. We do not cover it here beyond noting it exists.

What it lets an agent do

Railway describes the server as one that lets assistants create projects, deploy templates, manage environments, pull variables and redeploy services. The docs give example prompts that show the range:

• "Create a Next.js app in this directory and deploy it to Railway. Also assign it a domain."
• "Deploy a Postgres database."
• "Pull environment variables for my project and save them to a .env file."
• "Redeploy my api service in the production environment."
• "Use the railway agent to figure out why my backend service is crashing on deploy."

The last one uses a tool called railway-agent, which hands a plain-language request to Railway's own AI agent for multi-step work such as log analysis and service configuration. That makes this server unusual: part of the work is done by a second agent on Railway's side, not by your agent alone.

Two ways to connect, one server

The server runs on Railway's infrastructure at mcp.railway.com. The docs give two routes to it.

Through the CLI (the default). railway mcp connects your editor to the hosted server over stdio. It attaches credentials from your railway login session to each request, and it refreshes your access token when needed. The editor config holds no long-lived Railway credential. If a call says you are not authenticated, run railway login and the next call picks it up without a restart.

With OAuth. Editors that support OAuth connect directly to https://mcp.railway.com. No CLI is needed. You choose which workspaces and projects the client can reach, tokens are short-lived, and you can revoke them from your Railway account settings.

Which should you pick? If you already use the CLI, the default is simpler. If you want a narrow scope, or you work on a machine without the CLI, use OAuth.

Install it in each agent

The cleanest route is Railway's own installer. It detects supported tools and merges the Railway entry into their configs without removing other servers.

railway mcp install

To target one agent, pass --agent:

railway mcp install --agent claude-code
railway mcp install --agent cursor --agent codex

Add --oauth to configure the direct HTTP endpoint instead of the CLI connection, or --local for the local server. The supported --agent values are claude-code, cursor, factory-droid, copilot, codex, opencode, pi and antigravity.

There is also a one-command bootstrap that installs the CLI and configures skills, MCP and authentication together: railway setup agent, with --oauth for the OAuth route.

Claude Code

Vendor route: railway mcp install --agent claude-code. The installed entry is command: "railway" with args: ["mcp"], or, for OAuth, type: "http" with url: "https://mcp.railway.com".

If you prefer to add it by hand, these lines are our adaptation of Claude Code's claude mcp add syntax, not text from Railway:

claude mcp add --transport stdio railway -- railway mcp
claude mcp add --transport http railway https://mcp.railway.com

Codex

Vendor route: railway mcp install --agent codex. In config.toml the CLI form is command = "railway" with args = ["mcp"], and the OAuth form is url = "https://mcp.railway.com". Our hand-written equivalent:

[mcp_servers.railway]
command = "railway"
args = ["mcp"]

For the OAuth form, run codex mcp login railway after adding the URL (our adaptation, from the Codex docs).

Cursor

Vendor route: railway mcp install --agent cursor. The entry has the same shape as the standard mcpServers JSON: a command and args, or a url for OAuth.

{
  "mcpServers": {
    "railway": { "command": "railway", "args": ["mcp"] }
  }
}

Antigravity and Gemini CLI

Antigravity is in the installer's list. For it, Railway says the entry is written to ~/.gemini/config/mcp_config.json, and there is a separate Antigravity plugin that installs the Railway skill and MCP server together. The OAuth form uses url there, which Antigravity's docs accept alongside serverUrl.

Gemini CLI is not on Railway's list. If you still use it, add the same command and args entry to your settings.json under mcpServers. That line is our adaptation. Remember that Gemini CLI is now for Code Assist enterprise customers, and individuals moved to Antigravity CLI on 18 June 2026.

OpenCode

Vendor route: railway mcp install --agent opencode. It writes a local entry with command: ["railway", "mcp"] and enabled: true, or a remote entry with url for OAuth.

{
  "mcp": {
    "railway": {
      "type": "local",
      "command": ["railway", "mcp"],
      "enabled": true
    }
  }
}

Other agents

GitHub Copilot, Factory Droid and Pi are also in the installer. See our guide to MCP clients for how each agent names the same fields.

The tools it exposes

The hosted server at mcp.railway.com exposes a short list:

accept-deploy commits staged changes and deploys. The docs mark it destructive, and say clients prompt for confirmation. delete-feature-flag is described as admin and destructive.

The short list tells you the design. Most of the real work, such as logs and service configuration, goes through railway-agent. Your agent states the goal and Railway's agent does the steps.

Local mode and its wider tool set

For machines that cannot reach mcp.railway.com, such as egress-restricted networks, the CLI ships an in-process server. Start it with railway mcp local, or write the config with railway mcp install --local.

It talks directly to the Railway API using your CLI credentials, marks destructive tools with protocol hints, and returns a preview before it requires confirm: true. Its tool set is much larger than the hosted one:

This is the version to choose if you want your own agent to do the stepwise work with direct tools. The cost is that more of those tools can change or remove things, so approval discipline matters more.

Security and permissions

Railway's docs give four points, and we agree with them:

• CLI authentication. railway mcp reads and refreshes your login credentials. Your editor config does not hold a long-lived Railway credential.
• OAuth scoping. You choose the workspaces and projects. Tokens are short-lived and revocable.
• Destructive actions are marked at the protocol level. A client that honors the hint will ask first.
• Project tokens are not accepted. The server wants a user identity for billing and audit.

The docs also tell you to review what the model asks for, especially redeploy, accept-deploy and railway-agent, plus remove_service, delete_domain, remove_tcp_proxy, remove_bucket and remove_volume in local mode. They suggest limiting use to non-critical environments where possible.

Our additions, from general MCP practice:

1. Do not set always-allow on this server. A deploy or a removed volume is hard to take back.
2. Use OAuth with a narrow project scope when an agent only needs one app.
3. Treat environment variables as sensitive. "Pull environment variables" brings secrets into the conversation. Anything in the chat can reach the model provider.
4. Watch for injected text in logs. A log line is untrusted input, and an agent reading logs through get_logs or railway-agent may read text an attacker planted.

Limits and gotchas

• Two tool sets. Hosted and local differ. A prompt that works in one may name a tool that does not exist in the other.
• CLI version. The default connection needs CLI 5.44.0 or later. On earlier versions, railway mcp starts the local in-process server instead, which has a different tool set.
• Stale configs. Configs that run railway mcp proxy still work and connect to mcp.railway.com. Re-run railway mcp install to update them to the bare railway mcp form.
• Old guides. Many blog posts still show the npm package. Skip them.
• Feature requests go to Railway's Central Station post linked from the docs. We did not read the issue tracker for this page.

Alternatives

Railway's skills page says agent skills for Railway work with Claude Code, Codex, OpenCode and Cursor. A skill is a markdown file, so it costs less context than a tool list. You can use both. Our skills hub explains the format.

Our take

We did not deploy anything with this server for this page. This is a reading of Railway's documentation and repos.

The useful lesson is about how to read a dead repo. The archived railway-mcp-server still ranks and still shows 190 stars, but the maintained path is the CLI. If you are choosing today, you are choosing the CLI's MCP, and you are choosing between a short hosted tool list and a long local one.

For most people we would start with the default CLI connection and the hosted server. It keeps credentials out of editor files, and it pushes multi-step work to Railway's own agent, which knows the platform. If you want your agent to run every step itself, or you are on a locked-down network, local mode is there.

The caution is the same as for any deploy tool. The hosted server can redeploy and accept deploys. Keep it off production until you trust your approval habits, and keep a human on the confirm prompt.

A short setup checklist

1. Install the CLI and run railway login.
2. Check railway --version is 5.44.0 or later.
3. Run railway mcp install --agent <yours>.
4. Remove any old npx -y @railway/mcp-server entry.
5. Restart the agent and list tools.
6. Ask for whoami and list-projects first.
7. Leave deploys on manual approval.

Frequently asked questions

Is the Railway MCP server still a separate npm package?

No. @railway/mcp-server is deprecated and only forwards to railway mcp. The server now lives in the Railway CLI.

How do I add Railway MCP to Claude Code?

Install the CLI, run railway login, then railway mcp install --agent claude-code.

Do I need the CLI to use it?

Not with OAuth. Editors that support it connect directly to https://mcp.railway.com.

Can it delete things?

Yes. Destructive tools are marked, and the docs tell you to review redeploy, accept-deploy and railway-agent.

Does it accept project tokens?

No. A user identity is required for billing and audit.