# MCP Server Setup

Use rukprompt with Claude Desktop / Claude Code / Cursor — or any MCP-aware client. The recommended UX is `npx @rukprompt/cli`; the underlying HTTP transport is also documented below as the **base layer** for advanced use cases.

## ✨ Recommended: `@rukprompt/cli` (npx)

One command — picks the right config path for your client, validates your key against the backend, and writes the entry safely (with a `.bak` backup of the previous file):

```bash
npx -y @rukprompt/cli install claude-desktop --api-key sk-img-...
npx -y @rukprompt/cli install claude-code   --api-key sk-img-...
npx -y @rukprompt/cli install cursor        --api-key sk-img-...
```

After install, restart your MCP client and ask: *"list my rukprompt presets"* — it will call `preset_list` automatically.

### Manual config (any of the three clients — same shape)

```json
{
  "mcpServers": {
    "rukprompt": {
      "command": "npx",
      "args": ["-y", "@rukprompt/cli", "mcp"],
      "env": { "RUKPROMPT_API_KEY": "sk-img-..." }
    }
  }
}
```

### Why CLI over direct HTTP?

- Stdio transport — works on every MCP client without quirks
- No `"type": "http"` config gotchas
- One-line install: `rukprompt install claude-desktop`
- Auto-updates via `npx -y` (always pulls latest published version)
- Direct CLI usage too: `rukprompt preset list`, `rukprompt image generate ...`

### Key management

```bash
rukprompt key set --api-key sk-img-...   # validate + persist to ~/.rukprompt/config.json (mode 0600)
rukprompt key show                       # masked key + last validated time
rukprompt key test                       # ping backend to verify
rukprompt key clear                      # remove from this machine
```

When you rotate a key, just run `rukprompt key set --api-key sk-img-newxxx...` again — the next CLI spawn picks it up.

## Tools (11)

### Presets
| Tool | Description |
|---|---|
| `preset_list` | List presets the team can use. Optional `teamOnly: boolean`. |
| `preset_get` | Read one preset. `{ presetId: string }` |
| `preset_create` | Create a new team preset. Body matches `POST /v0/images/presets`. |
| `preset_update` | Update a team preset. Body matches `PATCH /v0/images/presets/:presetId`. |
| `preset_delete` | Remove a preset from the team. `{ presetId: string }` |

### Images
| Tool | Description |
|---|---|
| `image_generate` | Generate an image. Body matches `POST /v0/images/generations`. |
| `image_list` | List the team's generated images (paginated). Optional `presetId` / `search` filters. |
| `image_get` | Read one image's metadata + URL by `imageId`. |
| `image_download` | Get the public URL + filename + size of an image, or pass `asBase64: true` to receive the bytes inline as MCP image content. |

### Models
| Tool | Description |
|---|---|
| `model_list` | List image-generation models the team can use (id, providerType, supported resolutions/aspect ratios, credit costs). Same payload as `GET /v0/models`. |

### Credits / Usage
| Tool | Description |
|---|---|
| `credits_check` | Read the team's credit balance + recent burn rate. Returns `creditsRemaining`, `creditsUsed`, `completedJobs`, a `status` flag (`ok` / `low` / `critical`), a `warning` string when credits are low, and the 5 most recent jobs. Call before bulk `image_generate` to avoid mid-batch failures. Optional `from` / `to` ISO dates narrow the window. |

For preset / variable schemas, see [presets.md](./presets.md).

## Quick reference

| Goal | Command |
|---|---|
| Install + set key (Claude Desktop) | `npx -y @rukprompt/cli install claude-desktop --api-key sk-img-...` |
| Install + set key (Claude Code) | `npx -y @rukprompt/cli install claude-code --api-key sk-img-...` |
| Install + set key (Cursor) | `npx -y @rukprompt/cli install cursor --api-key sk-img-...` |
| Just save key (no client config) | `npx -y @rukprompt/cli key set --api-key sk-img-...` |
| Test current key | `npx -y @rukprompt/cli key test` |
| Show current key (masked) | `npx -y @rukprompt/cli key show` |
| Rotate key | `npx -y @rukprompt/cli key set --api-key sk-img-newxxx...` |
| Remove key from this machine | `npx -y @rukprompt/cli key clear` |
| List presets from terminal | `npx -y @rukprompt/cli preset list` |
| Generate image from terminal | `npx -y @rukprompt/cli image generate --prompt "..." --out img.png` |
| Run proxy directly (debug) | `RUKPROMPT_API_KEY=sk-img-... npx -y @rukprompt/cli mcp` |

## Direct HTTP (advanced / base layer)

The CLI is a thin wrapper around the HTTP MCP at `POST /v0/mcp`. If you'd rather skip the npx layer — for instance integrating from a non-Node runtime, or scripting curl calls — you can connect directly:

```
URL:        https://developer.rukprompt.com/v0/mcp
Transport:  streamable-http
Auth:       Authorization: Bearer sk-img-...
```

`GET /v0/mcp` returns server metadata + the list of available tools (no auth needed for the metadata endpoint).

### Direct config in MCP clients

```json
{
  "mcpServers": {
    "rukprompt": {
      "type": "http",
      "url": "https://developer.rukprompt.com/v0/mcp",
      "headers": {
        "Authorization": "Bearer sk-img-..."
      }
    }
  }
}
```

> **Note**: Claude Code CLI requires the `"type": "http"` field. Without it the config is rejected with *"Does not adhere to MCP server configuration schema"*.

### Raw JSON-RPC (testing)

Streamable HTTP is just JSON-RPC 2.0 over HTTP. Test with `curl`:

```bash
# List tools
curl -s -X POST https://developer.rukprompt.com/v0/mcp \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

# Call a tool
curl -s -X POST https://developer.rukprompt.com/v0/mcp \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0","id":2,
    "method":"tools/call",
    "params":{"name":"preset_list","arguments":{"teamOnly":true}}
  }' | jq
```

### Inspector

Use the official MCP Inspector to debug interactively (works with both transports):

```bash
# Via CLI (stdio):
npx @modelcontextprotocol/inspector \
  --command "npx -y @rukprompt/cli mcp" \
  --env "RUKPROMPT_API_KEY=$KEY"

# Or direct HTTP:
npx @modelcontextprotocol/inspector \
  --url https://developer.rukprompt.com/v0/mcp \
  --header "Authorization: Bearer $KEY"
```

## Auth Notes

- The same `sk-img-...` key works for both CLI and direct HTTP — there's only one underlying transport (`/v0/mcp`).
- Each MCP `tools/call` is logged in `developer_api_usage` like a regular REST hit.
- The transport is **stateless** — each request authenticates independently. No long-lived MCP session state on the server.
- All operations are scoped to the API key's team. The MCP server cannot be coerced into reaching across teams.