Grok MCP: imagens e vídeo pela API da xAI

Ferramentas MCP remotas no Grok são um recurso do lado do servidor da API da xAI: você indica um servidor MCP dentro do array tools da requisição e o próprio runtime da xAI abre a conexão, lê a lista de ferramentas e as chama enquanto o Grok escreve a resposta. Nada roda no seu computador. É essa a diferença em relação a Cursor ou Claude Code, onde o cliente MCP fica no editor à sua frente e quem conversa pela rede é a sua máquina.

Resposta rápida: acrescente um objeto a tools — {"type": "mcp", "server_url": "https://bananabanana.pro/api/mcp", "server_label": "bananabanana", "authorization": "Bearer bb_live_…"} — e o Grok ganha dez ferramentas de geração: imagens na família Nano Banana, vídeo no Veo 3.1 e no Gemini Omni Flash, fala no Gemini TTS. Imagens a partir de $0.03, vídeo a partir de $0.10, e uma conta nova vem com $0.20 para testar. No grok.com a mesma URL entra em Connectors → New Connector → Custom, embora a parte do login seja menos definida (há uma seção sobre isso adiante).

Tudo o que aqui se afirma sobre o nosso lado do fio foi medido com requisições reais em 1 de setembro de 2026. Tudo o que se afirma sobre o lado da xAI vem da documentação deles como estava naquele mesmo dia, e eu cito em vez de parafrasear, porque essa parte da API deles muda.

Duas superfícies, um servidor

"O Grok suporta MCP?" são na verdade duas perguntas, e as respostas são diferentes.

Duas restrições da mesma página merecem uma segunda leitura. Transportes: "Only Streaming HTTP and SSE transports are supported". E o caminho compatível com OpenAI perde dois parâmetros, require_approval e connector_id, de modo que pedir à xAI uma confirmação antes de uma chamada paga não é opção ali. Ou você constrói isso, ou escolhe as ferramentas com cuidado.

Nosso endpoint é Streamable HTTP sem estado, exatamente o transporte que atende a esse requisito. Sem cabeçalho de sessão para manter vivo, sem stream SSE para vigiar: uma resposta JSON por requisição JSON-RPC.

Ligando o BananaBanana à API da xAI

O mínimo que funciona, com cURL direto na Responses API:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.6",
    "input": [
      { "role": "user",
        "content": "Generate a 16:9 product photo of a ceramic cup on linen, soft morning light. Use nano-banana-pro, then give me the URL." }
    ],
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://bananabanana.pro/api/mcp",
        "server_label": "bananabanana",
        "server_description": "Image, video and speech generation on Google models",
        "authorization": "Bearer bb_live_your_key_here",
        "allowed_tools": ["list_models", "generate_image", "get_result"]
      }
    ]
  }'

O mesmo no SDK Python da xAI, onde dois parâmetros mudam de nome:

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp
 
client = Client(api_key=os.environ["XAI_API_KEY"])
 
chat = client.chat.create(
    model="grok-4.6",
    tools=[
        mcp(
            server_url="https://bananabanana.pro/api/mcp",
            server_label="bananabanana",
            authorization=os.environ["BB_KEY"],          # extra_headers=… also works
            allowed_tool_names=["list_models", "generate_image", "get_result"],
        )
    ],
)
chat.append(user("Make me a 16:9 hero image of a ceramic cup on linen."))

A chave bb_live_… sai do seu perfil, seção API Keys. Ela aparece uma única vez.

Dois detalhes custam uma tarde cada.

O prefixo Bearer. A xAI descreve authorization como "a token that will be set in the Authorization header on requests to the MCP server", o que deixa em aberto se eles embrulham o valor em Bearer para você. Nosso servidor não adivinha. Mande o token pelado e a reclamação vem específica:

{"error":{"code":-32001,"message":"Unsupported Authorization scheme. Use 'Authorization: Bearer <token>'."}}

Então escreva o esquema você mesmo: "authorization": "Bearer bb_live_…". Se um dia isso duplicar do lado da xAI, use a forma sem ambiguidade e defina o cabeçalho direto com headers: {"Authorization": "Bearer bb_live_…"}.

