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

> Ligue o Krea a agentes compatíveis com MCP para que possam descobrir modelos, inspecionar esquemas e gerar imagens ou vídeos a partir da sua workspace.

O Krea disponibiliza um servidor Model Context Protocol (MCP) alojado para agentes e assistentes de programação. Utilize-o quando quiser que um cliente compatível com MCP chame o Krea diretamente em vez de escrever pedidos à API manualmente.

<Info>
  Não precisa de uma chave de API para ligar. Adicione `https://api.krea.ai/mcp` como URL do servidor MCP e, em seguida, inicie sessão com a sua conta Krea através do fluxo OAuth do seu cliente.
</Info>

## Detalhes do servidor

| Definição    | Valor                     |
| ------------ | ------------------------- |
| Transporte   | Streamable HTTP           |
| URL          | `https://api.krea.ai/mcp` |
| Autenticação | OAuth                     |

A faturação depende da forma como se autentica:

| Método de autenticação | Fonte de faturação                                                            |
| ---------------------- | ----------------------------------------------------------------------------- |
| OAuth                  | As unidades de computação da workspace que selecionar durante o consentimento |
| Token de API           | O saldo de API separado da sua workspace                                      |

## Autenticação

A maioria dos clientes MCP utiliza OAuth automaticamente. Quando o cliente pedir para ligar, siga o fluxo de início de sessão no navegador e autorize o Krea.

### Escolher uma workspace durante o consentimento

O ecrã de consentimento OAuth inclui um seletor de **Workspace** que lista todas as workspaces a que pertence. A sua workspace predefinida está pré-selecionada; escolha outra se quiser que esta sessão MCP corra noutro local (por exemplo, uma workspace de estúdio partilhada em vez da sua workspace pessoal).

A workspace que selecionar fica associada à sessão OAuth e determina:

* **Faturação.** As unidades de computação são deduzidas da workspace selecionada, não apenas da conta em sessão.
* **Âmbito dos recursos.** Os ficheiros carregados através de ferramentas como `upload_asset` são guardados na workspace associada, e as ferramentas que exigem um carregamento (por exemplo, `get_upload_url`) só funcionam depois de uma workspace estar associada.

Para mudar a workspace associada mais tarde, desligue o Krea no seu cliente MCP e volte a ligar — o seletor voltará a aparecer.

<Note>
  As sessões OAuth antigas, criadas antes do lançamento do seletor de workspace, não têm uma associação explícita. Essas sessões recorrem à workspace predefinida da sua conta. Volte a ligar para associar a sessão a uma workspace específica.
</Note>

Se o seu cliente MCP não suportar OAuth, pode autenticar-se com um token de API em alternativa:

| Chave do cabeçalho | Valor do cabeçalho      |
| ------------------ | ----------------------- |
| `Authorization`    | `Bearer KREA_API_TOKEN` |

