Shiped MCP setup — read this if you are an AI agent

You are an AI coding agent (Claude Code, Codex, Kiro, Cursor, or similar) and the user asked you to "set up Shiped", "connect Shiped", "add the Shiped MCP server", or pointed you at this file. Follow the steps below to configure yourself — don't just summarize this doc back to the user, actually do it.

What you're setting up

Once connected, you get three tools:

  • deploy_to_shiped(name, html?, files?) — deploy HTML/CSS/JS, get back a public URL
  • list_shiped_projects() — list the user's deployed projects
  • delete_shiped_project(slug) — delete one

There are two ways to connect — prefer remote HTTP when your client supports it (Claude Code, Codex): zero install, no npm package to fetch. Fall back to the local stdio server (npx @shiped/mcp) for clients that only support stdio (Kiro) or if the remote path has trouble in your environment.

Both paths use a one-time OAuth/device login instead of an API key — the first tool call opens a browser (or prints a code + link) for the user to approve. After that it's remembered and you never need to ask again.

Step 1 — detect which client you're running in

Check, in order:

  1. Is there a .kiro/ directory in the project, or were you invoked as Kiro? → Kiro (stdio only)
  2. Is there a .codex/ directory, or were you invoked as codex? → Codex (remote HTTP preferred)
  3. Is there a .claude/ directory, CLAUDE.md, or were you invoked as claude? → Claude Code (remote HTTP preferred)
  4. Otherwise, ask the user which of the above they're using, or default to the stdio JSON config (Step 2, Kiro section) since it's the most widely supported shape.

Step 2 — connect

Claude Code (remote HTTP — preferred)

claude mcp add --transport http shiped https://shiped.app/mcp

Claude Code discovers the OAuth endpoints automatically. On first tool call it prompts the user to authenticate — a browser opens, they sign in with Google and click Approve.

Codex (remote HTTP — preferred)

codex mcp add shiped --url https://shiped.app/mcp

Or write directly to ~/.codex/config.toml:

[mcp_servers.shiped]
url = "https://shiped.app/mcp"

Then run codex mcp login shiped to trigger the browser approval (or it happens automatically on first tool call, depending on the Codex version).

Kiro (stdio only)

Write (create if missing, merge if present) .kiro/settings/mcp.json in the project, or ~/.kiro/settings/mcp.json for a global install:

{
  "mcpServers": {
    "shiped": {
      "command": "npx",
      "args": ["-y", "@shiped/mcp"]
    }
  }
}

Also copy or symlink skills/shipd-deploy/SKILL.md from the Shiped repo into the user's Kiro skills directory if you have access to it, so future "deploy this" requests trigger automatically.

Any other MCP-standard client, or if remote HTTP has trouble

Fall back to stdio via npx:

claude mcp add shiped -- npx -y @shiped/mcp      # Claude Code
codex mcp add shiped -- npx -y @shiped/mcp       # Codex

Or the equivalent JSON: { "mcpServers": { "shiped": { "command": "npx", "args": ["-y", "@shiped/mcp"] } } }

This path uses a device-flow login instead: the first tool call prints a short code and a link instead of opening a browser directly — tell the user to open the link, confirm the code, and click Approve.

Step 3 — verify

Call list_shiped_projects(). Outcomes:

  • Remote HTTP, not yet authenticated: the client shows an "Authenticate" prompt, or the tool call fails until the user completes the browser flow. Tell them to look for the prompt / approve in the browser, then retry.
  • Stdio, not yet authenticated: a short code + URL is printed to stderr/logs. Tell the user to open the URL, confirm the code, click Approve, then retry.
  • Either path, already connected: you get a project list directly (empty or not) — done.

If the tool isn't found at all, the config write in Step 2 didn't take effect — check the file/command was applied correctly and, if the client requires a restart to pick up new MCP servers, tell the user to restart it.

Step 4 — tell the user what happened

Once verified, report back in one or two sentences: which client and which transport (remote HTTP or local stdio) you configured, and whether they need to do anything (approve in the browser) or it's already working. Do not walk them through this doc manually — you've already done it.

CI / headless fallback (no browser available)

Neither OAuth path works without a browser. For CI pipelines or scripted environments, use the stdio path with a dashboard-generated API key instead:

{ "mcpServers": { "shiped": { "command": "npx", "args": ["-y", "@shiped/mcp"], "env": { "SHIPED_API_KEY": "sk_live_..." } } } }

Generate the key at https://shiped.app/dashboard/settings. The remote HTTP transport does not support this fallback — always use stdio for CI.