MCP

Text size

MCP

The Shipyard CLI includes a Model Context Protocol (MCP) server, shipyard mcp serve. AI assistants such as Claude Code, Claude Desktop, Cursor, Codex and Kiro use it to list, inspect, rebuild and debug your Shipyard environments.

Use it for writing and running tests, code review, incident triage, and verifying a change against its environment before you merge.

tip

Use the Shipyard MCP integration with the Playwright MCP integration for visual testing with agents against your Shipyard environments.

Learn more: Playwright MCP on GitHub

Full reference

This page is a summary. The full guide (configuration, every tool, the verify prompt, troubleshooting) lives with the CLI: docs/mcp.md on GitHub.

Installation

The MCP server needs Shipyard CLI 1.9.0 or later.

brew tap shipyard/tap
brew install shipyard
shipyard --version

Other install methods: Shipyard CLI README.

Log in, so the server can find your token:

shipyard login

If you belong to more than one org, set a default: shipyard set org <org_name>.

Plugin

Claude Code, Codex, Cursor and Kiro can install the Shipyard plugin. It adds the MCP server and a short skill that tells the assistant how to use it safely, in one step. The plugin contains no code and no token: it runs shipyard mcp serve, so you still need the CLI installed and shipyard login.

Client	Install
Claude Code	claude plugin marketplace add shipyard/shipyard-plugins, then claude plugin install shipyard@shipyard
Codex	codex plugin marketplace add shipyard/shipyard-plugins, then codex plugin add shipyard@shipyard
Cursor	cursor-agent plugin marketplace add https://github.com/shipyard/shipyard-plugins, then Cursor Settings, Plugins: install Shipyard
Kiro	In the Powers panel, install from the GitHub URL https://github.com/shipyard/shipyard-plugins

Cursor Auto-Run

The Cursor app decides whether to ask from its Auto-Run setting, not from the tool hints. With Auto-Run on and MCP Tools Protection off, Cursor runs Shipyard tools without asking, including stop_environment. Before you connect Shipyard, open Cursor Settings, Auto-Run, and choose Ask Every Time or turn on MCP Tools Protection. Then check that a destructive call asks you first.

The plugin runs shipyard from the PATH the client sees, and you can't change that command. If the server fails to start with "command not found" (desktop apps opened from the Dock or Start menu may not see your shell's PATH), use the manual setup below instead, with the absolute path from which shipyard as the command.

Restart the session afterwards. Use the plugin or the manual setup below, not both. If you added a server by hand, remove it first (claude mcp remove shipyard, or delete the entry from Cursor's or Kiro's mcp.json). Otherwise Claude Code may keep your server and skip the plugin's, so the plugin's permission rule below doesn't match. Codex is the exception: a [mcp_servers.shipyard] entry replaces the plugin's server, so you can keep one for the Unattended use settings below.

Setup

Every client runs the same command, shipyard mcp serve. After shipyard login, no token is needed in the client config.

Keep your token out of project files

.cursor/mcp.json, .kiro/settings/mcp.json and Claude Code's .mcp.json live in the repository and tend to get committed. Use shipyard login, or put the token in a per-user file only.

Desktop apps often don't see your shell's PATH. If the server fails to start, use the absolute path from which shipyard as the command.

Claude Code

claude mcp add shipyard -- shipyard mcp serve

Add --scope user to make it available in every project. Check it with /mcp inside Claude Code.

Claude Desktop

Settings, Developer, Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "shipyard": {
      "command": "/opt/homebrew/bin/shipyard",
      "args": ["mcp", "serve"]
    }
  }
}

Replace the command with the output of which shipyard, then restart Claude Desktop.

Cursor

~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "shipyard": {
      "command": "shipyard",
      "args": ["mcp", "serve"]
    }
  }
}

Reload the window, then check Settings, MCP. Cursor asks you to approve the server the first time, and again if its command changes.

Codex CLI

codex mcp add shipyard -- shipyard mcp serve

Or edit ~/.codex/config.toml:

[mcp_servers.shipyard]
command = "shipyard"
args = ["mcp", "serve"]

OpenCode

~/.config/opencode/opencode.jsonc (every project) or opencode.jsonc (one project).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "shipyard": {
        "type": "local",
        "command": ["shipyard", "mcp", "serve"]
      }
    }
  }
}

Check the connection with /mcps inside OpenCode or opencode mcp list.

Kiro

~/.kiro/settings/mcp.json (every workspace) or .kiro/settings/mcp.json (one workspace). The Kiro IDE and Kiro CLI share these files.

{
  "mcpServers": {
    "shipyard": {
      "command": "shipyard",
      "args": ["mcp", "serve"]
    }
  }
}

