railwayapp · codyde · Jul 28, 2026
diff --git a/content/docs/ai/mcp-server.md b/content/docs/ai/mcp-server.md
@@ -8,7 +8,7 @@ The [Railway MCP Server](https://github.com/railwayapp/railway-mcp-server) is a
 Railway offers two ways to connect:
 
 * **Local MCP** — runs through the [Railway CLI](/cli) on your machine. Recommended for most coding-agent workflows since it shares the CLI's authentication and project context.
-* **Remote MCP** — a hosted endpoint at `mcp.railway.com`. No local install or CLI required; clients authenticate through OAuth in the browser.
+* **Remote MCP** — a hosted endpoint at `mcp.railway.com`. With the Railway CLI, `railway mcp install --remote` connects through the CLI proxy using your existing `railway login`, so there is no browser step. Without the CLI, clients connect to the URL directly and authenticate through OAuth in the browser.
 
 ## Quick start
 
@@ -20,7 +20,7 @@ If the CLI is already installed, skip the bootstrap and run:
 
 ```bash
 railway setup agent          # local MCP
-railway setup agent --remote # remote MCP
+railway setup agent --remote # remote MCP (via the CLI proxy, no browser step)
 ```
 
 Read on for per-editor manual configuration, the available tool list, and security considerations.
@@ -119,19 +119,31 @@ The local server runs through the Railway CLI and exposes a broader set of CRUD
 
 The remote server exposes a focused set of tools plus a powerful agent entry point. For anything complex, delegate to `railway-agent`.
 
-* **Account**
+* **Account & workspaces**
   * `whoami`
-* **Projects**
-  * `list-projects`, `create-project`, `list-services`
+  * `list-workspaces`
+* **Projects & services**
+  * `list-projects`, `create-project`
+  * `list-services`, `create-service`, `update-service`
+  * `create-deployment` — create a service from a GitHub repo and trigger its first deploy
+  * `get-service-config`, `get-service-metrics`
+* **Configuration**
+  * `list-variables`, `set-variables`
+  * `list-domains`, `generate-domain`
+* **Deployments & logs**
+  * `list-deployments`, `get-status`, `get-logs`
+  * `redeploy`
+  * `accept-deploy` — commit staged changes and deploy (destructive; clients prompt for confirmation)
 * **Feature flags**
   * `list-feature-flags`, `get-feature-flag`
   * `set-feature-flag`, `delete-feature-flag` (admin; destructive delete is marked at the protocol level)
-* **Deployments**
-  * `redeploy`
-  * `accept-deploy` — commit staged changes and deploy (destructive; clients prompt for confirmation)
+* **Documentation**
+  * `search-docs`, `fetch-docs` — search and read Railway documentation
 * **Agent**
   * `railway-agent` — hand a natural-language request to Railway's AI agent for multi-step operations like log analysis, debugging, and service configuration
 
+Write and create tools require the same workspace or project access you hold in the dashboard, and actions in a restricted environment require the admin role.
+
 ## Security considerations
 
 The Railway MCP Server runs CLI commands or invokes Railway APIs on your behalf. Destructive operations are intentionally excluded from the local server's tool list, but you should still:
@@ -142,7 +154,8 @@ The Railway MCP Server runs CLI commands or invokes Railway APIs on your behalf.
 
 For the remote server specifically:
 
-* **OAuth scoping.** When you consent, you choose which workspaces and projects the client can access. Tokens are short-lived and can be revoked from your Railway account settings.
+* **OAuth scoping.** When you consent through the browser flow, you choose which workspaces and projects the client can access. Tokens are short-lived and can be revoked from your Railway account settings.
+* **CLI proxy credentials.** When you connect through `railway mcp install --remote`, the proxy uses your existing CLI login and refreshes the token for each request. No token is written into the editor's config file, and the proxy only ever sends it to `mcp.railway.com`.
 * **Destructive actions** are marked at the protocol level. Clients that respect these hints will prompt for confirmation.
 * **Project tokens are not accepted.** The remote MCP server requires a user identity for billing and audit trails.
 

diff --git a/content/docs/cli/mcp.md b/content/docs/cli/mcp.md
@@ -1,9 +1,9 @@
 ---
 title: railway mcp
-description: Start or install the Railway MCP server for AI coding tools.
+description: Start, proxy, or install the Railway MCP server for AI coding tools.
 ---
 
-Start a local Railway MCP server, or install the Railway MCP configuration into supported AI coding tools.
+Start a local Railway MCP server, bridge the hosted server through your CLI login, or install the Railway MCP configuration into supported AI coding tools.
 
 ## Usage
 
@@ -17,14 +17,28 @@ Running `railway mcp` with no subcommand starts the local stdio MCP server. This
 
 | Subcommand | Description |
 |------------|-------------|
+| `proxy` | Bridge the hosted MCP server at `https://mcp.railway.com` over stdio, authenticating with your existing `railway login` |
 | `install` | Install Railway's MCP server config into AI coding tools |
 
+## Transports
+
+`railway mcp install` can configure three transports. All three write to the same `railway` server entry, so switching between them is a single re-run of the command.
+
+| Transport | Command | How it authenticates |
+|-----------|---------|----------------------|
+| Local | `railway mcp install` | Runs the local stdio server (`railway mcp`) through the CLI, sharing your CLI login and linked project |
+| Remote (proxy) | `railway mcp install --remote` | Runs `railway mcp proxy`, which forwards to `mcp.railway.com` using your `railway login`. No browser step |
+| Remote (OAuth) | `railway mcp install --remote --oauth` | Points the editor at the `mcp.railway.com` URL directly; the editor runs its own OAuth browser flow |
+
+The proxy is the default remote transport because it reuses the login you already have. It refreshes your token automatically, so the connection keeps working without re-authenticating, and no credential is written into the editor's config file. Use `--remote --oauth` for environments without the Railway CLI, or when you want the editor to manage its own OAuth connection.
+
 ## Options for `install`
 
 | Flag | Description |
 |------|-------------|
 | `--agent <AGENT>` | Target a specific tool instead of all detected tools. Can be used more than once |
-| `--remote` | Configure the remote MCP server at `https://mcp.railway.com` instead of the local stdio server |
+| `--remote` | Configure the remote MCP server at `https://mcp.railway.com` through the CLI proxy (`railway mcp proxy`) instead of the local stdio server |
+| `--oauth` | Use with `--remote` to write the direct `mcp.railway.com` URL, so the editor runs its own OAuth flow instead of the proxy |
 
 ## Supported agents
 
@@ -37,18 +51,18 @@ Running `railway mcp` with no subcommand starts the local stdio MCP server. This
 | OpenAI Codex | `codex` |
 | OpenCode | `opencode` |
 
-When installing with `--remote`, the Railway CLI configures supported tools with Railway's hosted MCP server at `https://mcp.railway.com`.
-
 ## Installed MCP entries
 
-| Agent | Local stdio config | Remote config |
-|-------|--------------------|---------------|
-| Claude Code | `command: "railway"`, `args: ["mcp"]` | `type: "http"`, `url: "https://mcp.railway.com"` |
-| Cursor | `command: "railway"`, `args: ["mcp"]` | `url: "https://mcp.railway.com"` |
-| Factory Droid | `type: "stdio"`, `command: "railway"`, `args: ["mcp"]`, `disabled: false` | `type: "http"`, `url: "https://mcp.railway.com"`, `disabled: false` |
-| GitHub Copilot | `type: "local"`, `command: "railway"`, `args: ["mcp"]`, `tools: ["*"]` | `type: "http"`, `url: "https://mcp.railway.com"`, `tools: ["*"]` |
-| OpenCode | `type: "local"`, `command: ["railway", "mcp"]`, `enabled: true` | `type: "remote"`, `url: "https://mcp.railway.com"`, `enabled: true` |
-| OpenAI Codex | `command = "railway"`, `args = ["mcp"]` | `url = "https://mcp.railway.com"` |
+The local and remote-proxy transports both write a stdio entry that runs the `railway` binary; they differ only in the arguments (`["mcp"]` versus `["mcp", "proxy"]`). The remote-OAuth transport writes the hosted URL directly.
+
+| Agent | Local (`railway mcp`) | Remote proxy (`railway mcp proxy`) | Remote OAuth (URL) |
+|-------|-----------------------|------------------------------------|--------------------|
+| Claude Code | `command: "railway"`, `args: ["mcp"]` | `command: "railway"`, `args: ["mcp", "proxy"]` | `type: "http"`, `url: "https://mcp.railway.com"` |
+| Cursor | `command: "railway"`, `args: ["mcp"]` | `command: "railway"`, `args: ["mcp", "proxy"]` | `url: "https://mcp.railway.com"` |
+| Factory Droid | `type: "stdio"`, `command: "railway"`, `args: ["mcp"]`, `disabled: false` | `type: "stdio"`, `command: "railway"`, `args: ["mcp", "proxy"]`, `disabled: false` | `type: "http"`, `url: "https://mcp.railway.com"`, `disabled: false` |
+| GitHub Copilot | `type: "local"`, `command: "railway"`, `args: ["mcp"]`, `tools: ["*"]` | `type: "local"`, `command: "railway"`, `args: ["mcp", "proxy"]`, `tools: ["*"]` | `type: "http"`, `url: "https://mcp.railway.com"`, `tools: ["*"]` |
+| OpenCode | `type: "local"`, `command: ["railway", "mcp"]`, `enabled: true` | `type: "local"`, `command: ["railway", "mcp", "proxy"]`, `enabled: true` | `type: "remote"`, `url: "https://mcp.railway.com"`, `enabled: true` |
+| OpenAI Codex | `command = "railway"`, `args = ["mcp"]` | `command = "railway"`, `args = ["mcp", "proxy"]` | `url = "https://mcp.railway.com"` |
 
 `railway mcp install` merges the Railway server entry into existing configs without removing other MCP servers.
 
@@ -72,21 +86,43 @@ railway mcp install --agent cursor
 railway mcp install --agent claude-code --agent copilot
 ```
 
-### Install the remote MCP server configuration
+### Use the remote server through your CLI login
 
 ```bash
 railway mcp install --remote
 ```
 
+This configures detected tools to run `railway mcp proxy`. Because the proxy uses your existing `railway login`, the editor connects to `mcp.railway.com` without an OAuth browser step. If you are not logged in, run `railway login` and the connection starts working on the next request.
+
+### Use the remote server with the editor's own OAuth flow
+
+```bash
+railway mcp install --remote --oauth
+```
+
+### Switch a tool back to the local server
+
+```bash
+railway mcp install --agent claude-code
+```
+
 ## Local server
 
-MCP clients that use a local stdio server should run:
+MCP clients that use a local stdio server run:
 
 ```bash
 railway mcp
 ```
 
-The `railway mcp install` command writes this configuration for supported tools automatically.
+## Proxy server
+
+MCP clients configured for the remote server through the CLI run:
+
+```bash
+railway mcp proxy
+```
+
+You do not run this command directly. `railway mcp install --remote` writes it into the editor's MCP configuration, and the editor launches it. The proxy reads your stored `railway login`, attaches a fresh token to each request, and forwards it to `mcp.railway.com`. Restart the editor after installing so it picks up the change.
 
 ## Related
 

diff --git a/src/components/mcp-install-guide.tsx b/src/components/mcp-install-guide.tsx
@@ -383,7 +383,7 @@ function QuickInstall({
       <p className="border-t border-muted bg-muted-element/30 px-4 py-2 text-xs text-muted-base">
         {mode === "local"
           ? "Configures detected tools to run the Railway MCP server through the local Railway CLI."
-          : "Configures detected tools to use Railway's hosted MCP server at mcp.railway.com via OAuth."}
+          : "Configures detected tools to reach Railway's hosted MCP server at mcp.railway.com through the CLI proxy, using your railway login (no browser step). The per-editor configs below show the direct-URL setup, which authenticates via OAuth — the same as railway mcp install --remote --oauth."}
       </p>
     </div>
   );