Railyard

API & MCP

Automate Railyard from a pipeline or an AI assistant.

REST API

Railyard's backend is a REST API, and everything the app does — listing projects, loading and saving a document, validating a design, exporting a bundle, managing organisations — is available over it. Authenticate with a personal access token minted from your user settings; tokens expire after 90 days unless you choose another lifetime. Owner-level, reviewer and irreversible actions — creating, renaming or deleting an organisation; deleting a project; listing, restoring or permanently deleting a recently deleted organisation or project; moving a project to another organisation; changing a project's sharing, visibility, version control or branch protection, or recovering access to it; pruning project history; reviewing, approving, merging or declining a merge request, or withdrawing someone else's; changing members, roles or invitations; accepting or declining an invitation; and opening billing — need a signed-in browser session and are refused for tokens. The full endpoint reference lives at /api-docs.

Plans, deliverables and the API

  • GET /api/plans — the plan catalogue, public: every plan's prices (in pence, GBP, excluding VAT), editor and rack limits, features and deliverables. It is the same file the server enforces.
  • GET /api/projects/{id}/entitlements — what this estate may do now: its entitlements (plan, limits and features), its rackCount, whether a Project Pass could be bought now (projectPassAvailable) and its projectPasses, newest first. Name the organisation with X-Org-Id, as for other project routes.
  • POST /api/projects/{id}/deliverables/{kind} — generates a deliverable from the saved design and returns it as a file download. kind is one of build-pack, build-pack-preview, cable-schedule, cable-labels, optics, power-schedule, power-cords, power-report, netbox, nautobot, designbuilder, netbox-sync or nautobot-sync. An optional JSON body {"changeRequestId": "…", "options": {…}} exports a merge request's draft instead of main, and passes options such as netboxVersion or, for build-pack-preview, the rackId. It accepts a personal access token, so scripts and MCP clients can use it. netbox-sync and nautobot-sync return JSON rather than a file to import: the objects the NetBox or Nautobot bundle carries, one array per bundle file, each row with that file's columns and a railyard object naming the rack, device, port, cable or other entity it came from. The NetBox plugin and the railyard-sync CLI use them to keep a DCIM in step with the design; they take the bundle's options and are paid exactly like the bundles.
  • POST /api/projects/{id}/project-pass/checkout — opens a Stripe Checkout for a Project Pass and returns its url. Browser session only, for the owner of the personal space.

A request the plan does not cover answers 402 with one of two codes. plan_required names the missing feature (deliverables, branches, mergeRequests or liveCollaboration), the deliverable when there is one, the current plan, the requiredPlans that include it and whether a projectPass would. plan_limit names the resource (racks or editors), its limit, the current count, the scope (estate or organisation), the requiredPlans with room for it and projectPass. Both carry a readable error. With billing on, the anonymous POST /api/export serves only format=json and answers any other format with plan_required; /api/validate is unchanged. With billing off neither code is ever returned. See Plans & billing.

Hosted remote MCP

When your Railyard server has remote MCP enabled, connect to https://railyard.sh/mcp. The hosted connection uses Railyard sign-in and OAuth consent; it does not use a personal access token. It can reach your hosted projects within your current permissions. Edits remain subject to project permissions and revision checks.

Claude Desktop and Claude on the web

Choose Add custom connector, enter https://railyard.sh/mcp, then sign in to Railyard and approve the requested permissions.

Claude Code

Run claude mcp add --transport http --scope user railyard https://railyard.sh/mcp, then claude mcp login railyard. The browser sign-in asks you to approve the connection. Check it with claude mcp list or /mcp inside Claude Code. The user scope makes Railyard available in every project; omit --scope user to use it only in the current project.

Codex CLI and IDE

Run codex mcp add railyard --url https://railyard.sh/mcp, then codex mcp login railyard. The login opens Railyard in a browser to review and approve access. For a headless terminal, codex mcp login railyard --no-browser prints an authorisation URL and asks you to paste the browser callback URL. Check the entry with codex mcp list.

Gemini CLI

Run gemini mcp add --transport http railyard https://railyard.sh/mcp, then open Gemini CLI and run /mcp auth railyard if Gemini reports that the server requires authentication. Check it with gemini mcp list. Status: documented from Gemini CLI's remote MCP docs; hosted Railyard smoke test pending.

Cursor

Create ~/.cursor/mcp.json for a personal setup, or .cursor/mcp.json inside a project, with {"mcpServers":{"railyard":{"url":"https://railyard.sh/mcp"}}}, then restart Cursor and follow any authentication prompt in Customize → MCPs. Status: documented from Cursor's MCP integration docs; hosted Railyard smoke test pending.