Kiro reloads the file on save. Read Unattended use before running Kiro CLI non-interactively.

Then start a new session and ask "list my Shipyard environments".

Tools

From Shipyard CLI 1.10.0, each tool tells the client whether it only reads, may change or remove something, or only adds state. Clients use this to decide when to ask you.

Read-only

• get_environments, get_environment: list environments, or one environment's details
• get_build_history: an environment's builds
• get_failure_details (Shipyard CLI 1.10.0 or later): why a build failed, in one call (phase, reason, failing services, log excerpts)
• get_build_logs (Shipyard CLI 1.10.0 or later): a build's stored build, run or crash logs, also after the environment stopped
• get_services, get_logs: services in an environment, and their logs
• get_env_vars: environment variables (hidden values masked)
• get_volumes, get_snapshots: volumes and their snapshots
• get_orgs, get_org: your orgs, and the current default
• port_forward: returns the CLI command to run; forwards nothing itself

May change or remove something

• stop_environment, cancel_environment, rebuild_environment: stop, cancel the latest build, rebuild
• update_branches: point repos in an environment at other branches
• restart_service: restart one service
• put_env_vars, delete_env_var: set or delete environment variables
• reset_volume, load_snapshot: reset a volume, or restore a snapshot over it
• exec_service: run a command in a service container. Off by default; enable with SHIPYARD_MCP_ALLOW_EXEC=true in the client's env, or mcp.allow_exec: true in ~/.shipyard/config.yaml
• set_org: change the default org that later calls use
• telepresence_connect: run telepresence connect on your machine

Only adds state

• restart_environment, revive_environment: start a stopped environment, revive a deleted one
• deploy_detached: create an independent copy of an environment
• create_snapshot: snapshot a volume

The server also provides a verify prompt that walks an agent through checking a pushed change against its environment. See the full reference.

Unattended use

In an interactive session, each client asks before a tool call. For an agent that runs on its own (script, CI, headless session), allow only the read-only tools:

Client	Setting
Claude Code	"permissions": {"allow": ["mcp__shipyard__get_*"]} in .claude/settings.json, or claude -p --allowedTools "mcp__shipyard__get_*". With the plugin, use mcp__plugin_shipyard_shipyard__get_* instead.
Codex	With Shipyard CLI 1.10.0 or later: default_tools_approval_mode = "writes" under [mcp_servers.shipyard] (it relies on the tool hints added in 1.10.0). With Shipyard CLI 1.9.0: approve each read-only tool instead, one table per tool, for example [mcp_servers.shipyard.tools.get_orgs] with approval_mode = "approve". With the plugin, keep command and args in the [mcp_servers.shipyard] block: it replaces the plugin's server.
Cursor CLI	"permissions": {"allow": ["Mcp(shipyard:get_*)"]} in .cursor/cli.json or ~/.cursor/cli-config.json. Needs a server added by hand: cursor-agent doesn't load the plugin's server.
Kiro CLI	"disabledTools": [...] listing every tool under "May change or remove something" and "Only adds state" (otherwise deploy_detached can still create environments). Kiro CLI non-interactive mode runs MCP tools without asking. disabledTools is a block-list: a tool added in a later release is enabled until you list it, so recheck after each Shipyard CLI upgrade. Set it on a server you added by hand, and uninstall the Shipyard power first: the power's server is not covered by it.

Prefer an org API key over your personal token for shared machines and CI: it only reaches one org. Details: Permissions and least privilege.

Updating and removing

• Update: shipyard upgrade (Shipyard CLI 1.10.0 or later), or brew upgrade shipyard. Restart the client afterwards.
• Update the plugin: claude plugin update shipyard@shipyard or codex plugin marketplace upgrade shipyard. In Cursor, run cursor-agent plugin marketplace update shipyard, then reinstall the plugin from Cursor Settings, Plugins. In Kiro, uninstall the power and import it from GitHub again.
• Remove from a client: claude mcp remove shipyard, codex mcp remove shipyard, or delete the shipyard entry from the Cursor, Kiro or Claude Desktop config file.
• Remove the plugin: claude plugin uninstall shipyard@shipyard, codex plugin remove shipyard@shipyard, uninstall it from Cursor Settings, Plugins, or uninstall the power from Kiro's Powers panel.
• Remove the token: delete api_token from ~/.shipyard/config.yaml.

More, including rolling back to an earlier release: Updating, uninstalling and rolling back.

Troubleshooting

• "Connection closed", or unknown command "mcp": the shipyard the client runs is older than 1.8.0. Run which -a shipyard, then upgrade or remove the stale copy, or use the newer binary's absolute path.
• Tools fail with a missing token: run shipyard login. The client's environment is not your shell's.
• More: Troubleshooting.