MCP for AI agents
Connect Claude, Claude Code, Cursor or any MCP client to Railyard. 42 tools to deploy, roll back, read logs, query databases, manage domains and backups. OAuth, scoped, audited; destructive actions wait for a human.
MCP (Model Context Protocol) is an open standard that lets AI assistants call tools on external systems. Railyard runs an MCP server, so Claude, Claude Code, Cursor or any other MCP client can work with your Railyard team on your behalf. It can deploy and roll back, read logs and traffic, run commands, query your database, and manage domains, backups and servers.
Everything the agent does runs with the access you grant, on the team you pick, and shows up in that team’s activity log. Anything that removes or overwrites data waits for a person to approve it.
Quick start
- Add Railyard to your client. In Claude, open Customize → Connectors, search for Railyard and choose Connect. For other clients, see Connect your client.
- Approve access. A Railyard page opens in your browser. Pick the team and the access level (
read,deployorwrite), then approve. - Ask. For example: “Which of my apps failed their last deploy, and why?”
There’s nothing to install and no token to copy. The client discovers Railyard’s sign-in on its own.
Endpoint
| URL | https://app.railyard.run/api/mcp |
| Transport | Streamable HTTP (POST) |
| Protocol | MCP 2026-07-28 (stateless) and the earlier 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 revisions |
| Sign-in | OAuth 2.1 with PKCE, or a Railyard API token as a Bearer header |
| Capabilities | Tools (42) and prompts (3) |
On a self-hosted Railyard, the endpoint is /api/mcp on your own dashboard’s address.
Connect your client
Claude (web, desktop and mobile)
Open Customize → Connectors, search for Railyard, choose Connect and approve access on the Railyard page that opens. On Team and Enterprise plans, an organization owner adds the connector first, then each member connects with their own Railyard account.
Claude Code
claude mcp add --transport http railyard https://app.railyard.run/api/mcp
Run /mcp inside Claude Code and choose Authenticate to sign in through your browser.
Cursor
In .cursor/mcp.json:
{ "mcpServers": { "railyard": { "url": "https://app.railyard.run/api/mcp" } } }
VS Code, Windsurf and other clients
Add https://app.railyard.run/api/mcp as a remote (streamable HTTP) MCP server. Clients that support MCP authorization sign in through your browser.
With an API token instead of OAuth
For a client that can’t do OAuth, or for scripts and CI, create a token under Settings → Access & tokens and send it as a header:
claude mcp add --transport http railyard https://app.railyard.run/api/mcp --header "Authorization: Bearer rly_..."
{ "mcpServers": { "railyard": { "url": "https://app.railyard.run/api/mcp", "headers": { "Authorization": "Bearer rly_..." } } } }
Access levels
You choose the level on the consent screen, or when you create a token.
| Level | What it allows |
|---|---|
read | List and inspect apps, servers, deploys, domains, backups, processes and scheduled tasks; read logs, traffic, alerts and activity. Nothing that changes anything. |
deploy | Everything in read, plus deploy, roll back, cancel deploys, restart, scale workers and toggle maintenance mode. |
write | Everything in deploy, plus create apps and environments, launch templates, change variables and domains, start backups, run commands and scheduled tasks, read variable values, list tables and run read-only SQL. |
The level can never go beyond your own role on the team: a viewer can grant read, a deployer up to deploy, and an admin or owner up to write. If your role changes later, the agent’s access follows it. A tool the connection isn’t allowed to use returns an error that names the access it needs.
Tools reference
Tools marked approval never act directly. Each call creates a request on the Approvals page, and nothing changes until a team admin approves it.
Account and templates
| Tool | Access | What it does |
|---|---|---|
whoami | read | The team, its plan and limits, app and server counts, and this connection’s access level |
list_templates | read | Search the one-click app templates and multi-service stacks, by words or category (up to 50 results) |
launch_template | write | Create an app or stack from a template key and start its first deploy, on a server you name or the first online one |
Apps
| Tool | Access | What it does |
|---|---|---|
list_apps | read | Every app with status, URL, server and environment |
get_app | read | One app: status, URL, repository and branch, domains, processes, variable names (not values) and the last 5 deploys |
create_app | write | Create an app from an https:// Git repository URL, detect how to build it, and start its first deploy |
create_environment | write | Copy an app’s settings and variables into a new environment of it, such as staging, optionally on another branch. It doesn’t deploy until asked |
clone_app | write | Copy an app into a new app with the next free name. It doesn’t deploy until asked |
promote_app | write | Promote an environment to the app it came from: copy its settings across and deploy the same commit there |
scale_app | deploy | Set how many containers a worker process runs, then redeploy. The web process scales with autoscaling |
set_maintenance | deploy | Turn maintenance mode on or off and redeploy the current release to apply it |
delete_app | write · approval | Delete an app and its data |
Deploys
| Tool | Access | What it does |
|---|---|---|
deploy_app | deploy | Deploy the latest commit, or an exact commit SHA, tag or branch passed as ref, with the same approval rule and rate limit as the dashboard |
list_deploys | read | Recent deploys of the team or one app, filtered by status (up to 50) |
get_deploy | read | One deploy: commit, trigger, who started it, timing and the error if it failed |
deploy_logs | read | The build and release log of a deploy, the last 200 lines by default (up to 500) |
rollback_app | deploy | Redeploy an earlier successful deploy. It also restores that deploy’s variables unless restore_config is false |
cancel_deploy | deploy | Cancel a queued, scheduled or running deploy |
Runtime
| Tool | Access | What it does |
|---|---|---|
app_logs | read | Runtime log lines, 100 by default (up to 500), filtered by text or /regex/, level, process and time range (1h, 24h, 7d, 30d) |
list_processes | read | Running containers with state, health, restarts, crash looping, CPU and memory |
restart_app | deploy | Restart all of an app’s containers, or one process’s |
run_command | write | Run a one-off command inside the app’s container, in the background |
get_command | read | Status, exit code and output of a command started with run_command |
list_scheduled_tasks | read | The app’s scheduled tasks with schedule, command and last run |
run_scheduled_task | write | Run a scheduled task now, outside its schedule |
Variables
| Tool | Access | What it does |
|---|---|---|
get_env | write | Variables with their values. Sealed variables show as (sealed) |
set_env | write | Set a variable, applied on the next deploy. Sealed variables can’t be changed here |
unset_env | write · approval | Remove a variable |
Domains
| Tool | Access | What it does |
|---|---|---|
list_domains | read | Custom domains with verification and certificate state, and the DNS records still to create |
add_domain | write | Add a domain (or a redirect) and return the DNS records to create. Railyard verifies them and issues the certificate |
remove_domain | write · approval | Remove a domain |
Databases
| Tool | Access | What it does |
|---|---|---|
list_backups | read | The app database’s 50 most recent backups |
create_backup | write | Start a backup now (Postgres, MySQL and ClickHouse) |
restore_backup | write · approval | Restore the database from a completed backup, replacing the current data |
list_tables | write | Tables with approximate row counts and sizes, largest first |
query_database | write | Run one read-only SQL statement. It runs in a read-only transaction with a time limit and returns at most 200 rows |
Servers
| Tool | Access | What it does |
|---|---|---|
list_servers | read | Servers with status, provider, load and pending security updates |
get_server | read | One server: status, agent version, load, security updates and the apps it runs |
reboot_server | write · approval | Reboot a server; its apps are briefly down |
Monitoring
| Tool | Access | What it does |
|---|---|---|
app_traffic | read | Requests, status classes, error rate, latency percentiles and busiest paths over live, 1h, 6h, 24h, 7d or 30d, compared with the window before |
list_alerts | read | The app’s metric alerts, whether they’re firing, and the last 50 incidents |
list_activity | read | The audit trail, newest first, for the team or one app (up to 50 entries) |
Prompts
Clients that show MCP prompts (for example as slash commands) get three ready-made ones:
| Prompt | Arguments | What it does |
|---|---|---|
debug_failed_deploy | app | Finds the app’s latest failed deploy, reads its error and logs, and explains the cause and the fix |
app_health_report | app | Summarizes the app’s status, processes, traffic, errors and alerts |
fleet_overview | — | Reviews every server and app on the team and flags what needs attention |
Example requests
- “Why did the last deploy of my API fail? Fix the variable it needs and redeploy.”
- “Roll the shop back to yesterday’s release.”
- “Which apps returned 5xx errors in the last hour?”
- “Create a staging environment of the web app on the
developbranch and deploy it.” - “How many users signed up this week? Query the database.”
- “Add
shop.example.comto the storefront and tell me which DNS records to create.” - “Launch Plausible from the templates on my second server.”
Approving sensitive actions
Five tools never act straight from an agent: delete_app, unset_env, remove_domain, restore_backup and reboot_server. Each call creates a request on the Approvals page, which also shows on the dashboard. A team admin approves it to run the action and record the result, or rejects it to drop it. This happens on every call, whatever the access level. Agents can’t approve anything, including deploys that are waiting for approval.
Security and privacy
- Your password never reaches the agent. Sign-in happens in your browser, against Railyard, with OAuth 2.1 and PKCE.
- One team per connection. Every call is limited to the team you authorized. Anything else returns “not found”.
- Secrets stay protected.
readanddeployaccess see variable names only. Values needwriteaccess, and sealed variables stay masked.writeaccess can also run commands inside your app’s container, so give it only to agents you trust. - Read-only SQL.
query_databasecan’t change data. Each query runs in a read-only transaction with a time limit. - A suspended or past-due team stays readable. Read tools keep working; nothing can be changed until the team is back in good standing.
- Full audit. Every tool call is written to the activity log with a source of
mcp, the tool and the token, including calls that were refused. Variable values, SQL and command text are never stored in that entry. - Revoke any time. Authorized clients and their tokens are listed under Settings → Access & tokens.
Limits
| Limit | Value |
|---|---|
| Requests | one JSON-RPC request per HTTP POST |
| App log lines | 100 by default, 500 maximum |
| Deploy log lines | 200 by default, 500 maximum |
| SQL rows returned | 200 |
| Command output returned | the last 20,000 characters |
| Deploys and activity entries | 20 by default, 50 maximum |
| Deploy rate | the same per-hour limit as the dashboard |
| Authorization code | 10 minutes, single use, bound to the client and PKCE challenge |
Troubleshooting
“This API token can’t …” The connection’s access level is too low for that tool. Reconnect and choose deploy or write (your role has to allow it), or create a token with that scope.
“No app named …” App names are the name values from list_apps.
“Waiting for approval” That tool needs an admin to approve it. Open Approvals in Railyard.
“This team is suspended” or “Payment is overdue” Read tools still work. Changes resume once the team is back in good standing.
The client keeps asking to sign in. Remove the Railyard connector and add it again. If you revoked its token under Settings → Access & tokens, the client needs a new sign-in.
Guides and deep dives
- Deploy an app from Claude Code with MCP, step by step
- Connect Claude, Cursor, VS Code and Windsurf
- Debug a failed deploy with Claude
- Roll back a bad release from chat
- Staging environments with an AI agent
- Let an AI agent query your database with read-only SQL
- How an MCP server for deployments works, request by request
- MCP authorization explained: OAuth 2.1, PKCE and client registration
- Designing MCP tools an AI agent can’t misuse
- MCP 2026-07-28: stateless requests and server/discover
Next steps
- Connect your agent with the quick start.
- Pick the access level:
readfor agents that only answer questions,deployfor ones that ship,writefor full control. - Watch approvals for the five approval-only tools.
- Go further with the REST API and the CLI, which cover everything in the dashboard.