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

# MCP

> 将 Krea 连接到兼容 MCP 的智能体，让它们能够发现模型、检查 schema，并直接在你的工作区中生成图像或视频。

Krea 为智能体和编程助手提供托管的 Model Context Protocol (MCP) 服务器。当你希望兼容 MCP 的客户端直接调用 Krea，而不是手动编写 API 请求时，可以使用它。

<Info>
  连接无需 API 密钥。将 `https://api.krea.ai/mcp` 添加为 MCP 服务器 URL，然后通过客户端的 OAuth 流程使用你的 Krea 账户登录即可。
</Info>

## 服务器详情

| 设置   | 值                         |
| ---- | ------------------------- |
| 传输方式 | Streamable HTTP           |
| URL  | `https://api.krea.ai/mcp` |
| 身份认证 | OAuth                     |

计费方式取决于你的认证方式：

| 认证方式      | 计费来源             |
| --------- | ---------------- |
| OAuth     | 你在授权时选择的工作区的计算单元 |
| API token | 工作区独立的 API 余额    |

## 身份认证

大多数 MCP 客户端会自动使用 OAuth。当客户端要求你连接时，按照浏览器的登录流程并授权 Krea 即可。

### 在授权时选择工作区

OAuth 授权页面包含一个 **Workspace** 选择器，会列出你所属的所有工作区。默认工作区会被预先选中；如果你希望本次 MCP 会话在其他工作区中运行（例如使用共享的工作室工作区而不是你的个人工作区），可以选择其他工作区。

你所选择的工作区会绑定到该 OAuth 会话，并决定：

* **计费。** 计算单元会从所选的工作区中扣除，而不仅仅是从登录账户扣除。
* **资源范围。** 通过 `upload_asset` 等工具上传的文件会保存到绑定的工作区，并且需要上传的工具（例如 `get_upload_url`）只有在绑定了工作区之后才能使用。

若以后想要切换绑定的工作区，请在 MCP 客户端中断开 Krea 的连接，然后重新连接——你会再次看到该选择器。

<Note>
  在工作区选择器发布之前创建的旧 OAuth 会话没有明确的绑定。这些会话会回退到你账户的默认工作区。请重新连接，以将该会话绑定到指定的工作区。
</Note>

如果你的 MCP 客户端不支持 OAuth，可以改用 API token 进行认证：

| 请求头键            | 请求头值                    |
| --------------- | ----------------------- |
| `Authorization` | `Bearer KREA_API_TOKEN` |

