Cody De Arkland

Jun 26, 2026

Every (Agents) Connection to Railway

If it can't just fire up a browser and log in as you, how does an agent actually get in and use Railway? We've spent agents week talking about the different ways we've looked at making it easier. Everything from fully revamping setup, the CLI as their first tool, sandboxes for short-lived ephemeral work and agent actions (shoutout to our agents in the sandbox post, we added Droid from Factory and Cursor's agent yesterday.), and how we build the loop all the way from develop, to deployed, iterating, and debugging.

All of that only matters if the agent can get in at all. For a long time the dashboard and canvas were that front door, which is a great experience for a human but not for the agent/harness a user is throwing commands at to "go do the thing" (sans something like browser-use, but, you get my point). So we've spent a lot of effort over the past few months to make sure as many actions as safely possible are exposed in a way agents can consume.

Three paths in

The three connection patterns absolutely have some overlap, because ultimately the thing on the other end of the connection isn't always the same. Classic adage of "tool for the job." Sometimes the "thing" is a coding agent running on your laptop inside a project. Sometimes it's a hosted assistant with no access to your filesystem at all, relying instead on GitHub to pull down and take action. Sometimes it's even a script in CI that just needs a structured answer back.

Each of these has their own unique demands and expectations from tooling.

Local MCP runs on your machine through the Railway CLI. It's the default, configured via the automated setup flow, and the right call when "local state" matters: you just built an app, haven't pushed it to GitHub yet, and are running out of the directory you're standing in. Under the hood, the MCP drives API calls, falling back to CLI calls and the Railway Agent as needed. If you're driving agents locally, this ends up being the most successful path for you.

Remote MCP lives at mcp.railway.com and is a standard OAuth based MCP server. It stands on its own, talking straight to the Railway API with no local CLI to lean on, which matters because the systems reaching for it usually don't have one installed. It's very portable, able to run in hosted systems like ChatGPT or Claude.ai directly.

Beyond the MCP approach...

Railway CLI + Railway Agent is a different shape entirely. We've been hard at work over the last six months to cover as much of Railway's surface area as we can in an agent-friendly CLI. For the parts that there isn't, you hand the work to an agent-operator that understands the core of Railway and how to drive the outcome. It's only callable from the Remote MCP server, and we expose CLI commands (railway agent -p) that are consumable from the local MCP.

Install once, get local MCP

The recommended starting point is heading to agents.railway.com to grab the instructions (or asking your agent to ask railway.com where to configure the agent tools), and dropping the one-liner in your terminal:

curl -fsSL railway.com/agents.sh | sh

That installs the CLI, Railway's agent skills, and the MCP server, configuring the local MCP server by default in the agents it detects.

Why prefer the local MCP? The earlier reference to local file state is a big reason, but also from a friction standpoint it inherits your sign-in from the CLI directly. Once you've run railway login, the local MCP server reuses that exact authentication, the same token every other CLI command already uses. There's no second login, no token to paste into a config file, no OAuth round-trip for the agent to complete. There's nothing else to wire up, and your agent can start making structured tool calls against the important parts of Railway right away.

It also has the widest reach of the three doors, because of the combination of tool availability, local CLI access, and the Railway Agent access via the CLI. Past the basics like deploying and pulling logs, it can create services, manage variables and volumes, generate domains, scale, and read metrics. If the CLI can do it, the local MCP server is usually right behind it.

If you installed using the installation command above, everything is configured by default. If you haven't installed via that path (hi Homebrew), you can run railway setup agent to execute the same flow, or just land the MCP configuration with railway mcp install. This configures just the MCP piece for the coding tools it finds on your machine:

railway mcp install

That covers Claude Code, Cursor, Factory Droid, GitHub Copilot, OpenAI Codex, and OpenCode, merging the Railway entry into each tool's config without touching the other servers you've set up.

One housekeeping note while we're here. If you wired up Railway's MCP through an npx command at some point, that older path is deprecated. The server ships inside the CLI now, so railway mcp is the whole story, and re-running the install moves you onto the supported path.

Skill and Railway CLI

Yesterday, we wrote a post focused on our Railway Agent Skills, and how we approached landing them. When you install via the bootstrap command, these skills are installed by default and help route agents between when to use MCP vs CLI, which MCP to use, and how to engage Railway Agent. It's an important part, because it lets us tune the approach the agent is taking and guide it down the paths we want.

As we moved through CLI improvements, we focused on the agent-experience nits that pop up when a non-interactive caller is hitting the system: commands that don't return proper structure, and interactive prompts that block automation.

Commands that return data now take a --json flag that outputs it accordingly, so an agent gets structured output instead of scraping returns meant for human eyes.
Where applicable, -y skips the confirmation prompts that would otherwise leave an agent hanging on an "Enter" that never comes.
-s / -e scope any command to an exact service and environment, so you're filtering down to the right one.

All of these behaviors are steered by the agent skills and the skills router we've built into use-railway. The layered approach has worked really well for us.

The other half of the work has been closing the gap between the dashboard and the terminal, one command at a time. Metrics, custom domains, outbound networking, volumes, buckets, templates, and sandboxes all landed as first-class CLI commands, which means they all landed as things an agent can do too.