Substitua `KREA_API_TOKEN` por um token obtido em [krea.ai/app/api/tokens](https://www.krea.ai/app/api/tokens). Apenas os proprietários e administradores da workspace podem criar tokens de API.

A utilização com token de API é faturada ao saldo de API da sua workspace, tal como as chamadas diretas à API. Consulte [Chaves de API e faturação](/developers/api-keys-and-billing) para mais detalhes sobre o saldo de API.

<Warning>
  Armazene as credenciais MCP por token de API da mesma forma que armazena chaves de API. Não faça commit de ficheiros de configuração MCP que contenham tokens reais.
</Warning>

## Claude Code

Execute este comando no terminal:

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

Inicie sessão com a sua conta Krea quando o Claude Code pedir para ligar. Reinicie o Claude Code ou recarregue os seus servidores MCP depois de adicionar o servidor.

## Codex

1. Abra **Settings** > **MCP servers** no Codex.
2. Adicione um novo servidor.
3. Selecione **Streamable HTTP** como transporte.
4. Cole o URL do servidor:

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

5. Guarde o servidor e inicie sessão com a sua conta Krea quando o Codex pedir para ligar.

## Cursor

Abra a paleta de comandos, procure por **Open MCP settings** e adicione esta entrada a `mcp.json`:

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

Reinicie o Cursor após guardar o ficheiro e, em seguida, inicie sessão com a sua conta Krea quando o Cursor pedir para ligar.

## Utilizar o Krea através de MCP

Depois de ligado, peça ao seu agente para listar modelos do Krea ou inspecionar o esquema de um modelo antes de gerar. Os IDs dos modelos correspondem aos caminhos da API utilizados no resto da documentação para programadores, como `image/krea/krea-2/medium` ou `video/google/veo-3.1`.

Por exemplo:

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

Se um modelo estiver descontinuado, o Krea devolve metadados de descontinuação através da descoberta de modelos MCP. Consulte [Descontinuações](/developers/deprecations) para orientações de migração.

## Ferramentas

O servidor MCP do Krea expõe ferramentas que correspondem à API pública. O seu agente descobre-as automaticamente através de `tools/list`; as mais comuns são:

| Ferramenta         | O que faz                                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `list_models`      | Lista os modelos de imagem e vídeo disponíveis.                                                                       |
| `get_model_schema` | Inspeciona o esquema de entrada de um modelo antes de gerar.                                                          |
| `generate`         | Submete um trabalho de geração de imagem ou vídeo.                                                                    |
| `execute_node_app` | Executa uma node app.                                                                                                 |
| `get_job`          | Obtém o estado atual e a saída de um trabalho a partir do `jobId`.                                                    |
| `cancel_job`       | Cancela um trabalho em execução e remove-o da sua lista de trabalhos.                                                 |
| `get_upload_url`   | Solicita um URL pré-assinado de curta duração para carregar um ficheiro local e utilizá-lo como entrada de um modelo. |

As saídas das ferramentas de geração e de node app incluem o `job_id` do trabalho submetido juntamente com o payload do trabalho. Passe esse ID a `get_job` para consultar o estado, ou a `cancel_job` para parar um trabalho de que já não precisa.

### Cancelar um trabalho

`cancel_job` chama `DELETE /jobs/{id}` nos bastidores e devolve `{ "job_id": "...", "deleted": true }` em caso de sucesso. O cancelamento só produz efeito enquanto o trabalho estiver num estado não terminal — consulte [Ciclo de vida do trabalho](/developers/job-lifecycle) para as regras e implicações de faturação (os trabalhos cancelados não são faturados).

Exemplo de prompt:

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

### Fornecer entradas de média

Qualquer entrada de um modelo que aceite um URL de média (por exemplo `start_image`, `image_style_references[].url` ou `reference_images`) aceita uma de três formas:

* Um URL externo — uma ligação `https://` publicamente acessível a um ficheiro de imagem, vídeo, áudio ou modelo 3D.
* Um URI de dados em base64 — por exemplo `data:image/png;base64,iVBORw0KGgo…`.
* Um URL de recurso carregado — o URL devolvido após carregar um ficheiro local para o Krea.

Listas de URLs separadas por vírgulas não são suportadas. Passe cada entrada como o seu próprio campo ou elemento de array.

### Carregar um ficheiro local com `get_upload_url`

Quando o ficheiro que pretende utilizar está na sua máquina local e ainda não está alojado em lado nenhum, peça ao seu agente para chamar `get_upload_url`. A ferramenta devolve um URL pré-assinado que é válido durante três horas. O seu cliente faz então `POST` do ficheiro para esse URL como `multipart/form-data` com um único campo `file`, e o corpo da resposta contém um URL de recurso que pode passar a uma chamada `generate` subsequente.

Exemplo de fluxo:

```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>
  Se o `POST` de carregamento falhar devido a saída de rede restringida, adicione `api.krea.ai` à lista de domínios permitidos do seu cliente. O URL pré-assinado é servido a partir do mesmo host que o resto da API pública.
</Info>

Se o seu ficheiro já estiver acessível num URL público ou se conseguir codificá-lo como um URI de dados em base64, dispense `get_upload_url` e passe esse valor diretamente para a entrada de geração.

## Widget de UI do MCP Apps

As chamadas às ferramentas de geração e de node app anexam um recurso de UI do [MCP Apps](https://modelcontextprotocol.io/). Os clientes MCP que suportam MCP Apps renderizam um widget interativo de resultado de trabalho em linha com a resposta da ferramenta, incluindo:

* Um bloco de carregamento dimensionado de acordo com a relação de aspeto do trabalho enquanto este está em fila ou em processamento.
* Polling automático de `get_job` para que o widget se atualize à medida que o trabalho avança, sem que o agente tenha de chamar `get_job` por si.
* Botões de ação para repetir a geração ou cancelar o trabalho a partir do interior do widget.
* Um deslizador de comparação antes/depois em ecrã inteiro para resultados de enhance.

O widget é exposto como o recurso `ui://krea-public-api/job-result-frame` e é ligado automaticamente — não é necessária qualquer configuração no cliente. Os clientes que não suportam MCP Apps simplesmente ignoram o recurso e recorrem à saída estruturada da ferramenta.

Como o widget faz o polling por si, prefira a geração assíncrona (o predefinido) quando quiser que a UI mostre o progresso. Utilize o modo síncrono apenas quando o utilizador pedir explicitamente para aguardar o resultado final na resposta da ferramenta.

## Resolução de problemas

| Problema                            | Solução                                                                                                                                                                                                                                                                                        |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A autenticação falha                | Volte a ligar o servidor MCP e complete o fluxo OAuth do Krea no navegador. Se utilizar um token de API, confirme que o cabeçalho é exatamente `Authorization: Bearer KREA_API_TOKEN` e que o token não foi revogado.                                                                          |
| O cliente não consegue ligar-se     | Confirme que o cliente está configurado para Streamable HTTP e utiliza `https://api.krea.ai/mcp`.                                                                                                                                                                                              |
| A geração é rejeitada por faturação | Se ligou via OAuth, verifique as unidades de computação na workspace que selecionou durante o consentimento — volte a ligar se precisar de associar a sessão a uma workspace diferente. Se ligou com um token de API, adicione saldo de API em [krea.ai/app/api](https://www.krea.ai/app/api). |
| A chamada ao modelo falha           | Peça ao seu agente para inspecionar o esquema do modelo antes de tentar novamente. Os pedidos MCP usam as mesmas entradas de modelo que a API.                                                                                                                                                 |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Chaves de API e faturação" icon="key" href="/developers/api-keys-and-billing">
    Crie tokens de API e faça a gestão do saldo de API para pedidos autenticados por token.
  </Card>

  <Card title="Playground interativo" icon="rocket" href="/developers/interactiveexample">
    Experimente pedidos na aplicação Krea antes de pedir a um agente para os executar.
  </Card>

  <Card title="Descontinuações" icon="triangle-exclamation" href="/developers/deprecations">
    Veja como o MCP expõe metadados de migração de modelos.
  </Card>

  <Card title="APIs dos modelos" icon="book-open" href="/api-reference/introduction">
    Explore os esquemas de endpoints e os parâmetros dos modelos.
  </Card>
</CardGroup>