Shipyard MCP

What is Shipyard MCP?

Shipyard MCP is a Model Context Protocol server that lets AI assistants like Claude manage Shipyard ephemeral environments directly. It is built into the Shipyard CLI and provides tools for environment, service, volume, and organization management.

How to use Shipyard MCP?

Install the Shipyard CLI using the install script, Homebrew, or a download from the releases page. Run shipyard login to authenticate and save your API token. Then add the MCP server to your AI assistant—for example, claude mcp add shipyard --env SHIPYARD_API_TOKEN=your-token --env SHIPYARD_ORG=your-org -- shipyard mcp serve—or configure it in Codex CLI’s ~/.codex/config.toml. The server listens for tool calls and executes them against the Shipyard API.

Key features of Shipyard MCP

• 7 environment management tools (list, get, stop, restart, rebuild, cancel, revive)
• 2 service management tools (list services, get logs)
• 5 volume management tools (list, reset, snapshot create/load, list snapshots)
• 3 organization management tools (list orgs, get/set default org)
• Limitations: exec, port‑forward, and telepresence return help text directing users to the CLI.

Use cases of Shipyard MCP

• AI assistant lists all environments filtered by branch or repo name.
• Assistant stops, restarts, or rebuilds a specific environment on command.
• Assistant revives a deleted environment or cancels an ongoing build.
• Assistant manages volume snapshots: lists, creates, loads, resets volumes.
• Assistant shows current organization or switches default org without leaving the chat.

FAQ from Shipyard MCP

How do I authenticate the MCP server?

You can authenticate by setting the SHIPYARD_API_TOKEN environment variable (get your token from your Shipyard profile page) and optionally SHIPYARD_ORG. Alternatively, run shipyard login once to save your token locally—then the MCP server reuses that configuration.

What tools does the MCP server expose?

It exposes 17 tools in four categories: environment management (7), service management (2), volume management (5), and organization management (3). Three tools (exec, port‑forward, telepresence) are limited and return instructions to use the CLI directly.

Can I run commands inside a service container via MCP?

No—the exec_service tool is limited; it only returns help text telling you to use shipyard exec from the CLI. For interactive commands, use the command line.

How do I add Shipyard MCP to Claude Desktop?

Run claude mcp add shipyard --env SHIPYARD_API_TOKEN=your-token --env SHIPYARD_ORG=your-org -- shipyard mcp serve. If you already configured the CLI with shipyard login, you can omit the environment variables.

What are the prerequisites for using Shipyard MCP?

You need a Shipyard account with API access enabled, a valid SHIPYARD_API_TOKEN, and optionally an organization name. The CLI must be installed and authenticated. The MCP server works on Linux, macOS, and Windows.