> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Model Context Protocol (MCP) server
> Connect MCP-compatible agents to Krea with OAuth or an API key to discover models, inspect schemas, and generate images and videos.
Krea exposes a hosted Model Context Protocol (MCP) server for agents and coding assistants. Use it when you want an MCP-compatible client to call Krea directly instead of writing API requests by hand.
You do not need an API key to connect. Add `https://api.krea.ai/mcp` as the MCP server URL, then sign in with your Krea account through your client's OAuth flow.
## Server Details
| Setting | Value |
| -------------- | ------------------------- |
| Transport | Streamable HTTP |
| URL | `https://api.krea.ai/mcp` |
| Authentication | OAuth |
Billing depends on how you authenticate:
| Authentication method | Billing source |
| --------------------- | -------------------------------------------------------- |
| OAuth | Compute units on the workspace you select during consent |
| API token | Your workspace's separate API balance |
## Authentication
Most MCP clients use OAuth automatically. When the client asks you to connect, follow the browser sign-in flow and authorize Krea.
### Choose a workspace during consent
The OAuth consent screen includes a **Workspace** picker that lists every workspace you belong to. Your default workspace is pre-selected; pick a different one if you want this MCP session to run somewhere else (for example, a shared studio workspace instead of your personal one).
The workspace you select is bound to the OAuth session and determines:
* **Billing.** Compute units are deducted from the selected workspace, not just the signed-in account.
* **Asset scope.** Files uploaded through tools such as `upload_asset` are saved to the bound workspace, and tools that require an upload (for example, `get_upload_url`) only work once a workspace is bound.
To switch the bound workspace later, disconnect Krea in your MCP client and reconnect — you'll see the picker again.
Legacy OAuth sessions created before the workspace picker shipped do not have an explicit binding. Those sessions fall back to your account's default workspace. Reconnect to bind the session to a specific workspace.
If your MCP client does not support OAuth, you can authenticate with an API token instead:
| Header key | Header value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer KREA_API_TOKEN` |
Replace `KREA_API_TOKEN` with a token from [krea.ai/app/api/tokens](https://www.krea.ai/app/api/tokens). Only workspace owners and admins can create API tokens.
API-token usage is billed to your workspace's API balance, the same as direct API calls. See [API Keys & Billing](/developers/api-keys-and-billing) for API balance details.
Store API-token MCP credentials the same way you store API keys. Do not commit MCP configuration files that contain real tokens.
## Claude Code
Run this command in your terminal:
```bash theme={null}
claude mcp add --transport http krea-ai https://api.krea.ai/mcp
```
Sign in with your Krea account when Claude Code asks you to connect. Restart Claude Code or reload your MCP servers after adding the server.
## Codex
1. Open **Settings** > **MCP servers** in Codex.
2. Add a new server.
3. Select **Streamable HTTP** as the transport.
4. Paste the server URL:
```text theme={null}
https://api.krea.ai/mcp
```
5. Save the server and sign in with your Krea account when Codex asks you to connect.
## Cursor
Open the command palette, search for **Open MCP settings**, then add this entry to `mcp.json`:
```json theme={null}
{
"mcpServers": {
"krea-ai": {
"url": "https://api.krea.ai/mcp"
}
}
}
```
Restart Cursor after saving the file, then sign in with your Krea account when Cursor asks you to connect.
## Using Krea Through MCP
Once connected, ask your agent to list Krea models or inspect a model schema before generating. Model IDs match the API paths used in the rest of the developer docs, such as `image/krea/krea-2/medium` or `video/google/veo-3.1`.
For example:
```text theme={null}
List the available Krea image models, then generate an image with Krea 2 using a 16:9 aspect ratio.
```
If a model is deprecated, Krea returns deprecation metadata through MCP model discovery. See [Deprecations](/developers/deprecations) for migration guidance.
## Tools
The Krea MCP server exposes tools that map to the public API. Your agent discovers them automatically through `tools/list`; the most common ones are:
| Tool | What it does |
| ------------------ | --------------------------------------------------------------------------------------- |
| `list_models` | List available image and video models. |
| `get_model_schema` | Inspect a model's input schema before generating. |
| `generate` | Submit an image or video generation job. |
| `execute_node_app` | Run a node app. |
| `get_job` | Fetch the current status and output of a job by `jobId`. |
| `cancel_job` | Cancel an in-flight job and delete it from your job listings. |
| `get_upload_url` | Request a short-lived presigned URL for uploading a local file to use as a model input. |
Generation and node-app tool outputs include the `job_id` of the submitted job alongside the job payload. Pass that ID to `get_job` to poll status, or to `cancel_job` to stop a job you no longer need.
### Cancelling a job
`cancel_job` calls `DELETE /jobs/{id}` under the hood and returns `{ "job_id": "...", "deleted": true }` on success. Cancellation only takes effect while the job is in a non-terminal status — see [Job Lifecycle](/developers/job-lifecycle) for the rules and billing implications (cancelled jobs are not billed).
Example prompt:
```text theme={null}
Cancel job 7f3c9b1a-… because the prompt was wrong.
```
### Providing media inputs
Any model input that accepts a media URL (for example `start_image`, `image_style_references[].url`, or `reference_images`) accepts one of three forms:
* An external URL — a publicly reachable `https://` link to an image, video, audio, or 3D model file.
* A base64 data URI — for example `data:image/png;base64,iVBORw0KGgo…`.
* An uploaded asset URL — the URL returned after uploading a local file to Krea.
Comma-separated lists of URLs are not supported. Pass each input as its own field or array element.
### Uploading a local file with `get_upload_url`
When the file you want to use is on your local machine and not already hosted somewhere, ask your agent to call `get_upload_url`. The tool returns a presigned URL that is valid for three hours. Your client then `POST`s the file to that URL as `multipart/form-data` with a single `file` field, and the response body contains an asset URL that you can pass into a subsequent `generate` call.
Example flow:
```bash theme={null}
# 1. Ask the agent to call get_upload_url through MCP. It returns something like:
# https://api.krea.ai/public-api/assets/presigned/...
# 2. POST the local file to that presigned URL.
curl -X POST "$UPLOAD_URL" -F "file=@/path/to/image.png"
# 3. The response body contains the asset URL. Use it in the next generate call,
# for example as start_image or image_style_references[].url.
```
If the upload `POST` fails because of restricted network egress, add `api.krea.ai` to your client's domain allowlist. The presigned URL is served from the same host as the rest of the public API.
If your file is already accessible at a public URL or you can encode it as a base64 data URI, skip `get_upload_url` and pass that value directly into the generation input instead.
## MCP Apps UI widget
Generation and node-app tool calls attach an [MCP Apps](https://modelcontextprotocol.io/) UI resource. MCP clients that support MCP Apps render an interactive job-result widget inline with the tool response, including:
* A loading tile sized to the job's aspect ratio while the job is queued or processing.
* Auto-polling of `get_job` so the widget updates as the job progresses, without the agent calling `get_job` itself.
* Action buttons to retry the generation or cancel the job from inside the widget.
* A fullscreen before/after comparison slider for enhance results.
The widget is exposed as the `ui://krea-public-api/job-result-frame` resource and is wired up automatically — no client configuration is required. Clients that don't support MCP Apps simply ignore the resource and fall back to the structured tool output.
Because the widget polls for you, prefer async generation (the default) when you want the UI to show progress. Use sync mode only when the user explicitly asks to wait for the final result in the tool response.
## Troubleshooting
| Issue | Fix |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authentication fails | Reconnect the MCP server and complete the Krea OAuth flow in your browser. If you use an API token, confirm the header is exactly `Authorization: Bearer KREA_API_TOKEN` and that the token has not been revoked. |
| Client cannot connect | Confirm the client is configured for Streamable HTTP and uses `https://api.krea.ai/mcp`. |
| Generation is rejected for billing | If you connected with OAuth, check the compute units on the workspace you selected during consent — reconnect if you need to bind the session to a different workspace. If you connected with an API token, add API balance at [krea.ai/app/api](https://www.krea.ai/app/api). |
| Model call fails | Ask your agent to inspect the model schema before retrying. MCP requests use the same model inputs as the API. |
## Next Steps
Create API tokens and manage API balance for token-authenticated requests.
Try requests in the Krea app before asking an agent to run them.
See how MCP exposes model migration metadata.
Browse endpoint schemas and model parameters.