Claude Code

Claude Code connects through the Stableship plugin. It brings:

• The MCP server, so Claude can read findings, fix briefs and rules, start checks and verify fixes.
• /stableship:gate, a command for the common jobs (below).
• The stableship skill. Claude loads it on its own before it changes sign-in, data access, payments or migrations: read the rules, give every new Supabase table row level security, keep the service-role key out of client code, and propose rule changes instead of making them.
• Hooks. At the start of a session Claude hears about open blocking findings. Before it edits a file about sign-in, data, payments or the database, it gets the rules for that file. Verdicts and new blocking findings arrive in the session as they land.

In a terminal, npx --yes @stableship/cli@latest init does both connect steps below in one go: it signs you in, and when the claude command is on that terminal's PATH it installs the plugin. When claude is not found, init signs you in and asks you to connect your agent; install the plugin with the first step below. Installing the plugin also removes a separate stableship MCP server you may have added before: the plugin brings its own, and with both, every tool is listed twice.

Connect

1. Install the plugin in your terminal:

   claude plugin marketplace add stableship-ai/claude-plugins && claude plugin install stableship@stableship

2. Sign in, then approve in the browser:

   npx --yes @stableship/cli@latest login

The sign-in opens app.stableship.ai in your browser: sign in, pick the workspace and approve. No token to copy.

Use a token instead

First make a token: in Stableship open Settings, then Connections, open API tokens and connected apps, and choose Create token with Read findings and rules and Start checks and verify fixes. Copy it: it starts with sst_ and is shown once. Use it where these steps say sst_your_token.

Without the plugin, add only the MCP server with a token. Use the plugin or this, not both: both list every tool twice.

In your terminal:

claude mcp add --transport http stableship https://api.stableship.ai/mcp --scope user --header "Authorization: Bearer sst_your_token"

Keep the token out of your repository.

Check it works

Open a new Claude Code session, or run /clear. Then ask Claude Code to list your Stableship projects: it calls list_projects and names your app.

If it does not connect:

• Run /plugin: Stableship should be installed and on.
• Run /mcp: Stableship should say connected.

The /stableship:gate command

Stableship checks the code on GitHub, not your local files. check tells you when you have unpushed work, and fix pushes the fix (after asking) before it can verify it. fix never weakens tests, row level security policies or auth checks to make a finding go away.

Keep Claude out of .env files

A plugin cannot set permission rules, so add these to your project's .claude/settings.json (or ~/.claude/settings.json for every project):

{  "permissions": {    "deny": ["Read(.env)", "Read(.env.*)", "Edit(.env)", "Edit(.env.*)"]  }}

These rules cover Claude's file tools at any depth in the project. They do not stop a shell command such as cat .env, so keep Bash prompts on.

If something is off

• /stableship:gate is missing. Run /plugin and check that stableship is installed and turned on.
• Tools fail with "unauthorized". Run /mcp, pick the Stableship server and choose Authenticate. If you disconnected it in Stableship (Settings, then Connections, then Connected apps), authenticate again.
• "Not connected" for your repository. The repository's GitHub origin must be a repository connected to a Stableship app. Check with git remote get-url origin.
• The check says your changes are not included. Push the branch, then check again.
• No note at the start of a session. That is expected when nothing blocks.