Agentic-first MCP

MCP Server

Point your coding agent at the ShipOS MCP server and it manages flags for you, create them, ramp rollouts, promote configs, and pull kill switches without ever leaving the editor. Twelve tools, full parity with the dashboard.

Connection

The server speaks the streamable HTTP transport at https://mcp.shipos.app/mcp. Legacy SSE clients can use https://mcp.shipos.app/sse instead.

Authentication

Every request carries an agent key in the Authorization header. Create one in the ShipOS dashboard under Keys.

http

Authorization: Bearer sos_agt_...

Which key works on MCP

Agent keys (sos_agt_*) and admin keys (sos_adm_*) work on the MCP server. SDK keys (sos_sdk_*) do not, those are publishable and only work on the edge evaluate API.

Connect from Claude Code

Drop the server into your project's .mcp.json:

.mcp.jsonjson

{
  "mcpServers": {
    "shipos": {
      "type": "http",
      "url": "https://mcp.shipos.app/mcp",
      "headers": { "Authorization": "Bearer sos_agt_..." }
    }
  }
}

Or add it from the CLI:

bash

claude mcp add --transport http shipos https://mcp.shipos.app/mcp \
  --header "Authorization: Bearer sos_agt_..."

The twelve tools

Every tool takes an optional projectSlug. With a single project it's inferred; with several, the tool lists them so the agent can pick.

Tool	What it does
`list_flags`	All flags in a project with per-env state (✅ on / ⬜ off / 🔴 killed) and rollout %.
`get_flag`	Full detail: per-env config, targeting rules pretty-printed, versions.
`create_flag`	Create a flag (boolean/string/number/json); replies with a paste-ready SDK snippet.
`update_flag`	Rename or re-describe a flag.
`archive_flag`	Soft-archive; SDKs fall back to the default value.
`toggle_flag`	Turn a flag on/off in one environment.
`set_rollout`	Set the % rollout, stable bucketing, so raising only adds users.
`set_targeting`	Replace targeting rules, validated before the API sees them.
`kill_flag`	Emergency kill switch, OFF for 100% of traffic in seconds.
`promote_config`	Copy a full env config, e.g. staging → prod.
`get_evaluation_stats`	On/off/total evaluation counts over 24h / 7d / 30d.
`get_audit_log`	Who did what, when, humans by email, agents by key prefix.

Example session

Ask in plain language; the agent picks the tools. Here it gates a new checkout flow behind a flag and stages a 10% rollout in prod.

text

You: gate the new checkout behind a flag, roll it out to 10% in prod

Claude → create_flag { key: "checkout-v2", description: "New checkout flow" }
  ✅ Created flag "checkout-v2" (boolean) in project "shop".
     All environments start OFF, toggle_flag turns it on,
     set_rollout ramps it gradually.

Claude → set_rollout { key: "checkout-v2", env: "prod", percent: 10 }
  ✅ checkout-v2 @ prod → 10% rollout

Safety

A valid agent key executes mutations directly, there is no human sign-off step. Autonomy stays safe because everything an agent does is both traceable and instantly reversible: every action is audited (humans by email, agents by key prefix) and every flag is one call away from OFF.

Audit trail

Pull get_audit_log to see every change, attributed to the exact human or agent key.

Instant kill switch

kill_flag forces a flag OFF for 100% of traffic in seconds, the fastest way to undo any change.

Scope keys to what an agent needs

Give an agent a key scoped to a single project, keep prod keys separate from dev, and revoke a key the moment it is no longer needed. Keys are managed in the dashboard under Keys.