shipsafe-mcp

shipsafe-mcp

ShipSafe MCP server. Runs security scans locally inside Claude Code, Codex, and other MCP hosts. Source code never leaves your machine.

Status: published on npm. npx -y shipsafe-mcp pulls the latest. 0.7.0 adds the ShipSafe Coach skill — a pre-generation interrupt for Claude Code. See CHANGELOG.md.

Install

Claude Code:

claude mcp add --transport stdio shipsafe -- npx -y shipsafe-mcp

Codex — add to ~/.codex/config.toml:

[mcp_servers.shipsafe]
command = "npx"
args = ["-y", "shipsafe-mcp"]

Cursor — add to ~/.cursor/mcp.json (or the project-local .cursor/mcp.json):

{
  "mcpServers": {
    "shipsafe": {
      "command": "npx",
      "args": ["-y", "shipsafe-mcp"]
    }
  }
}

Tools

Tool	Free	Description
scan_repo	yes	Run Sentinel rules locally over a directory. Source never leaves your machine.
scan_url	yes	Scan a github.com/owner/repo URL via the public ShipSafe scan flow.
get_finding	yes	Fetch a finding detail from your ShipSafe account. Requires SHIPSAFE_TOKEN.
list_lessons	yes	List ShipSafe coaching lessons; optional topic filter.
explain_pragma	yes	Explain what a sentinel:ignore RULE-ID pragma silences.
suggest_fix	Available	LLM-generated fix (unified diff + explanation + CWE) for a finding. ~$0.05/call with BYOK Anthropic key, ~$0.25/call hosted. Requires SHIPSAFE_TOKEN and account balance.

Auth

The one-shot setup (recommended):

npx shipsafe-mcp claim <your-email> <otp-from-signup-email>

This swaps your OTP for an ssm_… token, writes it to ~/.shipsafe/token (chmod 600), and registers the MCP server with Claude Code if installed. The bearer is never passed through claude mcp add argv, so it cannot leak via ps auxe on shared systems.

If you prefer manual setup: visit https://shipsafe-web-eight.vercel.app/dashboard/mcp-tokens, issue a token, and either:

• export SHIPSAFE_TOKEN="ssm_..." in your shell profile, OR
• Write the token to ~/.shipsafe/token (chmod 600).

SHIPSAFE_TOKEN env still wins over the file when both are set.

Always-on integrations

The MCP tools fire when you ask. These integrations fire when you build — without you remembering.

Pre-generation interrupt for Claude Code (recommended)

npx shipsafe-mcp install-coach

Installs the ShipSafe Coach skill into ~/.claude/skills/shipsafe-coach/. Claude Code auto-activates the skill whenever your prompt mentions auth, webhooks, payments, secrets, RLS, AI agents, CSP, file uploads, privacy / PII, or CI/CD. Before generating, Claude pulls the relevant ShipSafe lesson via the MCP, surfaces 2-3 curated risks, and asks you to confirm constraints. Code is then generated honoring those constraints.

Bypass once: include skip shipsafe in your prompt. Remove: rm -rf ~/.claude/skills/shipsafe-coach/ Reinstall: npx shipsafe-mcp install-coach (refuses to overwrite an edited file unless you rm it first).

The skill calls the MCP's list_lessons tool at runtime; lesson content stays current as long as you keep invoking npx -y shipsafe-mcp (which you do on every MCP tool call).

Git pre-commit hook (recommended)

npx shipsafe-mcp install-hooks

Writes a Git pre-commit hook to .git/hooks/pre-commit that runs Sentinel on staged source files and blocks the commit if any critical-or-above findings appear. No project file edits, no Husky, no package.json changes.

Configure per-commit:

# Lower the bar (default: critical)
export SHIPSAFE_BLOCK_SEVERITY=high       # critical | high | medium | low | none

# Bypass once
git commit --no-verify

# Remove the hook
rm .git/hooks/pre-commit

If you already have a pre-commit hook that wasn't installed by us, the command refuses to overwrite it. Move or rename yours first, then re-run.

Claude Code: scan on every Edit / Write

Add to ~/.claude/settings.json (under hooks):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npx -y shipsafe-mcp scan . --severity critical --quiet && echo '' || echo '⚠️ shipsafe: critical finding(s) in this repo — run scan_repo or `npx shipsafe-mcp scan .` for details'"
          }
        ]
      }
    ]
  }
}

Effect: every time Claude Code edits or writes a file, this hook runs Sentinel against the repo and surfaces a one-line warning if any critical findings exist. The first run after install is slow (npx fetch); subsequent runs hit cache and finish in well under a second.

Match more file types, change the severity threshold, or change the message by editing the inline pipeline above.

GitHub Action: scan every PR

Drop the following into .github/workflows/shipsafe.yml:

name: shipsafe scan
on:
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Run shipsafe scan
        run: npx -y shipsafe-mcp scan . --severity critical

The job fails (and the PR check goes red) if Sentinel exits non-zero. For richer integration — posting findings as inline review comments, etc. — wire the JSON output through gh pr review.

Security model

scan_repo runs entirely local. No source code, no file contents, no paths are sent to ShipSafe. Findings appear in tool output only. By default it refuses to scan paths outside the current working directory — a prompt-injected host cannot make it walk /etc, ~/.ssh, ~/.aws, etc. Override with SHIPSAFE_ALLOW_ANY_PATH=1 set in the MCP server's env (not by the agent).

scan_url submits the GitHub URL to ShipSafe's anonymous public scan flow. The repo is cloned server-side, scanned, and the findings appear on a public report page.

get_finding and suggest_fix talk to your ShipSafe account over an authenticated bearer token.

All tool outputs are wrapped in untrusted-data delimiters and have C0 control chars stripped, mitigating the April 2026 MCP tool-result injection class of attacks. suggest_fix results carry an explicit APPLY_GUARD instructing the host not to auto-apply diffs.

See CHANGELOG.md for the full release history.

License

MIT