MCP

O Krea expõe um servidor Model Context Protocol (MCP) hospedado para agentes e assistentes de programação. Use-o quando quiser que um cliente compatível com MCP chame o Krea diretamente, em vez de escrever requisições de API manualmente.

Você não precisa de uma chave de API para se conectar. Adicione https://api.krea.ai/mcp como a URL do servidor MCP e, em seguida, faça login com sua conta Krea através do fluxo OAuth do seu cliente.

Detalhes do servidor

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

A cobrança depende de como você se autentica:

Método de autenticação	Origem da cobrança
OAuth	Unidades de computação do workspace que você selecionar durante o consentimento
Token de API	Saldo de API separado do seu workspace

Autenticação

A maioria dos clientes MCP usa OAuth automaticamente. Quando o cliente pedir para você se conectar, siga o fluxo de login no navegador e autorize o Krea.

Escolha um workspace durante o consentimento

A tela de consentimento OAuth inclui um seletor de Workspace que lista todos os workspaces aos quais você pertence. Seu workspace padrão vem pré-selecionado; escolha outro se quiser que esta sessão MCP seja executada em outro lugar (por exemplo, um workspace de estúdio compartilhado em vez do seu pessoal). O workspace selecionado fica vinculado à sessão OAuth e determina:

Cobrança. As unidades de computação são debitadas do workspace selecionado, não apenas da conta conectada.
Escopo dos assets. Arquivos enviados por ferramentas como upload_asset são salvos no workspace vinculado, e ferramentas que exigem um upload (por exemplo, get_upload_url) só funcionam depois que um workspace é vinculado.

Para trocar o workspace vinculado mais tarde, desconecte o Krea no seu cliente MCP e reconecte — o seletor aparecerá novamente.

Sessões OAuth legadas criadas antes do lançamento do seletor de workspace não possuem um vínculo explícito. Essas sessões usam o workspace padrão da sua conta como fallback. Reconecte-se para vincular a sessão a um workspace específico.

Se o seu cliente MCP não oferece suporte a OAuth, você pode se autenticar com um token de API:

Chave do header	Valor do header
`Authorization`	`Bearer KREA_API_TOKEN`

Substitua KREA_API_TOKEN por um token de krea.ai/app/api/tokens. Apenas proprietários e administradores do workspace podem criar tokens de API. O uso via token de API é cobrado do saldo de API do seu workspace, da mesma forma que chamadas diretas à API. Veja Chaves de API e cobrança para detalhes sobre o saldo de API.

Armazene credenciais MCP com token de API da mesma forma que você armazena chaves de API. Não faça commit de arquivos de configuração MCP que contenham tokens reais.

Claude Code

Execute este comando no seu terminal:

claude mcp add --transport http krea-ai https://api.krea.ai/mcp

Faça login com sua conta Krea quando o Claude Code pedir para você se conectar. Reinicie o Claude Code ou recarregue seus servidores MCP após adicionar o servidor.

Codex

Abra Settings > MCP servers no Codex.
Adicione um novo servidor.
Selecione Streamable HTTP como transporte.
Cole a URL do servidor:

https://api.krea.ai/mcp

Salve o servidor e faça login com sua conta Krea quando o Codex pedir para você se conectar.

Cursor

Abra a paleta de comandos, busque por Open MCP settings e adicione esta entrada ao mcp.json:

{
  "mcpServers": {
    "krea-ai": {
      "url": "https://api.krea.ai/mcp"
    }
  }
}

Reinicie o Cursor após salvar o arquivo e faça login com sua conta Krea quando o Cursor pedir para você se conectar.

Usando o Krea através do MCP

Uma vez conectado, peça ao seu agente para listar os modelos do Krea ou inspecionar o schema de um modelo antes de gerar. Os IDs dos modelos correspondem aos caminhos da API usados no restante da documentação para desenvolvedores, como image/krea/krea-2/medium ou video/google/veo-3.1. Por exemplo:

List the available Krea image models, then generate an image with Krea 2 using a 16:9 aspect ratio.

Se um modelo estiver obsoleto, o Krea retorna metadados de descontinuação através da descoberta de modelos via MCP. Veja Descontinuações para orientação sobre migração.

Ferramentas

O servidor MCP do Krea expõe ferramentas que correspondem à API pública. Seu agente as descobre automaticamente via 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 schema de entrada de um modelo antes de gerar.
`generate`	Envia um job de geração de imagem ou vídeo.
`execute_node_app`	Executa um node app.
`get_job`	Obtém o status atual e a saída de um job pelo `jobId`.
`cancel_job`	Cancela um job em andamento e o remove da sua lista de jobs.
`get_upload_url`	Solicita uma URL pré-assinada de curta duração para fazer upload de um arquivo local e usá-lo como entrada de um modelo.

As saídas das ferramentas de geração e de node app incluem o job_id do job enviado junto com o payload do job. Passe esse ID para get_job para consultar o status, ou para cancel_job para parar um job que você não precisa mais.

Cancelando um job

cancel_job chama DELETE /jobs/{id} por baixo dos panos e retorna { "job_id": "...", "deleted": true } em caso de sucesso. O cancelamento só tem efeito enquanto o job está em um status não terminal — veja Ciclo de vida do job para as regras e implicações de cobrança (jobs cancelados não são cobrados). Exemplo de prompt:

