# @offlinecreator/mcp

MCP server + thin CLI for [OfflineCreator Studio](https://offlinecreatorstudio.com).

Gives Cursor, Claude Desktop, Claude Code, Hermes, Windsurf, and other MCP clients tools to list models, check credits, generate images/video, and wait for results.

**Current release:** [`@offlinecreator/mcp@0.1.1`](https://www.npmjs.com/package/@offlinecreator/mcp)

**Recommended remote MCP:** `https://mcp.offlinecreatorstudio.com/mcp` (Streamable HTTP + OAuth 2.1)

**API-key fallback:** local stdio or `https://offlinecreatorstudio.com/mcp`

## Setup

Add the recommended URL to your MCP client, then complete Studio browser
sign-in and consent. No API key is stored in the client configuration.

For local stdio or legacy remote fallback, create a scoped key in **Settings**
and copy the secret once (`oc_live_…` or `oc_test_…`).

### Environment

| Variable | Required | Description |
|----------|----------|-------------|
| `OFFLINECREATOR_API_KEY` | Yes | Personal API key from Settings |
| `OFFLINECREATOR_API_BASE` | No | API origin. Default `https://offlinecreatorstudio.com`. Localhost allowed; other hosts need `OFFLINECREATOR_ALLOW_INSECURE_API_BASE=true`. |
| `OFFLINECREATOR_UPLOAD_ROOT` | No | Directory that `upload_input` file paths must stay inside (default: process cwd). |
| `OFFLINECREATOR_ALLOW_INSECURE_API_BASE` | No | Set `true` only for private/non-prod API hosts. |

## Security notes

- API keys stay in env / MCP client config — tools never echo them.
- `upload_input` cannot read arbitrary disk paths: paths must stay under the upload root, use image extensions, pass size limits, and match image magic bytes.
- The client only calls `/api/v1/*` on a trusted API origin (HTTPS except localhost).
- Generations still use Studio moderation, credit reserve/refund, and ownership checks.

## Install by client

### Cursor

Recommended remote OAuth:

```json
{
  "mcpServers": {
    "offlinecreator": {
      "url": "https://mcp.offlinecreatorstudio.com/mcp"
    }
  }
}
```

API-key stdio fallback:

```json
{
  "mcpServers": {
    "offlinecreator": {
      "command": "npx",
      "args": ["-y", "@offlinecreator/mcp"],
      "env": {
        "OFFLINECREATOR_API_KEY": "oc_live_…"
      }
    }
  }
}
```

Never put the key in the URL or use `?api_key=`.

Local monorepo development:

```json
{
  "mcpServers": {
    "offlinecreator": {
      "command": "node",
      "args": ["C:/path/to/mcp_tool/packages/mcp/dist/index.js"],
      "env": {
        "OFFLINECREATOR_API_KEY": "oc_test_…",
        "OFFLINECREATOR_API_BASE": "http://localhost:3000"
      }
    }
  }
}
```

### Claude Desktop

Add `https://mcp.offlinecreatorstudio.com/mcp` in **Settings → Connectors →
Add custom connector**. Use the stdio JSON above in
`%APPDATA%\Claude\claude_desktop_config.json` as the API-key fallback.

### Claude Code

Remote OAuth:

```bash
claude mcp add offlinecreator --transport http https://mcp.offlinecreatorstudio.com/mcp
```

Local stdio:

```bash
claude mcp add offlinecreator --env OFFLINECREATOR_API_KEY=oc_live_… -- npx -y @offlinecreator/mcp
```

### Hermes

Add to `~/.hermes/config.yaml`, then run `/reload-mcp`:

```yaml
mcp_servers:
  offlinecreator:
    url: "https://mcp.offlinecreatorstudio.com/mcp"
```

### Windsurf

Add to `%USERPROFILE%\.codeium\windsurf\mcp_config.json`:

```json
{
  "mcpServers": {
    "offlinecreator": {
      "serverUrl": "https://mcp.offlinecreatorstudio.com/mcp"
    }
  }
}
```

### VS Code / Copilot

VS Code uses `servers` rather than `mcpServers`. Add to `.vscode/mcp.json` or
the MCP user configuration:

```json
{
  "servers": {
    "offlinecreator": {
      "type": "http",
      "url": "https://mcp.offlinecreatorstudio.com/mcp"
    }
  }
}
```

### Legacy remote API-key fallback

Clients that support fixed headers can still use:

```json
{
  "mcpServers": {
    "offlinecreator": {
      "url": "https://offlinecreatorstudio.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:OFFLINECREATOR_API_KEY}"
      }
    }
  }
}
```

Never put a key in the URL or use `?api_key=`.

## Tools

| Tool | Purpose |
|------|---------|
| `list_models` | Launch catalog + credit costs |
| `get_credits` | Current balance |
| `generate` | Start generation (`wait: true` to poll) |
| `upload_input` | Attach image for image-to-video, then submit |
| `get_generation` | Current status |
| `wait_generation` | Poll until done |
| `download_output` | Short-lived signed URL for a completed output |
| `cancel_generation` | Cancel reserved job + refund |
| `list_generations` | Recent jobs |

Tools are filtered by key scope (`models`, `read`, `generate`). Top-up
discovery and Checkout creation are CLI/API features, not MCP tools. They
always return a URL for a human browser action; agents never charge a payment
method directly.

## CLI sugar

```bash
npx @offlinecreator/mcp models
npx @offlinecreator/mcp balance
npx @offlinecreator/mcp topups
npx @offlinecreator/mcp topup --id topup-1000
npx @offlinecreator/mcp generate --model flux-schnell --prompt "A clean product still" --wait
```

## Development

```bash
npm install
npm run mcp:build
OFFLINECREATOR_API_KEY=oc_test_… OFFLINECREATOR_API_BASE=http://localhost:3000 npm run mcp:start
```

## Privacy note

Studio generations run on disclosed cloud providers (not on-device). LocalForge remains the offline product.