Railway MCP Setup: CLI Login, OAuth, and Project Checks

How do you add the CLI connection?

Verify the CLI installation and login first, then add one MCP entry using your client's expected configuration format. Testing these separately gives you a useful diagnosis if the editor cannot start the process.

Follow the Railway CLI installation guide for your operating system. In a terminal, check:

railway --version
railway login
railway whoami

For Cursor, the official MCP guide documents this configuration in .cursor/mcp.json:

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

Merge the entry into your existing object instead of replacing unrelated servers. The Cursor client guide explains the project versus global configuration distinction. Prefer a project configuration when the connection is only needed for that repository.

Use the configuration validator to catch malformed JSON before restarting or reloading the client. It cannot authenticate Railway or determine whether your account can see a project. Once the entry loads, inspect the discovered tools and retain ordinary action approval controls during the first session.

If the terminal works but the GUI editor reports a missing command, compare their executable search paths. Installing a second unrelated MCP package is unlikely to fix an editor that simply cannot locate the Railway executable.

What should the first project check prove?

The first check should identify the account, project, service, and intended environment without changing infrastructure. Ask for a small inventory you can compare with the Railway dashboard, rather than a broad instruction such as “set up my app.”

A useful first request is: “Identify my Railway account, list the projects I can access, and show the services in the project I select. Do not create, redeploy, change variables, or accept staged changes.” Inspect the tool actions as well as the final explanation.

Railway's environment documentation says projects start with a production environment and service changes are scoped to an environment. Therefore, “the project is correct” is insufficient. A staging service and its production counterpart can share a recognizable name while having very different consequences.

Keep this acceptance record:

• The account and Workspace you intended to use.
• The project identifier and recognizable project name.
• The service identifier and environment you checked.
• The read operation, its result, and the time you compared it with the dashboard.

Do not include variable values in the record. Ask the assistant to omit secrets from explanations and screenshots. Reading infrastructure metadata is enough to establish initial targeting; exporting environment files is unnecessary for this check.

How do you diagnose missing access?

Separate process startup, authentication, and project visibility before changing permissions. A missing executable is a local installation problem, while an absent project after successful authentication usually demands an account or scope check.

Use this order: confirm the configured route, inspect the client error, check the CLI or OAuth identity, and compare the accessible projects with the dashboard. Keep the failing operation and redacted error together so each retry tests a specific hypothesis.

The Railway MCP guide states that project tokens are not accepted by this server. Do not paste one into a configuration just because it worked in another Railway automation. Credential compatibility is determined by the endpoint, not by the brand printed on the token page.

Use Config Doctor for the configuration layer. If tools already appear and only one project fails, focus on that project's access rather than reinstalling the client. If a previously working login expires, reauthenticate through the selected route, then repeat the same narrow read check before resuming work.

When is the connection ready for deployment?

The connection is ready for a deployment workflow only after targeting is verified and the proposed change is concrete enough to review. MCP access alone does not establish that the code builds, the service is healthy, or the release can be reversed.

We recommend a short release brief: repository revision, project, environment, service, expected change, verification request, and rollback choice. Ask the assistant to identify what it will do before it runs a deployment tool. A request to “fix production” is too broad for an initial connection exercise.

Use an existing non-critical environment for the first authorized change where practical. Railway's environment guide describes isolation between configurations, but external dependencies still deserve attention: a staging variable can point at a production database if someone configured it that way.

After the change, compare the actual deployment and application behavior with the brief. Retain the revision and result in your normal release record. That makes the connection useful beyond its first successful demo: future work starts from a checked operational baseline.