MCP documentation

Connect Upscayl to Codex

Upscayl runs a stateless Streamable HTTP MCP endpoint on Cloudflare Pages. Authentication uses the same paid-account API keys as the REST API.

Get an API key REST API docs

Before you connect

An Upscayl account with at least one completed credit purchase.
An active API key created on the API Keys page.
Codex CLI or another client that supports remote Streamable HTTP MCP servers.

Add the remote server

Put the key in an environment variable, then tell Codex which variable supplies the bearer token.

Terminal

export UPSCAYL_API_KEY="up_live_your_key"
codex mcp add upscayl --url https://www.upscayl.app/api/mcp --bearer-token-env-var UPSCAYL_API_KEY

Equivalent config.toml

[mcp_servers.upscayl]
url = "https://www.upscayl.app/api/mcp"
bearer_token_env_var = "UPSCAYL_API_KEY"

Verify the connection

Restart Codex after changing the environment or configuration. Ask it to list the Upscayl products or check your credit balance before submitting an image.

Tool reference

Tool	Purpose	Important behavior
`upscayl_list_products`	List available Upscayl MCP products.	Read-only and does not spend credits.
`upscayl_get_credit_balance`	Return the account's available paid credits.	Read-only and authenticated.
`upscayl_upscale_image`	Start a 2x or 4x upscale from a public HTTPS URL.	Requires an 8–128 character idempotency key. Reserves 0.7 credit.
`upscayl_get_task`	Get task status and the finished image URL.	Only returns tasks owned by the authenticated account.

Example requests for Codex

“Check my Upscayl credit balance.”

“Upscale this image 4x with Upscayl: https://example.com/photo.jpg”

“Check the status of Upscayl task TASK_ID and give me the result URL.”

Billing and task lifecycle

A new task reserves 0.7 credit through the same atomic credit function as the REST API.
The credit is finalized when the image succeeds.
A failed task is refunded automatically and retries with the same idempotency key do not charge twice.
Tasks are asynchronous. Poll after about 3 seconds, then increase the interval.

Safe retries

Generate a new idempotency key for each new image job.
Reuse that exact key only when retrying the same input and options.
Do not submit a second create call just to check progress; use upscayl_get_task.
Respect Retry-After when the service returns a rate or concurrency limit.

Common errors

HTTP	Meaning	What to do
401	Missing, invalid or revoked API key.	Create a new active key and update the environment variable.
402	Not enough credits.	Purchase credits, then retry the same job with the same idempotency key.
403	No paid API access or insufficient key scope.	Complete a purchase or create a key with the required scopes.
429	Rate, daily or concurrent-task limit reached.	Wait for Retry-After or for an active task to finish.
5xx	Temporary processing or dependency failure.	Retry with the same idempotency key after a short delay.

Raw endpoint

Most users should configure this URL in an MCP client rather than calling it manually. The endpoint accepts MCP JSON-RPC over Streamable HTTP and requires a bearer API key.

https://www.upscayl.app/api/mcp