Jonathon's AI Wiki

Railway Remote MCP and `railway agent` CLI

7 min read

Source: X Bookmark 2045223753836355678 (Railway tweet) → Railway Remote Mcp Cli 2026 05 02 (Cody De Arkland blog, full content extracted)

Railway shipped two new agent surfaces in April 2026: a hosted Remote MCP server at mcp.railway.com with OAuth (no tokens on disk) and a new railway agent CLI command that talks to the same in-product AI agent the dashboard uses. Claude Code, Cursor, Codex, GitHub Copilot, Droid, and OpenCode are all wired up out of the box. The blog post is also a case study in MCP tool-surface design — Railway shipped 7 tools and is already reducing that count, with the deliberate decision to route every multi-step operation through a single railway-agent delegation tool rather than a sprawling per-CRUD-action surface.

Key Takeaways

  • Two on-ramps, same agent. mcp.railway.com (Remote MCP, in-editor) and railway agent (CLI, terminal/CI) both call the same backend POST /api/v1/agent endpoint. Improvements to Railway’s agent show up everywhere automatically.
  • OAuth in the browser, no tokens on disk. First use opens a consent screen; revoke at any time from Railway settings. The MCP .well-known/oauth-authorization-server endpoint mirrors back to Railway’s existing OIDC provider with the RFC 8707 resource parameter pre-baked, so audience binding works even if the client forgets it.
  • Add to Claude Code in one line: 
    claude mcp add railway --transport http https://mcp.railway.com
  • Cursor: one-click install from mcp.railway.com, or .cursor/mcp.json: 
    { "mcpServers": { "railway": { "url": "https://mcp.railway.com" } } }
  • CLI examples: 
    railway agent -p "show me the logs for my project"
railway agent -p "add a Postgres database to this project and set DATABASE_URL on the API service"
railway agent -p "list my services and their status" --json | jq '.toolCalls'
  • 7-tool MCP surface (intentional ceiling): whoami, list-projects, create-project, list-services, redeploy, accept-deploy, railway-agent. The first six are clean CRUD/discovery — they don’t need reasoning. Anything that’s a question in disguise routes through railway-agent.
  • The portable design lesson: “Context is expensive on both sides.” Every tool definition lives in the client’s prompt, every turn, before the user’s actual work. A 7-tool surface is cheap; a 25-tool surface is not — and larger lists measurably hurt selection quality. Multi-step operations under a sprawling tool surface become 6 round-trips burning the user’s context window before they get an answer. Delegate them to a single agent-tool that does the multi-step work server-side and returns a consolidated response.
  • railway-agent as instrumentation, not just delegation. Because it tracks which sub-tools it calls under the hood, Railway gets real usage data about which capabilities might earn promotion back to top-level tools. The tool surface is informed by actual usage, not guesses.
  • Implementation pattern worth borrowing. The MCP server is a Koa route handler inside Railway’s existing backend, not a separate service. OAuth piggy-backs on the existing OIDC provider, tools call internal controllers directly (no GraphQL hop, no token forwarding), and per-request RailwayContext flows through AsyncLocalStorage so tool handlers don’t have to thread auth/permissions through their arguments.
  • Local MCP and CLI are still maintained. Remote MCP is the new on-ramp, but the local MCP server and the rest of the CLI stay supported.
  • Scoped to user token in CI. railway agent in CI can do exactly what the user can do — nothing more.

How to use it from Claude Code

# 1. Install the MCP server in Claude Code
claude mcp add railway --transport http https://mcp.railway.com
 
# 2. First use will open OAuth consent in browser. Approve workspaces/projects.
 
# 3. Verify
/mcp  # in Claude Code, see "railway" listed

Once connected, you can ask Claude to run things like:

  • “Show me all my Railway projects, and what services are in each one.”
  • “Create a new Railway project called checkout-service.”
  • “Use the Railway agent to figure out why my backend service is crashing on deploy.”

The third pattern is the most powerful — Claude makes a single railway-agent call with the natural-language question; Railway’s agent runs the multi-step investigation server-side (logs, config, deploy correlation) and hands back a consolidated answer.

Implementation

Tool/Service: Railway Remote MCP Server (mcp.railway.com) + Railway CLI agent subcommand Setup: OAuth via claude mcp add (Code) / one-click install (Cursor) / click-to-copy snippet (everyone else). Local install path is still supported via the local MCP server. Cost: Public testing — no announced pricing for the MCP/agent surface itself; agent actions consume Railway resources you already pay for (deploys, compute). Integration notes:

  • The MCP server is stateless (sessionIdGenerator: undefined).
  • OAuth scope is per-workspace and per-project; revocable from Railway settings.
  • accept-deploy is annotated destructiveHint: true so MCP clients prompt for approval.
  • The blog post is also a reference implementation guide for anyone shipping their own MCP server: see https://docs.railway.com/guides/mcp-server.

Why this matters for WEO Marketly

WEO already deploys to Railway (per existing wiki references in Blog-Agent-Worker, Postiz integration, and various deploy notes). Adding the Railway MCP to Claude Code workspaces removes the dashboard round-trip for the most common operations: “why is staging crashing”, “set DATABASE_URL on this service”, “redeploy after the env-var change.” For staff who don’t normally touch Railway dashboard but need to investigate a crash, railway agent -p "..." is a more accessible interface than the dashboard.

The tool-surface design philosophy (“delegate multi-step to one agent-tool, keep direct tools cleanly bounded”) is the same lesson Sam Witteveen extracted from Claude Design (handoff pattern) and Simon Scrapes’ nine-component agentic OS (skill-systems-as-orchestrators). Railway is independently arriving at the same architectural answer: rich, multi-step capabilities live behind a thin tool surface, and the orchestration is server-side where it can be improved without breaking client schemas.

Try It

  1. Run claude mcp add railway --transport http https://mcp.railway.com in any Claude Code workspace.
  2. Approve OAuth in the browser.
  3. Ask Claude: “Use the Railway agent to summarize the current state of all my services and flag anything red.” — see how the single railway-agent call returns a consolidated answer.
  4. Update Railway CLI (railway upgrade), then try railway agent -p "show me memory and CPU for my services" --json | jq '.toolCalls' to see the underlying tool calls Railway’s agent made.
  5. If you build your own MCP server: read this post side-by-side with the Railway docs — the implementation notes are the cleanest public example of “fold MCP into your existing monolith rather than spinning up a parallel service.”

Open Questions

  • Pricing tier for high-volume railway-agent use — not announced; presumably bundled into existing plans during public testing but may change at GA.
  • Whether railway-agent will eventually be exposed as a more general-purpose endpoint (beyond Railway-context tasks) or stay tightly scoped to Railway operations.
  • Multi-tenant scoping in CI: the post says agent commands are scoped to user token. For org-shared CI runners, the right pattern is service tokens — confirmation needed in docs.

Graph View

Backlinks