VS Code Copilot

Run MCP: Add Server from the Command Palette and choose the HTTP server flow, or open your user MCP configuration and add {"servers":{"railyard":{"type":"http","url":"https://railyard.sh/mcp"}}}. VS Code supports OAuth for remote MCP servers, including Dynamic Client Registration for servers that advertise the MCP authorisation metadata. Status: documented from VS Code's MCP configuration docs; hosted Railyard smoke test pending.

OpenCode

Run opencode mcp add railyard --url https://railyard.sh/mcp, or add {"$schema":"https://opencode.ai/config.json","mcp":{"railyard":{"type":"remote","url":"https://railyard.sh/mcp"}}} to opencode.json. Run opencode mcp auth railyard if sign-in does not start automatically, then check with opencode mcp list. Status: OpenCode 1.18.33 completed local OAuth and reported Railyard connected; hosted smoke test pending.

ChatGPT custom apps

In ChatGPT workspaces where developer mode and custom MCP apps are available, create an app from Settings or Workspace settings, enter https://railyard.sh/mcp as the MCP endpoint, choose OAuth when prompted, scan tools, then create the draft app. Status: Railyard's OAuth callback and token exchange have automated coverage, but ChatGPT tool-level linking and a hosted smoke test remain pending. The connector should not be treated as verified in ChatGPT yet.

Bulk equipment placement

For an equipment list, ask the assistant to use add_rack_devices to place 1–50 devices in a single saved-project call, or draft_add_rack_devices on a review branch. Every item is checked before the batch is saved. A failed batch saves nothing, and a successful batch returns one new revision to use for the next call. The hosted endpoint allows 60 MCP requests per user per minute, including reads; if it returns HTTP 429, wait for the Retry-After interval before continuing. Project plan limits still apply.

Devices that exist or are planned but are not racked yet live in the store room. The assistant records them as stock_item design objects, places one unit in a rack with rack_stock_item and returns a device with unrack_device_to_stock, each with a draft_ twin for review branches.

Before placing a model, the assistant can find it in the public device catalogue with search_device_types and copy it into the project with import_device_type (or draft_import_device_type on a review branch), exactly as choosing it in the device type field does, so devices carry the catalogue's ports, power inlets and dimensions rather than guessed ones. Rack frames work the same way: search_rack_types finds a vendor rack and import_rack_type (or draft_import_rack_type) copies it, returning the key to pass to create_rack.

See the official setup docs for Gemini CLI, Cursor, VS Code, OpenCode, and ChatGPT custom connectors.

You can review and revoke the grant under User settings → Connected AI apps. Signing out of a browser session does not revoke a connector grant. A connector only stays connected beyond 15 minutes if it asked for offline_access, and never for more than 90 days from when you allowed it; after that it asks you again. Connecting the same app again replaces its earlier connection. The hosted connector cannot read projects saved only in your browser's local storage.

Local MCP server

The Railyard MCP server gives an MCP client — Codex, Claude Desktop, Claude Code, or any other — read and write access to your Railyard projects and organisations. It talks to a running Railyard backend over the same REST API and authenticates with a personal access token, speaking MCP over stdio.

Run npx -y railyard-mcp auth to open Railyard in your browser, then create a token under User settings → API tokens. The home-page installer provides copyable commands for Codex and the other supported clients. The token still needs to be added to the MCP client's protected configuration.

It exposes tools to, among other things:

  • list, read, create and rename projects;
  • validate a design and export it to any supported format (deliverables follow the project's plan; Railyard JSON is always free);
  • list organisations, members and invitations, and manage the shared device-type library;
  • read billing status.

Some actions need you signed in to Railyard in a browser, so a token — and an assistant using one — cannot do them: creating, renaming or deleting an organisation; deleting a project; listing, restoring or permanently deleting a recently deleted organisation or project; moving a project to another organisation; changing a project's sharing, visibility, version control or branch protection, or recovering access to it; pruning project history; reviewing, approving, merging or declining a merge request, or withdrawing someone else's; changing members, roles or invitations; accepting or declining an invitation; and opening billing.

Projects stored only in a browser's local storage are unavailable to either MCP connection. Destructive tools (delete, wholesale replace) are clearly marked. The local server lives in its own repository, railyard-sh/railyard-mcp, with install instructions for each client — or use the one-line install on the home page. Point your MCP client at it and give it a token.

The canonical document

Both the API and MCP server speak the same canonical Railyard JSON you get from export — one document describing the whole estate — so what you automate and what you design are the same shape.