# Install the BrShot MCP server

You are an AI agent. The user asked you to connect BrShot, which makes images, videos and audio, to the client you
run in. Do every step yourself by running the commands. Do not install any package: BrShot is a remote server.

- Server URL: `https://mcp.brshot.com/mcp` (Streamable HTTP)
- Auth: OAuth. The user signs in to BrShot in the browser, and you never handle a password.
- Headless or CI: an API key sent as `Authorization: Bearer <key>`. After an OAuth sign-in, the user can create one
  with the `create_api_key` tool.

## 1. Find your client and add the server

**Claude Code**
```bash
claude mcp add --transport http --scope user brshot https://mcp.brshot.com/mcp
claude mcp login brshot          # opens the browser; on a remote machine add --no-browser and paste the redirect URL
```

**Codex CLI**
```bash
codex mcp add brshot --url https://mcp.brshot.com/mcp
codex mcp login brshot
```

**Cursor:** add this to `~/.cursor/mcp.json`, then click "Needs login" next to brshot in Settings → MCP.
```json
{ "mcpServers": { "brshot": { "url": "https://mcp.brshot.com/mcp" } } }
```

**VS Code (Copilot):** run this, then start the server from the MCP view and sign in.
```bash
code --add-mcp '{"name":"brshot","type":"http","url":"https://mcp.brshot.com/mcp"}'
```

**Windsurf:** add this to `~/.codeium/windsurf/mcp_config.json`.
```json
{ "mcpServers": { "brshot": { "serverUrl": "https://mcp.brshot.com/mcp" } } }
```

**Claude.ai or Claude Desktop:** you cannot add it yourself. Tell the user to open Settings → Connectors → Add custom
connector, enter Name `BrShot` and URL `https://mcp.brshot.com/mcp`, then click Connect and sign in.

**Any client that only runs local (stdio) servers:** use the generic bridge. It contains no BrShot code.
```json
{ "mcpServers": { "brshot": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.brshot.com/mcp"] } } }
```

**With an API key instead of OAuth (CI):**
```bash
claude mcp add --transport http --scope user brshot https://mcp.brshot.com/mcp --header "Authorization: Bearer $BRSHOT_API_KEY"
```

## 2. Sign in

When the client opens the BrShot sign-in page, the user signs in with email (a password or an email link) or Google.
If you are on a machine with no browser, give the user the printed URL and paste back the redirect URL they get.

## 3. Check it works

Restart the client or reload its MCP servers if it needs that. Then call `account_status` and `list_models`, and tell
the user how many models they can use and how many credits they have.

## How to use it

- Quote first: `quote(model, params)` shows the cost in credits. `generate` holds those credits and never charges
  more. A failed take is refunded.
- Always pass your own `idempotency_key` to `generate`. If a job is still `processing`, poll `get_job`; never call
  `generate` again for the same take.
- Media inputs are refs. Upload the user's own file with `get_upload_url` (HTTP PUT) or `upload_media` (small
  files), then pass `brshot:upload/<id>`. Pass an earlier output as `brshot:job/<id>`.
- Download links in results are signed and expire after one hour. Call `get_download_url` for a fresh one.
- Every account gets free credits each month (they reset on the 1st and do not roll over). If the user has a
  promo code, call `redeem_code`. If `generate` answers `free_paused`, free credits are paused until 00:00 UTC;
  credits from a promo code still work.
- BrShot refuses sexual and violent content.
- Models with a rights input need `params.rights = true`. Set it only after the user explicitly confirms the wording
  shown in `list_models` for that request.
