🔌Overview

PicX runs a production Model Context Protocol 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.
Clients	Claude Desktop, Cursor, Claude Code, VS Code, Codex, or install via picx-cli

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 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, with https://api.picxstudio.com as the authorization server.

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 — Settings → Connectors, no config file
• 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 — picx mcp install --client <name> writes the right shape for you

Quick version, if you already know the shape:

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

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.