Cancel job 7f3c9b1a-… because the prompt was wrong.

Fornecendo entradas de mídia

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

Uma URL externa — um link https:// publicamente acessível para um arquivo de imagem, vídeo, áudio ou modelo 3D.
Um data URI em base64 — por exemplo data:image/png;base64,iVBORw0KGgo….
Uma URL de asset enviado — a URL retornada após fazer upload de um arquivo local para o Krea.

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

Fazendo upload de um arquivo local com `get_upload_url`

Quando o arquivo que você quer usar está na sua máquina local e ainda não está hospedado em algum lugar, peça ao seu agente para chamar get_upload_url. A ferramenta retorna uma URL pré-assinada que é válida por três horas. Seu cliente então faz um POST do arquivo para essa URL como multipart/form-data com um único campo file, e o corpo da resposta contém uma URL de asset que você pode passar para uma chamada subsequente de generate. Fluxo de exemplo:

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

Se o POST de upload falhar devido a restrições de saída de rede, adicione api.krea.ai à lista de domínios permitidos do seu cliente. A URL pré-assinada é servida do mesmo host que o restante da API pública.

Se o seu arquivo já está acessível em uma URL pública ou você pode codificá-lo como um data URI em base64, pule get_upload_url e passe esse valor diretamente para a entrada da geração. As chamadas às ferramentas de geração e de node app anexam um recurso de UI do MCP Apps. Clientes MCP que oferecem suporte ao MCP Apps renderizam um widget interativo de resultado do job inline com a resposta da ferramenta, incluindo:

Um bloco de carregamento dimensionado à proporção do job enquanto ele está na fila ou processando.
Polling automático de get_job para que o widget atualize conforme o job avança, sem que o agente precise chamar get_job por conta própria.
Botões de ação para tentar novamente a geração ou cancelar o job de dentro do widget.
Um controle deslizante em tela cheia de comparação antes/depois para resultados de enhance.

O widget é exposto como o recurso ui://krea-public-api/job-result-frame e é conectado automaticamente — nenhuma configuração no cliente é necessária. Clientes que não oferecem suporte ao MCP Apps simplesmente ignoram o recurso e usam a saída estruturada da ferramenta. Como o widget faz o polling para você, prefira a geração assíncrona (o padrão) quando quiser que a UI mostre o progresso. Use o modo síncrono apenas quando o usuário pedir explicitamente para aguardar o resultado final na resposta da ferramenta.

Solução de problemas

Problema	Solução
Falha na autenticação	Reconecte o servidor MCP e conclua o fluxo OAuth do Krea no seu navegador. Se você usa um token de API, confirme se o header é exatamente `Authorization: Bearer KREA_API_TOKEN` e se o token não foi revogado.
O cliente não consegue conectar	Confirme se o cliente está configurado para Streamable HTTP e usa `https://api.krea.ai/mcp`.
Geração rejeitada por cobrança	Se você conectou via OAuth, verifique as unidades de computação do workspace que selecionou durante o consentimento — reconecte se precisar vincular a sessão a um workspace diferente. Se conectou via token de API, adicione saldo de API em krea.ai/app/api.
Falha na chamada ao modelo	Peça ao seu agente para inspecionar o schema do modelo antes de tentar novamente. Requisições MCP usam as mesmas entradas dos modelos que a API.

Próximos passos

Chaves de API e cobrança

Crie tokens de API e gerencie o saldo de API para requisições autenticadas por token.

Playground interativo

Teste requisições no app do Krea antes de pedir para um agente executá-las.

Descontinuações

Veja como o MCP expõe metadados de migração de modelos.

APIs de modelos

Explore schemas de endpoints e parâmetros de modelos.

Primeiros passos

Krea 2

Conceitos principais

Exemplos de código

Detalhes do servidor

Autenticação

Escolha um workspace durante o consentimento

Claude Code

Codex

Cursor

Usando o Krea através do MCP

Ferramentas

Cancelando um job

Fornecendo entradas de mídia

Fazendo upload de um arquivo local com `get_upload_url`

Widget de UI do MCP Apps

Solução de problemas

Próximos passos

Chaves de API e cobrança

Playground interativo

Descontinuações

APIs de modelos

​Detalhes do servidor

​Autenticação

​Escolha um workspace durante o consentimento

​Claude Code

​Codex

​Cursor

​Usando o Krea através do MCP

​Ferramentas

​Cancelando um job

​Fornecendo entradas de mídia

​Fazendo upload de um arquivo local com get_upload_url

​Widget de UI do MCP Apps

​Solução de problemas

​Próximos passos

Chaves de API e cobrança

Playground interativo

Descontinuações

APIs de modelos

Detalhes do servidor

Autenticação

Escolha um workspace durante o consentimento

Claude Code

Codex

Cursor

Usando o Krea através do MCP

Ferramentas

Cancelando um job

Fornecendo entradas de mídia

Fazendo upload de um arquivo local com `get_upload_url`

Widget de UI do MCP Apps

Solução de problemas

Próximos passos