Connect Railway

An account of Railway is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Deploy, redeploy, read logs and manage variables of Railway projects through the official Railway MCP server and GraphQL API.

One account is one Railway account reached through the company Railway app, or a workspace token (or an account token) pasted by hand; every tool runs either way. One resource is one project. Its owner labels each project with an environment (prod, staging, preview or dev); deploys and variable changes are held per label, and a project without a label can only be inspected.

Permissions, presets and tools of this service: Railway plugin.

How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (providers.<id>.*, see configuration keys). Every instance registers its own app: this gateway never uses an app shared with another one.

The usual way: through your company's OAuth app at the service (one click once the app is registered)

Scopes asked: openid, offline_access, workspace:member.

Another way: with a workspace token pasted by hand

Sign in to Railway as the account the agents will act as; a shared service account that is a member of the workspace is fine.
Open Account settings, Tokens, and create a token with the workspace selected: a workspace token reaches that workspace only.
An account token, created with No workspace selected, works too but reaches every workspace of the account. A project token is not accepted: it reaches one environment of one project.
Railway tokens carry no permission choice: the token reaches what its workspace or account allows, and Vaubaan decides who may do what.
Copy the token and paste it here. Railway shows it once.

Where: https://railway.com/account/tokens

What the connect page asks:

Workspace token (secret): A workspace token is recommended; an account token works too. A project token is not accepted.

The service's documentation: https://docs.railway.com/integrations/api

Disconnecting

In your Railway account settings, open Authorized Apps, select your company's app and choose Revoke Access: every token it holds stops working at once.

Registration notes from the plugin

From the plugin's README, written for the people who register the app or create the token.

Credential — how the company registers its app

Railway → Workspace → Developer → Auth apps → New app (https://railway.com/workspace/developer/apps/new). Name it after your gateway instance. Leave Device Flow off.
Redirect URI: the instance callback the gateway shows in Settings → Administration → Company apps (Railway requires https://; for loopback use https://127.0.0.1, never localhost).
Copy client_id and client_secret into the instance configuration under the Railway provider app (Settings → Administration → Company apps, or the mounted config file). The host uses them for the authorization-code flow and for refresh; the plugin reads neither.

The gateway then runs the authorization-code flow declared by railwayCredentialSpec: scopes openid offline_access workspace:member, PKCE S256, prompt=consent (needed for a refresh token) and the RFC 8707 resource indicator https://mcp.railway.com on both the authorization and token requests — the MCP server refuses tokens minted without it. Access tokens last one hour; the host refreshes them with the standard refresh_token grant declared by the spec (refreshable: true), including after an UpstreamAuthError.

Credential, the other way: a workspace token

Without a company OAuth app — or beside it — an account is connected with a Railway token pasted by hand (railwayTokenCredential, src/token.ts), created under railway.com/account/tokens. Every tool runs with it: discovery and the four variable tools on the GraphQL API, the ten tools of Railway's MCP server with the token sent as Authorization: Bearer to https://mcp.railway.com/.

Token	Reach	Offered	MCP server
workspace token (workspace chosen)	that workspace only	yes, recommended	accepted — checked against the real service on 2026-10-14
account token ("No workspace")	every workspace of the account	yes, second choice	not checked; Railway documents the server for OAuth only
project token	one environment of one project	no: a resource is a project	—

A shared service account that is a member of the workspace is fine: Vaubaan decides who may do what.

Check at paste (probeRailwayToken): query { me { name email } } answers for an account token only (named by its email). Otherwise the projects the token reaches answer for a workspace token, named by its workspace (the vaubaan workspace) or, when the workspace name is not exposed, by its projects. Neither answers → the token is refused.

Discovery: the projects the token reaches, then — account token only — each workspace of me.workspaces. A workspace token has no me; its refusal ends the list.

When the MCP server refuses a pasted token (401 or 403), the plugin asks the API about the same token (explainMcpRefusal): refused there too → a rejected credential (401, the account "Needs reconnecting"); still accepted → the MCP server does not take this kind of token: a 403 naming it ("refused this account token … reconnect with a workspace token"), and the connection stays usable for the variable tools. railway__whoami may say little with a workspace token, which has no user behind it.

Removing the account tells the person to delete the token under Account settings → Tokens. ADR token-connections-beside-the-integration-app (amendment of 2026-10-14).

Last changed 2026-10-16. This page as Markdown: /docs/providers/railway.md