allowed_tools só é opcional no papel. A documentação da xAI é direta: sem ele, todas as definições de ferramentas do servidor entram no contexto do modelo, "if an MCP server exposes 10 different tools and you don't specify allowed_tools, all 10 tool definitions will be available". Nós expomos exatamente dez. Metade gasta dinheiro. Para um bot de imagens eu liberaria list_models, generate_image e get_result e mais nada, ampliando quando o vídeo for realmente necessário.

O que o Grok vê quando bate à porta

Este é o nosso aperto de mão, executado para este artigo. A descoberta de ferramentas dispensa credenciais:

curl -s -X POST https://bananabanana.pro/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

list_models, get_account, top_up, generate_image, edit_image,
generate_video, edit_video, generate_speech, get_result, list_generations

Tudo que de fato faz alguma coisa responde 401 até você apresentar um token, e a resposta carrega o ponteiro de que um cliente bem-comportado precisa:

HTTP/2 401
www-authenticate: Bearer realm="bananabanana",
  error_description="Authentication required. Connect this server with OAuth,
  or create an API key at https://bananabanana.pro/profile",
  resource_metadata="https://bananabanana.pro/.well-known/oauth-protected-resource/api/mcp",
  scope="mcp"

A URL de resource_metadata devolve o documento protected resource metadata da especificação de autorização do MCP, que é como clientes com OAuth encontram sozinhos o nosso servidor de autorização. Pelo caminho da API da xAI você nunca verá esse 401, porque a sua chave viaja em toda chamada. Para a história do conector logo abaixo, isso pesa.

Mais uma nota de compatibilidade, porque ela morde quem escreve o próprio cliente: não exigimos o cabeçalho Accept: application/json, text/event-stream e respondemos JSON puro. Quem falha misteriosamente atrás de um gateway são justamente os servidores que insistem no Accept com sabor de SSE.

Orçamento, job, polling: o fluxo que surpreende agentes

Gerar imagem é uma chamada e uma espera. Vídeo não é, e é aí que trava um loop de agente escrito na lógica de "chamo a ferramenta, leio a resposta".

Pedidos de vídeo e de várias imagens voltam com um orçamento em vez de um job. O modelo precisa chamar a ferramenta uma segunda vez com confirm_cost no valor exato, até o centavo, antes de qualquer cobrança. É uma lombada proposital: um agente não deveria conseguir gastar $4.40 num clipe 4K do Veo porque alguém escreveu "deixa mais cinematográfico".

Depois, a geração é assíncrona. generate_image e generate_video devolvem um job_id na hora; get_result faz long-polling de até 30 segundos por chamada e você repete até o status assentar. Imagens costumam chegar em 10 a 60 segundos. Vídeo leva de 1 a 10 minutos, conforme modelo e duração.

Consequência prática para a Responses API: um turno do usuário pode exigir quatro ou cinco chamadas de ferramenta do lado do servidor, e se a sua integração limitar os passos a dois, o Grok anuncia um job_id e para, feito garçom que anotou o pedido e foi para casa. Dê espaço a ele. Passe também idempotency_key nas gerações, para que uma nova tentativa não vire uma segunda cobrança.

Falhas se estornam sozinhas. Se o filtro de conteúdo do Google recusar um prompt ou a chamada morrer no provedor, o saldo volta automaticamente e get_result explica qual etapa recusou. Você nunca paga por um vídeo que não recebeu.

O grok.com também faz isso?

Em parte, e a resposta honesta tem um buraco.

A xAI documenta o caminho com clareza: vá a grok.com/connectors, clique em New Connector, escolha Custom e então "Enter the MCP server URL and complete any required authentication". O servidor precisa estar acessível pela internet, o que o nosso obviamente está. Os conectores nativos, diz a mesma página, autenticam por OAuth.

O que a página não diz é quais métodos de autenticação um conector personalizado aceita. Essa única frase, "complete any required authentication", é toda a especificação, e a página foi atualizada pela última vez em 17 de julho de 2026.

Do nosso lado, a situação é esta. Mantemos um servidor de autorização OAuth 2.1 completo: registro dinâmico de clientes, PKCE com S256, protected resource metadata, resource indicators, toda a especificação de autorização do MCP. Qualquer cliente que a siga se conecta sem uma linha de trabalho da nossa parte, exatamente como fazem os conectores do Claude e do ChatGPT. Se o conector personalizado do Grok percorrer o mesmo fluxo, vai simplesmente funcionar e você verá uma página de login normal com a sua conta.