Remote MCP

Local MCP assumes a few things: that you can install the CLI, that you can sign in, and that the work has something to do with the machine you're on. There are plenty of practical examples where these aren't true. That's when the remote MCP server earns its keep.

It's accessed at mcp.railway.com (which doubles as its landing page too), responds over Streamable HTTP, and it doesn't require a local install, outside of being configured in your agents and signed in via OAuth. The Remote MCP talks straight to the Railway API, and is fully self-contained. The agent authenticates through the browser with OAuth, you choose which workspaces and projects it can touch on the consent screen, and the connection is scoped to exactly that. (Project tokens aren't accepted here on purpose. The remote server wants a real user identity behind every call for billing and audit.)

The situations where remote is the right call tend to have similar shapes:

The system has no filesystem access, or you'd rather not give it any.
You can't or won't install the CLI, like a hosted assistant or a locked-down box.
A third-party agent that can't shell out to a local binary and only speaks MCP over HTTP.
CI, where a hosted endpoint and browser OAuth beat managing CLI auth inside a runner.

When we first shipped remote MCP, we kept the tool count deliberately tiny: a handful of operations plus the railway-agent tool as the escape hatch for anything complicated. A smaller surface is easier for a model to reason about, and we'd rather grow it on evidence than guess at what people wanted and bloat it on day one. So when the requests came in, they were specific. People wanted the exact operations they kept dropping back to the CLI for, and the read operations they lived in, logs and status, went in first. Here's where the remote server sits now:

Account: whoami
Projects & services: list-projects, create-project, list-services
Deployments: list-deployments, get-status, create-deployment, deploy-artifact, redeploy, and accept-deploy to commit staged changes (it's destructive, so well-behaved clients prompt before firing)
Observability: get-logs
Agent: railway-agent, the entry point for the multi-step work that doesn't fit a single tool call

Fun fact: There was a time period where Railway Agent made up 50% of the calls. Once we added get-status and get-logs, the volume for agent calls dropped by two-thirds. It still gets a lot of usage, but the intention is to gradually expose the workflows that users actually need, and keep the context used by tools small.

The Railway Agent, your operator

The two MCP servers give an agent tools. The CLI expands that tool box a lot further. The Railway Agent gives it a teammate who's REALLY smart about running Railway.

Your coding agent is good at building your application. It is not, out of the box, a Railway expert and in many cases it's operating out of aged training data. It'll almost always figure out its way through it, but it's definitely not peaceful to watch the CLI error a bunch of times as the agent works through it (another reason why we strongly encourage getting the skills installed).

The Railway Agent already knows all of the operating patterns. The project model, the services, the deployments, the logs and metrics, the variables, the networking, and the ways these things tend to break. So rather than teaching your agent to be a Railway expert, you let it delegate to one.

On the operations side it manages your Railway environment directly: create and configure services, attach a Postgres or Redis, wire up networking, set variables, scale a service, and walk a failing deployment until it understands what went wrong.

On the code side it can go a step further and write the fix. When a deploy breaks, smart diagnosis reads the build and runtime logs against your recent changes, explains what happened, and when the fix belongs in your repo it can open a pull request for you to review. For heavier work it can spin up its own sandbox and actually run code instead of guessing at it.

You can reach the Agent from the dashboard in the UI, but for the terminal-pilled builder, the Remote MCP server through the railway-agent tool, or CLI are your best bet. Take this for a spin in the CLI next time you're authenticated:

railway agent -p "why is my service crashing?"

-p is a single-turn prompt, which kicks the agent into a multi-step workflow behind the scenes: read the logs, check the deployment, reason about what went wrong, and answer with project-aware context instead of a guess.

A few example ways you can use it with automation:

# structured output a script can act on
railway agent -p "what's the status of my deployment?" --json

# continue an existing thread instead of starting cold
railway agent -p "now scale it to two replicas" --thread-id <ID>

# scope the question to a specific service and environment
railway agent -p "is this service healthy?" -s api -e production

--json is the one that matters for CI or sub-agent paths. A pipeline can shell out to railway agent, get structured output back, and make a decision on it without a human reading a chat window.

Run railway agent with no -p and you drop into an interactive session, which feels a lot more like a traditional back and forth REPL.

Which door do I use?

The short version:

Local MCP for a coding agent on your own machine. Inherits your sign-in, broadest surface, knows your directory and project. The default, and almost always the right answer.
Remote MCP when local doesn't fit: no filesystem, no CLI, a hosted assistant, or CI.
The Railway Agent when you'd rather hand off a multi-step problem than drive each tool call yourself.
The CLI directly when you want full control and the complete surface.

Most setups mix them, and that's the point. Whatever's on the other end, there's a door that fits.

Get connected

If you've got a coding agent in front of you right now, the fastest path (outside of asking your agent to look at railway.com and tell you how to get started) is to drop this into your terminal:

curl -fsSL railway.com/agents.sh | sh

If you're wiring up something hosted, attach --remote to the installer and you'll get pointed at https://mcp.railway.com for the remote install instead.

Rather hand the work off than manage the tools? railway agent -p is one prompt away.

Every (Agents) Connection to Railway