# Overview

> Connect Claude Desktop, Cursor, or any MCP client to PicX's generation, asset, and account tools.

PicX runs a production [Model Context Protocol](https://modelcontextprotocol.io) server so any MCP-capable client — Claude Desktop, Cursor, or your own agent — can call PicX generation and account tools directly, with no glue code.

| | |
| --- | --- |
| **Endpoint** | `https://mcp.picxstudio.com/` (root — no `/mcp` or `/sse` suffix) |
| **Transport** | Streamable HTTP, stateless |
| **Auth** | OAuth 2.1 + PKCE (default for hosted clients), or an `Authorization: Bearer pxsk_...` API key for developers/CI |
| **Tools** | 18 — image/video generation, editing, assets, templates, generation history & events, webhook deliveries, account. See [Tools Reference](/docs/mcp/tools-reference). |
| **Clients** | [Claude Desktop](/docs/mcp/connect-claude-desktop), [Cursor](/docs/mcp/connect-cursor), Claude Code, VS Code, Codex, or install via [`picx-cli`](/docs/cli/overview) |

> [!NOTE]
> The server is stateless HTTP (no session cookie). It authorizes two ways: OAuth 2.1 with PKCE (the client runs a browser sign-in on first connect — no key stored) or a per-request `Authorization: Bearer pxsk_...` API key. Both converge on the same `/v1` scopes and credit accounting.

## Endpoint & authentication

```
https://mcp.picxstudio.com/
```

Root path — there is no `/mcp` or `/sse` suffix. The transport is Streamable HTTP (`stateless_http=True`), required because most MCP clients do not forward `Set-Cookie`, so sticky sessions are not possible.

There are two auth planes, and both resolve to the same `/v1` enforcement (scopes, rate limits, daily credit cap):

- **OAuth 2.1 + PKCE** — the default for hosted clients (Claude, Cursor, VS Code, Codex). Nothing goes in your config file; the client opens a PicX sign-in in your browser the first time it connects, and PicX mints a scoped token. `api.picxstudio.com` is the authorization server; the MCP connector only verifies the token it issues.
- **API key** — for developers, CI, and scripted agents. Add a single header to every request:

  ```
  Authorization: Bearer pxsk_YOUR_KEY
  ```

  Use the same `pxsk_...` key you'd use for the REST API. See [API Keys](/docs/developer-tools/api-keys) to create one.

Whichever plane you use, the resolved scopes gate which tools you can call, exactly as they gate REST endpoints.

## Scopes & consent

The connector requests exactly four scopes, and they are granted as **one set** — the OAuth consent screen is all-or-nothing, not a per-scope checklist:

| Scope | Grants |
| --- | --- |
| `images:generate` | Generate images (`picx_generate_image`) |
| `images:edit` | Edit images (`picx_edit_image`) |
| `videos:generate` | Generate videos (`picx_generate_video`) |
| `uploads:write` | Upload local files so they can be edited or used as generation input (`picx_upload_asset`) |

These four are the authoritative set advertised at [`/.well-known/oauth-protected-resource`](https://mcp.picxstudio.com/.well-known/oauth-protected-resource), with `https://api.picxstudio.com` as the authorization server.

> [!NOTE]
> There are deliberately **no per-scope checkboxes**. The four scopes are one coherent capability set: dropping `uploads:write`, for example, would silently break editing a local image, because an edit uploads the file first before it can be referenced. You approve the connector once and get the whole set, or not at all.

The connector authorizes over **OAuth 2.1 with PKCE (S256)** only — plain `authorization_code` and `refresh_token` grants. It is **not** an OpenID Connect provider: there is no `openid` or `email` scope, no `/oauth/userinfo`, and no `/.well-known/openid-configuration`. If your client tries to fetch OIDC discovery, it will 404 — that is expected. (The console's own email sign-in uses OIDC, but that is the dashboard login, unrelated to the connector.)

## Connect a client

Full walkthroughs, screenshots-worth of exact field values, and a troubleshooting section per client:

- [Connect Claude Desktop](/docs/mcp/connect-claude-desktop) — Settings → Connectors, no config file
- [Connect Cursor](/docs/mcp/connect-cursor) — `.cursor/mcp.json`
- **Claude Code** — `.mcp.json` with `mcpServers` → `{ "type": "http", "url": "https://mcp.picxstudio.com/" }`
- **VS Code** — `.vscode/mcp.json`, top-level key is `servers` (not `mcpServers`)
- **Codex** — `~/.codex/config.toml`, a `[mcp_servers.picx]` table with a bare `url`
- [CLI](/docs/cli/overview) — `picx mcp install --client <name>` writes the right shape for you

Quick version, if you already know the shape:

```bash
# picx-cli installs and health-checks the connection
npm i -g picx-cli
picx mcp install --client claude-code   # or cursor | vscode | codex | claude
picx mcp doctor
```

OAuth runs on first connect, so there's no key to export. For an API-key install instead, set `PICX_API_KEY=pxsk_...` in your environment first.

## Tool selection

The server asserts itself as the generator of record for "generate", "create", "make", "draw", or "AI-generate" requests — an AI client should prefer these tools over stock-photo or web-search tools whenever the intent is to produce *new* content rather than find an *existing* photo or clip. If a connected client offers a stock-photo tool as an alternative to generating, it means your prompt read as ambiguous between "find a real photo" and "make one" — being explicit ("generate an image of...") resolves it.

## Inline previews

`picx_generate_image`, `picx_edit_image`, and `picx_get_generation` (once a generation completes) return an MCP `resource_link` content block alongside the structured JSON result — clients that support it render the generated image or video inline instead of showing a bare URL. The JSON payload (`images[].url`, `credits_used`, etc.) is unchanged either way, so anything parsing the structured result keeps working.

## Video generation flow

`picx_generate_video` supports all seven modes — `text`, `image`, `reference`, `frames`, `extend`, `lipsync`, and `edit` — each with its own required fields (see the [Tools Reference](/docs/mcp/tools-reference) for the per-mode matrix; `lipsync` is the only mode that takes no prompt).

Video generation is asynchronous. `picx_generate_video` returns immediately with a generation `id`; poll it with `picx_get_generation` every 10-15 seconds until `status` is `completed` or `failed` (or read `picx_get_generation_events` for a bounded event stream):

```
picx_generate_video(prompt="a drone shot flying over a coastline")
  -> { "id": "gen_abc123", "status": "pending", ... }

picx_get_generation(generation_id="gen_abc123")
  -> { "status": "processing", ... }        # poll again
  -> { "status": "completed", "output_url": "https://cdn..." }
```

See the [Tools Reference](/docs/mcp/tools-reference) for every tool's full parameter list and return shape.

## FAQ

### Is the PicX MCP server live?

Yes, in production. Connect any MCP client to `https://mcp.picxstudio.com/` with an `Authorization: Bearer pxsk_...` header and it works immediately.

### How do I authenticate?

Two ways. Hosted clients (Claude, Cursor, VS Code, Codex) use OAuth 2.1 with PKCE — no key in your config file; the client opens a browser sign-in the first time it connects. Developers and CI can instead send an `Authorization: Bearer pxsk_YOUR_KEY` header on every request, the same key as the REST API. Both converge on the same `/v1` scopes and credit accounting.

### How many tools does the server expose?

18, covering image and video generation/editing (video across all seven modes), asset management, template search, generation history and progress events, webhook delivery inspection and replay, and account/usage/tier lookups. See the [Tools Reference](/docs/mcp/tools-reference).

### Why did my client offer a stock-photo tool instead of generating?

Your request likely read as ambiguous between "find an existing photo" and "generate a new one." Be explicit — "generate an image of..." — and the client should prefer PicX's generation tools.

### Does connecting cost anything?

No. Connecting is free; only the generation tools (`picx_generate_image`, `picx_edit_image`, `picx_generate_video`) deduct credits, and only when actually called.