将 `KREA_API_TOKEN` 替换为来自 [krea.ai/app/api/tokens](https://www.krea.ai/app/api/tokens) 的 token。只有工作区所有者和管理员可以创建 API token。

API token 用量按工作区的 API 余额计费，与直接调用 API 相同。API 余额详情请参阅 [API 密钥与计费](/developers/api-keys-and-billing)。

<Warning>
  请像保管 API 密钥一样保管 API token MCP 凭据。不要将包含真实 token 的 MCP 配置文件提交到版本控制。
</Warning>

## Claude Code

在终端中运行以下命令：

```bash theme={null}
claude mcp add --transport http krea-ai https://api.krea.ai/mcp
```

当 Claude Code 提示你连接时，使用你的 Krea 账户登录。添加服务器后，请重启 Claude Code 或重新加载 MCP 服务器。

## Codex

1. 在 Codex 中打开 **Settings** > **MCP servers**。
2. 添加新服务器。
3. 选择 **Streamable HTTP** 作为传输方式。
4. 粘贴服务器 URL：

```text theme={null}
https://api.krea.ai/mcp
```

5. 保存服务器，并在 Codex 提示连接时使用你的 Krea 账户登录。

## Cursor

打开命令面板，搜索 **Open MCP settings**，然后将以下条目添加到 `mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "krea-ai": {
      "url": "https://api.krea.ai/mcp"
    }
  }
}
```

保存文件后重启 Cursor，并在 Cursor 提示连接时使用你的 Krea 账户登录。

## 通过 MCP 使用 Krea

连接后，可以让智能体列出 Krea 模型或在生成前检查模型 schema。模型 ID 与开发者文档其余部分使用的 API 路径相匹配，例如 `image/krea/krea-2/medium` 或 `video/google/veo-3.1`。

例如：

```text theme={null}
List the available Krea image models, then generate an image with Krea 2 using a 16:9 aspect ratio.
```

如果某个模型已弃用，Krea 会通过 MCP 模型发现返回弃用元数据。迁移指引请参阅 [弃用说明](/developers/deprecations)。

## 工具

Krea MCP 服务器暴露了与公共 API 对应的工具。你的智能体会通过 `tools/list` 自动发现它们，最常用的工具包括：

| 工具                 | 功能                                |
| ------------------ | --------------------------------- |
| `list_models`      | 列出可用的图像和视频模型。                     |
| `get_model_schema` | 在生成之前检查模型的输入 schema。              |
| `generate`         | 提交图像或视频生成任务。                      |
| `execute_node_app` | 运行一个节点应用。                         |
| `get_job`          | 通过 `jobId` 获取任务的当前状态和输出。          |
| `cancel_job`       | 取消正在执行的任务，并将其从任务列表中删除。            |
| `get_upload_url`   | 申请一个短期有效的预签名 URL，用于上传本地文件以作为模型输入。 |

生成工具和节点应用工具的输出会在任务负载之外附带所提交任务的 `job_id`。可以将该 ID 传给 `get_job` 以轮询状态，或传给 `cancel_job` 以停止你不再需要的任务。

### 取消任务

`cancel_job` 在底层会调用 `DELETE /jobs/{id}`，成功时返回 `{ "job_id": "...", "deleted": true }`。只有当任务处于非终止状态时，取消操作才会生效——规则及计费影响（被取消的任务不会计费）请参阅 [任务生命周期](/developers/job-lifecycle)。

提示词示例：

```text theme={null}
Cancel job 7f3c9b1a-… because the prompt was wrong.
```

### 提供媒体输入

任何接受媒体 URL 的模型输入（例如 `start_image`、`image_style_references[].url` 或 `reference_images`）都支持以下三种形式之一：

* 外部 URL —— 一个可公开访问的、指向图像、视频、音频或 3D 模型文件的 `https://` 链接。
* base64 data URI —— 例如 `data:image/png;base64,iVBORw0KGgo…`。
* 已上传的资源 URL —— 将本地文件上传到 Krea 后返回的 URL。

不支持以逗号分隔的 URL 列表。请将每个输入作为独立的字段或数组元素传入。

### 使用 `get_upload_url` 上传本地文件

当你要使用的文件位于本地机器上、且尚未托管在任何地方时，可以让智能体调用 `get_upload_url`。该工具会返回一个有效期为三小时的预签名 URL。随后，你的客户端将文件以 `multipart/form-data` 形式 `POST` 到该 URL，请求中只包含一个 `file` 字段，响应体中会返回一个资源 URL，可在后续的 `generate` 调用中使用。

示例流程：

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

<Info>
  如果由于网络出站受限导致上传的 `POST` 失败，请将 `api.krea.ai` 添加到客户端的域名白名单中。预签名 URL 与公共 API 的其他部分托管在同一主机上。
</Info>

如果你的文件已经可以通过公开 URL 访问，或者你能够将其编码为 base64 data URI，那么可以跳过 `get_upload_url`，直接将该值传入生成输入。

## MCP Apps UI 小组件

生成和节点应用工具调用会附带一个 [MCP Apps](https://modelcontextprotocol.io/) UI 资源。支持 MCP Apps 的 MCP 客户端会随着工具响应一起内联渲染一个交互式的任务结果小组件，包括：

* 在任务处于排队或处理中时，按任务的宽高比显示一个相应大小的加载占位卡片。
* 自动轮询 `get_job`，无需智能体本身调用 `get_job`，小组件会随任务进度自动更新。
* 在小组件内部提供操作按钮，可重试生成或取消任务。
* 针对增强结果提供全屏的前后对比滑块。

该小组件作为 `ui://krea-public-api/job-result-frame` 资源暴露，并已自动接入——客户端无需任何额外配置。不支持 MCP Apps 的客户端会直接忽略该资源，回退到结构化的工具输出。

由于小组件会替你轮询，希望在 UI 中展示进度时建议使用异步生成（默认）。仅当用户明确要求在工具响应中等待最终结果时，才使用同步模式。

## 故障排查

| 问题         | 解决方法                                                                                                                                     |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 身份认证失败     | 重新连接 MCP 服务器，并在浏览器中完成 Krea OAuth 流程。如果你使用 API token，确认请求头完全是 `Authorization: Bearer KREA_API_TOKEN`，且该 token 未被吊销。                       |
| 客户端无法连接    | 确认客户端已配置为 Streamable HTTP 并使用 `https://api.krea.ai/mcp`。                                                                                 |
| 生成因计费问题被拒绝 | 如果你通过 OAuth 连接，请检查你在授权时所选工作区的计算单元——如果需要将会话绑定到其他工作区，请重新连接。如果你使用 API token 连接，请在 [krea.ai/app/api](https://www.krea.ai/app/api) 充值 API 余额。 |
| 模型调用失败     | 在重试前让智能体检查模型 schema。MCP 请求使用与 API 相同的模型输入。                                                                                               |

## 后续步骤

<CardGroup cols={2}>
  <Card title="API 密钥与计费" icon="key" href="/developers/api-keys-and-billing">
    创建 API token 并管理用于 token 认证请求的 API 余额。
  </Card>

  <Card title="交互式 Playground" icon="rocket" href="/developers/interactiveexample">
    在让智能体执行请求之前，先在 Krea 应用中试运行请求。
  </Card>

  <Card title="弃用说明" icon="triangle-exclamation" href="/developers/deprecations">
    了解 MCP 如何暴露模型迁移元数据。
  </Card>

  <Card title="模型 API" icon="book-open" href="/api-reference/introduction">
    浏览端点 schema 和模型参数。
  </Card>
</CardGroup>