Se ele apenas guardar uma URL e não enviar credenciais, as dez ferramentas vão aparecer na lista do conector e cada chamada voltará com 401. A descoberta de ferramentas é anônima no nosso servidor, então um conector pode parecer saudável sem conseguir gerar nada.

Eu adoraria ser mais categórico aqui. Se você testou, o resultado vale um e-mail para [email protected], e a tabela de compatibilidade da nossa página de MCP é atualizada no mesmo dia.

Quanto custa

Os preços são por geração, debitados de um saldo pré-pago, sem assinatura.

Essa xícara é o prompt do exemplo de cURL lá de cima, rodado de verdade durante a escrita: Nano Banana Pro em 2K, $0.11 cobrados, pronto 32 segundos depois da chamada.

Uma conta nova começa com $0.20, o que dá seis imagens Lite ou um clipe curto no Veo Lite. Dá para conferir a fiação e não dá para julgar os modelos bons; prefiro dizer isso com todas as letras a fingir o contrário.

As recargas têm bônus por volume: 5% a partir de $50, 10% a partir de $100. Um código promocional ativo acrescenta mais 10% do depósito, calculado sobre a mesma base, então $100 com código creditam $120. Os números atuais ficam sempre na seção de preços.

O Grok já gera imagens. Por que desviar?

Pergunta justa, e a própria lista de modelos da xAI responde metade dela: eles têm grok-imagine-image-2.0 e grok-imagine-video-1.5. Para uma imagem rápida dentro do chat, use esses. Ninguém precisa de um servidor MCP para isso.

Os motivos para mandar a geração para fora são mais estreitos e giram em torno de quais modelos e de como a conta é lida:

• Modelos específicos do Google. Nano Banana Pro para texto na imagem e produto, Veo 3.1 para vídeo com áudio nativo, Omni Flash quando você quer som e uma edição conversacional do mesmo clipe.
• Preço antes da cobrança. list_models devolve preços por unidade em tempo real, e o vídeo orça antes de gastar. Dá para impor um teto a um agente e ele realmente respeita.
• Um saldo para todos os clientes. A mesma chave serve no Grok, no Gemini CLI, no Codex e no estúdio web, e todo resultado cai num histórico só.
• Estorno em caso de falha, que importa mais do que parece quando há um filtro de conteúdo no meio.

Os custos honestos desse caminho: um salto de rede a mais e um loop de polling, vídeo que exige confirmação, Omni Flash limitado a 720p e esquemas de ferramentas que os clientes cacheiam ao conectar, de modo que um parâmetro novo do nosso lado exige reconexão antes que o Grok consiga enviá-lo. Nada disso é fatal. Tudo isso é real.

FAQ

O Grok suporta servidores MCP?

Sim, do lado da API. As Remote MCP Tools da xAI funcionam no SDK nativo, na Responses API compatível com OpenAI e na Speech to Speech API, com server_url e server_label obrigatórios e authorization, headers e allowed_tools opcionais. No grok.com, conectores MCP personalizados ficam em Connectors → New Connector → Custom.

Preciso de OAuth ou basta uma chave de API?

Para a API da xAI, uma chave bb_live_… basta e é mais simples: passe-a em authorization já com o prefixo Bearer. OAuth importa para clientes do tipo conector, que fazem o login do usuário por conta própria. Nosso servidor aceita os dois no mesmo endpoint.

Qual modelo do Grok devo usar?

Os exemplos de MCP da xAI usam grok-4.6, hoje a recomendação padrão deles. Serve qualquer modelo com suporte a ferramentas do lado do servidor; o contrato das ferramentas não muda entre eles.

Dá para gerar vídeo com som por aqui?

Dá, com Veo 3.1 com áudio ou com Gemini Omni Flash, que sempre traz som. Conte com a confirmação em duas etapas e com um polling de um minuto ou mais. O Omni para em 720p, então não é a escolha para um clipe principal em tela cheia.

O que acontece quando uma geração falha?

A cobrança é revertida automaticamente e get_result devolve o motivo do provedor mais um próximo passo sugerido. Recusas do filtro de conteúdo valem uma nova tentativa com outra redação: o mesmo prompt pode passar na segunda vez, porque o filtro julga os pixels produzidos e não apenas o pedido.