> ## 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 > Conecte o Krea a agentes compatíveis com MCP para que eles possam descobrir modelos, inspecionar schemas e gerar imagens ou vídeos a partir do seu workspace. 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](https://www.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](/developers/api-keys-and-billing) 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: ```bash theme={null} 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 1. Abra **Settings** > **MCP servers** no Codex. 2. Adicione um novo servidor. 3. Selecione **Streamable HTTP** como transporte. 4. Cole a URL do servidor: ```text theme={null} https://api.krea.ai/mcp ``` 5. 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`: ```json theme={null} { "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: ```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 obsoleto, o Krea retorna metadados de descontinuação através da descoberta de modelos via MCP. Veja [Descontinuações](/developers/deprecations) 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](/developers/job-lifecycle) para as regras e implicações de cobrança (jobs cancelados não são cobrados). Exemplo de prompt: ```text theme={null} 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: ```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. ``` 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. ## 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/). 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](https://www.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 Crie tokens de API e gerencie o saldo de API para requisições autenticadas por token. Teste requisições no app do Krea antes de pedir para um agente executá-las. Veja como o MCP expõe metadados de migração de modelos. Explore schemas de endpoints e parâmetros de modelos.