# 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)

```bash
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)

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

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

```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:

```json
{
  "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:

```bash
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:

```json
{ "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.