> ## 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
> MCP 호환 에이전트가 워크스페이스에서 모델을 검색하고 스키마를 확인하며 이미지나 비디오를 생성할 수 있도록 Krea를 연결하세요.
Krea는 에이전트와 코딩 어시스턴트를 위해 호스팅형 Model Context Protocol (MCP) 서버를 제공합니다. API 요청을 직접 작성하는 대신 MCP 호환 클라이언트에서 Krea를 바로 호출하고 싶을 때 사용하세요.
연결에 API 키가 필요하지 않습니다. MCP 서버 URL로 `https://api.krea.ai/mcp`를 추가한 다음, 클라이언트의 OAuth 흐름을 통해 Krea 계정으로 로그인하세요.
## 서버 세부 정보
| 설정 | 값 |
| ----- | ------------------------- |
| 전송 방식 | Streamable HTTP |
| URL | `https://api.krea.ai/mcp` |
| 인증 | OAuth |
청구는 인증 방식에 따라 달라집니다:
| 인증 방식 | 청구 출처 |
| ------ | -------------------------- |
| OAuth | 동의 과정에서 선택한 워크스페이스의 컴퓨트 유닛 |
| API 토큰 | 워크스페이스의 별도 API 잔액 |
## 인증
대부분의 MCP 클라이언트는 OAuth를 자동으로 사용합니다. 클라이언트가 연결을 요청하면 브라우저 로그인 흐름을 따라 Krea를 승인하세요.
### 동의 중에 워크스페이스 선택
OAuth 동의 화면에는 사용자가 속한 모든 워크스페이스를 나열하는 **워크스페이스** 선택 도구가 포함되어 있습니다. 기본 워크스페이스가 미리 선택되어 있으며, 이 MCP 세션을 다른 곳에서 실행하려는 경우(예: 개인 워크스페이스 대신 공유 스튜디오 워크스페이스) 다른 항목을 선택하세요.
선택한 워크스페이스는 OAuth 세션에 바인딩되며 다음을 결정합니다:
* **청구.** 컴퓨트 유닛은 로그인한 계정이 아니라 선택한 워크스페이스에서 차감됩니다.
* **에셋 범위.** `upload_asset` 같은 도구를 통해 업로드된 파일은 바인딩된 워크스페이스에 저장되며, 업로드가 필요한 도구(예: `get_upload_url`)는 워크스페이스가 바인딩된 후에만 동작합니다.
나중에 바인딩된 워크스페이스를 변경하려면 MCP 클라이언트에서 Krea 연결을 해제한 후 다시 연결하세요 — 선택 도구가 다시 표시됩니다.
워크스페이스 선택 도구가 도입되기 전에 생성된 레거시 OAuth 세션에는 명시적 바인딩이 없습니다. 그러한 세션은 계정의 기본 워크스페이스로 폴백됩니다. 세션을 특정 워크스페이스에 바인딩하려면 다시 연결하세요.
MCP 클라이언트가 OAuth를 지원하지 않는 경우, API 토큰으로 대신 인증할 수 있습니다:
| 헤더 키 | 헤더 값 |
| --------------- | ----------------------- |
| `Authorization` | `Bearer KREA_API_TOKEN` |
`KREA_API_TOKEN`을 [krea.ai/app/api/tokens](https://www.krea.ai/app/api/tokens)에서 발급받은 토큰으로 교체하세요. 워크스페이스 소유자와 관리자만 API 토큰을 만들 수 있습니다.
API 토큰 사용량은 직접 API 호출과 동일하게 워크스페이스의 API 잔액으로 청구됩니다. API 잔액에 대한 자세한 내용은 [API 키 및 청구](/developers/api-keys-and-billing)를 참조하세요.
API 토큰 MCP 자격 증명은 API 키와 동일한 방식으로 보관하세요. 실제 토큰이 포함된 MCP 구성 파일을 커밋하지 마세요.
## 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 모델을 나열하거나 생성하기 전에 모델 스키마를 확인하도록 요청하세요. 모델 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` | 생성 전에 모델의 입력 스키마를 확인합니다. |
| `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 데이터 URI — 예: `data:image/png;base64,iVBORw0KGgo…`.
* 업로드된 자산 URL — 로컬 파일을 Krea에 업로드한 후 반환되는 URL.
쉼표로 구분된 URL 목록은 지원되지 않습니다. 각 입력은 별도의 필드 또는 배열 요소로 전달하세요.
### `get_upload_url`로 로컬 파일 업로드하기
사용하려는 파일이 로컬 머신에 있고 아직 어디에도 호스팅되어 있지 않다면, 에이전트에게 `get_upload_url`을 호출하도록 요청하세요. 이 도구는 3시간 동안 유효한 프리사인드 URL을 반환합니다. 그런 다음 클라이언트는 단일 `file` 필드를 사용해 `multipart/form-data`로 해당 URL에 파일을 `POST`하며, 응답 본문에는 이후 `generate` 호출에 전달할 수 있는 자산 URL이 포함됩니다.
예시 흐름:
```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.
```
제한된 네트워크 송신으로 인해 업로드 `POST`가 실패하면 클라이언트의 도메인 허용 목록에 `api.krea.ai`를 추가하세요. 프리사인드 URL은 나머지 공개 API와 동일한 호스트에서 제공됩니다.
파일이 이미 공개 URL로 접근 가능하거나 base64 데이터 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 토큰을 사용하는 경우, 헤더가 정확히 `Authorization: Bearer KREA_API_TOKEN`인지, 토큰이 취소되지 않았는지 확인하세요. |
| 클라이언트 연결 불가 | 클라이언트가 Streamable HTTP로 구성되어 있고 `https://api.krea.ai/mcp`를 사용하는지 확인하세요. |
| 청구 문제로 생성 거부됨 | OAuth로 연결한 경우, 동의 과정에서 선택한 워크스페이스의 컴퓨트 유닛을 확인하세요 — 세션을 다른 워크스페이스에 바인딩해야 한다면 다시 연결하세요. API 토큰으로 연결한 경우, [krea.ai/app/api](https://www.krea.ai/app/api)에서 API 잔액을 충전하세요. |
| 모델 호출 실패 | 다시 시도하기 전에 에이전트에게 모델 스키마를 확인하도록 요청하세요. MCP 요청은 API와 동일한 모델 입력값을 사용합니다. |
## 다음 단계
API 토큰을 만들고 토큰 인증 요청에 사용할 API 잔액을 관리하세요.
에이전트에게 요청을 실행하도록 요청하기 전에 Krea 앱에서 직접 요청을 시도해 보세요.
MCP가 모델 마이그레이션 메타데이터를 어떻게 노출하는지 확인하세요.
엔드포인트 스키마와 모델 파라미터를 살펴보세요.