Referência da API v2

Autenticação

Todas as requisições usam API Key via header apikey. As chaves são escopadas por organização — você só acessa instâncias da sua própria conta.

apikey: shz_<prefix>.<secret>

Teste se sua chave é válida listando suas instâncias.

curl -X GET https://api.shiftz.com.br/v2/instance/fetchInstances \
  -H "apikey: SUA_CHAVE_AQUI"

Erros & Status Codes

Erros seguem o formato JSON padrão. Quando aplicável, vem o campo details com informações adicionais (ex: violações Zod).

{
  "error": "invalid_body",
  "details": [
    {
      "code": "invalid_type",
      "path": ["text"],
      "message": "Required"
    }
  ]
}

Criar Instância

Cria uma nova instância. O instanceName que você escolher é o identificador usado em todas as outras rotas. A criação retorna uma API Key específica da instância no campo hash.

Quando qrcode: true, a resposta já inclui o campo qrcode com o conteúdo bruto e o base64 — sem necessidade de chamar /connect em seguida.

curl -X POST https://api.shiftz.com.br/v2/instance/create \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "marketing-01",
    "integration": "WHATSAPP-BAILEYS",
    "qrcode": true,
    "rejectCall": true,
    "msgCall": "Não atendemos chamadas neste número.",
    "groupsIgnore": true,
    "alwaysOnline": false,
    "readMessages": false,
    "readStatus": false,
    "syncFullHistory": false,
    "proxyHost": "proxy.exemplo.com",
    "proxyPort": 8080,
    "proxyProtocol": "http",
    "proxyUsername": "user",
    "proxyPassword": "pass",
    "webhook": {
      "enabled": true,
      "url": "https://seu-servidor.com/webhook",
      "base64": false,
      "headers": {
        "Authorization": "Bearer TOKEN_INTERNO"
      },
      "events": [
        "messages.upsert",
        "connection.update",
        "qrcode.updated"
      ]
    }
  }'

Listar Instâncias

Retorna todas as instâncias da sua organização com o estado de conexão atual.

curl -X GET https://api.shiftz.com.br/v2/instance/fetchInstances \
  -H "apikey: SUA_CHAVE"

Conectar Instância

Inicia a conexão com o WhatsApp e retorna o QR Code (raw + base64) ou o pairing code quando o telefone foi informado na criação.

QR Codes têm validade curta (~20s). Se a sessão for pra FAILED, descarte e chame /connect de novo pra obter um QR fresco.

curl -X GET https://api.shiftz.com.br/v2/instance/connect/marketing-01 \
  -H "apikey: SUA_CHAVE"

Estado da Conexão

Retorna o estado atual da conexão da instância. Valores: open (conectado), close (desconectado), connecting (em conexão), qr-code (aguardando leitura).

curl -X GET https://api.shiftz.com.br/v2/instance/connectionState/marketing-01 \
  -H "apikey: SUA_CHAVE"

Atualizar Instância

Atualiza a configuração da instância (webhook + flags de comportamento). Campos não enviados permanecem inalterados.

curl -X PUT https://api.shiftz.com.br/v2/instance/update/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "enabled": true,
      "url": "https://meusite.com/webhook",
      "events": ["messages.upsert", "connection.update"]
    }
  }'

Desconectar (Logout)

Encerra a sessão do WhatsApp mas mantém a instância criada. Para reconectar depois, basta chamar /instance/connect/:name novamente. Para remover permanentemente, use Deletar Instância.

curl -X DELETE https://api.shiftz.com.br/v2/instance/logout/marketing-01 \
  -H "apikey: SUA_CHAVE"

Deletar Instância

Remove permanentemente a instância: encerra a sessão WhatsApp, libera a vaga no plano e apaga a configuração.

curl -X DELETE https://api.shiftz.com.br/v2/instance/delete/marketing-01 \
  -H "apikey: SUA_CHAVE"

Listar Histórico

Retorna mensagens enviadas e recebidas pela instância. Suporta paginação por cursor (use nextCursor da resposta como cursor da próxima requisição). Status reflete o último ack recebido (sent, delivered, read, played, revoked).

curl -X GET "https://api.shiftz.com.br/v2/message/list/marketing-01?direction=out&limit=20" \
  -H "apikey: SUA_CHAVE"

Enviar Texto

Envia uma mensagem de texto. Suporta emojis, formatação WhatsApp (*bold*, _italic_, ~strikethrough~, `code`), preview de links e respostas (quoted).

curl -X POST https://api.shiftz.com.br/v2/message/sendText/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "text": "Olá! 👋",
    "delay": 1200
  }'

Enviar Mídia

Envia imagem, vídeo, documento ou áudio a partir de URL pública.

curl -X POST https://api.shiftz.com.br/v2/message/sendMedia/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "mediatype": "image",
    "media": "https://example.com/imagem.png",
    "caption": "Confira nosso novo produto!"
  }'

Enviar Áudio (PTT)

Envia um áudio como mensagem de voz (Push-To-Talk). Aceita URL pública de MP3 ou OGG.

curl -X POST https://api.shiftz.com.br/v2/message/sendWhatsAppAudio/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "audio": "https://example.com/voice.mp3"
  }'

Enviar Figurinha

Envia uma figurinha (sticker) a partir de URL pública. WebP é o formato nativo; outros formatos podem ser convertidos.

curl -X POST https://api.shiftz.com.br/v2/message/sendSticker/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "sticker": "https://example.com/sticker.webp"
  }'

Enviar Localização

Envia um pin de localização geográfica. Coordenadas em graus decimais.

curl -X POST https://api.shiftz.com.br/v2/message/sendLocation/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "name": "MASP",
    "address": "Av. Paulista, 1578"
  }'

Enviar Enquete

Cria uma enquete com opções para o destinatário votar. O voto chega via webhook como pollUpdateMessage.

curl -X POST https://api.shiftz.com.br/v2/message/sendPoll/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "name": "Qual o melhor horário?",
    "values": ["Manhã", "Tarde", "Noite"],
    "selectableCount": 1
  }'

Enviar Contato

Envia um ou mais cartões de contato (vCard). Para múltiplos contatos, envie um único array — o WhatsApp agrupa automaticamente.

curl -X POST https://api.shiftz.com.br/v2/message/sendContact/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "contact": [
      {
        "fullName": "Ivo Silva",
        "phoneNumber": "5511999997777",
        "organization": "Verboo",
        "email": "[email protected]"
      }
    ]
  }'

Enviar Vídeo Redondo (PTV)

Envia um vídeo curto circular (Push-To-Video). Use arquivos curtos (≤60s) em MP4.

curl -X POST https://api.shiftz.com.br/v2/message/sendPtv/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "video": "https://example.com/short.mp4"
  }'

Enviar Lista

Envia uma mensagem interativa com lista de opções selecionáveis. Ideal para menus, catálogos e formulários.

curl -X POST https://api.shiftz.com.br/v2/message/sendList/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "title": "Nossos Planos",
    "description": "Escolha o plano ideal para você:",
    "buttonText": "Ver opções",
    "footerText": "Shiftz",
    "sections": [
      {
        "title": "Planos",
        "rows": [
          { "title": "Starter", "description": "R$ 30/mês", "rowId": "plan_starter" },
          { "title": "Pro", "description": "R$ 90/mês", "rowId": "plan_pro" }
        ]
      }
    ]
  }'

Enviar Status (Broadcast)

Publica um status visível para todos os contatos ou para uma lista específica de JIDs. Suporta texto, imagem, áudio e vídeo.

curl -X POST https://api.shiftz.com.br/v2/message/sendStatus/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "content": "Estamos com desconto hoje! 🎉",
    "backgroundColor": "#FF5733",
    "font": 2,
    "allContacts": true
  }'

Enviar Reação

Reage a uma mensagem específica com um emoji. Para remover uma reação anterior, envie reaction como string vazia.

curl -X POST https://api.shiftz.com.br/v2/message/sendReaction/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "reaction": "👍",
    "key": {
      "remoteJid": "[email protected]",
      "id": "3EB0XXXXXXXX",
      "fromMe": false
    }
  }'

Enviar Presença

Simula presença num chat: digitando, gravando ou online. Use delay para definir a duração antes de pausar automaticamente.

curl -X POST https://api.shiftz.com.br/v2/chat/sendPresence/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999998888",
    "presence": "composing",
    "type": "text",
    "delay": 3000
  }'

Marcar como Lido

Marca um conjunto de mensagens como lidas. Em grupos, informe sender (JID do remetente original).

curl -X POST https://api.shiftz.com.br/v2/chat/markMessageAsRead/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "readMessages": [
      {
        "remoteJid": "[email protected]",
        "id": "3EB0XXXXXXXX"
      }
    ]
  }'

Verificar Número

Para cada número do array, retorna se está registrado no WhatsApp e o JID correspondente. Útil para validar antes de enviar.

curl -X POST https://api.shiftz.com.br/v2/chat/whatsappNumbers/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["5511999998888", "5511777776666"]
  }'

Deletar Mensagem (para todos)

Revoga uma mensagem (apaga para todos). Em grupos, ao deletar mensagem de outro participante, informe participant.

curl -X DELETE https://api.shiftz.com.br/v2/chat/deleteMessageForEveryone/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3EB0XXXXXXXX",
    "remoteJid": "[email protected]",
    "fromMe": true
  }'

Listar Chats

Retorna a lista completa de chats da instância (individuais + grupos). Cada item traz chatId, name (quando o WhatsApp expõe — pode vir vazio em DMs sem nome salvo), isGroup, lastMessageTimestamp, unreadCount, archived, pinned, muteEndTimestamp. pictureUrl não vem nesse listing — chame Foto de Perfil por chat pra resolver.

curl -X GET https://api.shiftz.com.br/v2/chat/findChats/marketing-01 \
  -H "apikey: SUA_CHAVE"

Listar Contatos

Retorna o address-book completo do número conectado. Cada item traz remoteJid (phone JID), remoteLid (LID alternativo, chave para destravar mapping LID↔phone em contatos com privacy mode), pushName, verifiedName, profilePicUrl, isMyContact, isBlocked. Suporta filtro pontual por where.remoteJid e paginação por cursor. Útil pro sync inicial do CRM logo após o pareamento.

curl -X POST https://api.shiftz.com.br/v2/chat/findContacts/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 500 }'

Foto de Perfil

Retorna a URL pública atual da foto de perfil do contato/grupo. Devolve { "url": null } se não houver ou estiver bloqueada. Também aceita variante POST /v2/chat/fetchProfilePictureUrl/:instance com { "chatId": "..." } no body — útil quando o JID complica encoding em path.

curl -X GET https://api.shiftz.com.br/v2/chat/fetchProfilePictureUrl/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE"

Arquivar Chat

Toggle. Use archive: true para arquivar e false para desarquivar.

curl -X POST https://api.shiftz.com.br/v2/chat/archiveChat/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "archive": true }'

Criar Grupo

Cria um grupo WhatsApp e adiciona os participantes informados.

curl -X POST https://api.shiftz.com.br/v2/group/create/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Time Marketing",
    "participants": ["5511999998888", "5511777776666"],
    "description": "Canal interno do time"
  }'

Informações do Grupo

Retorna metadados do grupo: subject, owner, descrição, lista de participantes (com flags isAdmin, isSuperAdmin).

curl -X GET https://api.shiftz.com.br/v2/group/findGroupInfos/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE"

Adicionar Participantes

Adiciona números ao grupo.

curl -X POST https://api.shiftz.com.br/v2/group/addParticipants/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["5511999998888"] }'

Remover Participante

Remove números do grupo. Aceita um array.

curl -X POST https://api.shiftz.com.br/v2/group/removeParticipant/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["5511999998888"] }'

Promover Admin

Promove participantes a administradores.

curl -X POST https://api.shiftz.com.br/v2/group/promote/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["5511999998888"] }'

Rebaixar Admin

Remove status de admin de participantes.

curl -X POST https://api.shiftz.com.br/v2/group/demote/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["5511999998888"] }'

Sair do Grupo

Remove o número da instância como participante do grupo.

curl -X POST https://api.shiftz.com.br/v2/group/leave/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE"

Link de Convite

Retorna o código de convite atual e a URL https://chat.whatsapp.com/<code>.

curl -X GET https://api.shiftz.com.br/v2/group/inviteCode/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE"

Revogar Convite

Invalida o código atual e gera um novo. Links antigos param de funcionar.

curl -X POST https://api.shiftz.com.br/v2/group/revokeInvite/marketing-01/[email protected] \
  -H "apikey: SUA_CHAVE"

Enviar Link por DM

Pega o invite-code do grupo e envia uma mensagem de texto com o link para cada número em numbers[].

curl -X POST https://api.shiftz.com.br/v2/group/sendInvite/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "groupJid": "[email protected]",
    "numbers": ["5511999998888", "5511777776666"],
    "description": "Entra no nosso grupo!"
  }'

Buscar Perfil

Retorna o perfil atual da instância: wuid, name, status, pictureUrl.

curl -X GET https://api.shiftz.com.br/v2/profile/fetchProfile/marketing-01 \
  -H "apikey: SUA_CHAVE"

Atualizar Nome

Define o nome de exibição do perfil.

curl -X POST https://api.shiftz.com.br/v2/profile/updateProfileName/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Time Marketing" }'

Atualizar Foto

Define a foto de perfil a partir de uma URL pública.

curl -X POST https://api.shiftz.com.br/v2/profile/updateProfilePicture/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "picture": "https://example.com/avatar.jpg" }'

Atualizar Status

Define o recado/status do perfil.

curl -X POST https://api.shiftz.com.br/v2/profile/updateProfileStatus/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Atendimento 9h-18h" }'

Configurar Webhook

Define ou atualiza a configuração de webhook de uma instância. Faz upsert — chamar de novo substitui a configuração anterior.

Cada POST inclui os headers X-Shiftz-Event, X-Shiftz-Attempt e X-Webhook-Signature (HMAC-SHA256 do body). Retry com backoff exponencial de 2s a 1h, total até 24h.

curl -X POST https://api.shiftz.com.br/v2/webhook/set/marketing-01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "enabled": true,
      "url": "https://meusite.com/webhook",
      "events": ["messages.upsert", "connection.update"]
    }
  }'

Consultar Webhook

Retorna a configuração atual de webhook da instância. Se não houver configuração, devolve um objeto neutro com enabled: false.

curl -X GET https://api.shiftz.com.br/v2/webhook/find/marketing-01 \
  -H "apikey: SUA_CHAVE"

Eventos de Webhook

Todos os eventos são entregues via POST na URL configurada, dentro de um envelope padrão. O campo data varia conforme o tipo do evento.

Use os nomes abaixo no array events ao configurar o webhook. events: [] ou events: ["*"] recebe todos. A filtragem aceita ambos os formatos — MESSAGES_UPSERT (Evolution v2 UPPERCASE) e messages.upsert (lowercase canônico). O Shiftz normaliza antes de comparar.

Eventos Evolution v2 (com mapping ou alias direto):

Não disponíveis (Evolution-specific, não emitidos pela API): APPLICATION_STARTUP, MESSAGES_SET, CONTACTS_SET, CHATS_SET/UPSERT/UPDATE/DELETE, GROUPS_UPSERT, NEW_JWT_TOKEN, TYPEBOT_*.

• presence.update: só emitido quando um contato remoto envia presença (ex: o destinatário está digitando). Chamar sendPresence da sua instância não dispara este evento — ele é só pra você ler presenças de outros.
• contacts.upsert: dispara quando um contato/grupo é criado, atualizado ou tem foto/nome alterado pelo lado remoto. Mudanças no seu próprio perfil (updateProfileName/Picture/Status) não disparam este evento — atualizam direto via API REST.
• messages.update (ack): delivered chega rápido (≤1s), mas read só vem quando o destinatário abre a conversa no celular. Em testes locais, abra o WhatsApp no celular receptor pra forçar o read receipt.
• messages.delete: o data.key agora contém id (mensagem revogada) e remoteJid (chat). Em algumas mensagens o remoteJid pode ser inferido do composto false_<chatId>_<msgId>.
• qrcode.updated: emitido em paralelo a connection.update quando há um novo QR. Use este pra renderizar QR em UI sem precisar interpretar connection.update com state: "qr-code".

Eventos adicionais (passthrough) — payload no formato canônico Shiftz:

{
  "event": "messages.upsert",
  "instance": "marketing-01",
  "data": { /* payload do evento */ },
  "date_time": "2026-05-06T01:48:35.762Z",
  "sender": "[email protected]",
  "server_url": "https://api.shiftz.com.br"
}

Visão geral

O MCP (Model Context Protocol) é o "plugue universal" que liga assistentes de IA a ferramentas externas. O Shiftz expõe um servidor MCP que dá ao seu agente acesso a todo o /v2/* em linguagem natural: ele cria instâncias, lê o QR Code, manda mensagem e administra grupos sozinho, sem você escrever uma linha de integração.

Três coisas definem a conexão e valem para todos os clientes desta página:

• URL: https://api.shiftz.com.br/mcp
• Autenticação: header Authorization: Bearer <apikey>, a mesma chave shz_... da API REST.
• Transport: Streamable HTTP (stateless).

A apikey também decide o que o agente enxerga: chave org-wide vê todas as instâncias, chave instance-scoped vê só uma. Além das tools, o servidor expõe resources (shiftz://instances/*) e prompts guiados, descobertos automaticamente pelo cliente.

Clientes suportados

A maioria dos clientes conecta direto no endpoint HTTP usando o header de autenticação. Alguns precisam de uma ponte local ou de OAuth. Ache o seu na tabela e pule para a seção dele:

Em todos os exemplos, troque shz_xxx.yyy pela sua apikey.

Claude Code

O CLI do Claude conecta direto no endpoint HTTP, sem ponte. Use --scope user para deixar o Shiftz disponível em qualquer projeto seu:

claude mcp add --transport http --scope user shiftz \
  https://api.shiftz.com.br/mcp \
  --header "Authorization: Bearer shz_xxx.yyy"

Numa sessão, o comando /mcp abre o painel com o status da conexão e a lista de tools. O arquivo .mcp.json (versionável) aceita variáveis de ambiente como ${SHIFTZ_API_KEY}, ideal para não commitar a chave.

Claude Desktop

O Claude Desktop tem conectores nativos, mas a UI deles só faz login por OAuth, sem campo para uma apikey fixa. Para a autenticação Bearer da Shiftz, use o mcp-remote como ponte (precisa de Node.js instalado). Edite o arquivo de config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shiftz": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.shiftz.com.br/mcp",
        "--header",
        "Authorization:${AUTH}"
      ],
      "env": {
        "AUTH": "Bearer shz_xxx.yyy"
      }
    }
  }
}

O header vai sem espaço (Authorization:${AUTH}) e o valor, com o espaço depois de Bearer, fica na env AUTH. Isso contorna um bug do npx no Windows que corta espaços dentro de args. Salve, reinicie o Claude Desktop e as tools aparecem no ícone de conectores do chat.

Claude.ai (web)

Os conectores customizados do claude.ai (Configurações, Conectores, "Adicionar conector personalizado") usam OAuth: você informa a URL do MCP e o claude.ai conduz o login OAuth do servidor. Não há campo para colar uma apikey fixa.

Como o /mcp da Shiftz autentica hoje pelo header Authorization: Bearer <apikey> (sem OAuth), ele ainda não pode ser adicionado direto no claude.ai web. Para usar o Shiftz no ecossistema Claude agora, vá de Claude Code ou Claude Desktop. Quando a Shiftz publicar o fluxo OAuth no endpoint MCP, esta seção será atualizada.

Codex CLI

O Codex CLI da OpenAI lê os MCP servers de ~/.codex/config.toml. O suporte a servidores HTTP remotos é nativo, mas fica atrás de uma flag experimental (experimental_use_rmcp_client), que vai no topo do arquivo:

experimental_use_rmcp_client = true

[mcp_servers.shiftz]
url = "https://api.shiftz.com.br/mcp"
bearer_token_env_var = "SHIFTZ_API_KEY"

Na primeira aba, exporte a chave (export SHIFTZ_API_KEY="shz_xxx.yyy") e o Codex a envia como Authorization: Bearer .... Em versões antigas, ou sem a flag experimental, use a segunda aba (ponte mcp-remote, igual ao Claude Desktop). O comando codex mcp add hoje só registra servers stdio, então o setup HTTP é feito editando o TOML.

Gemini CLI

O Gemini CLI do Google conecta direto via HTTP. O jeito mais rápido é o comando gemini mcp add:

gemini mcp add --transport http --scope user \
  --header "Authorization: Bearer shz_xxx.yyy" \
  shiftz https://api.shiftz.com.br/mcp

Atenção ao campo no ~/.gemini/settings.json: para Streamable HTTP use httpUrl. O campo url (sem http) seleciona o transport SSE, que é diferente. Dentro do Gemini CLI, /mcp lista os servers conectados.

OpenCode

O OpenCode usa a chave mcp no opencode.json (na raiz do projeto) ou em ~/.config/opencode/opencode.json. Servidores remotos têm "type": "remote":

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shiftz": {
      "type": "remote",
      "url": "https://api.shiftz.com.br/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:SHIFTZ_API_KEY}"
      }
    }
  }
}

A interpolação de env no OpenCode é {env:VAR} (e não ${VAR}); você também pode colar a chave literal em headers. Se o OpenCode tentar abrir um fluxo OAuth ao receber o 401, adicione "oauth": false no bloco do server.

OpenClaw

O OpenClaw guarda os MCP servers em ~/.openclaw/openclaw.json, sob mcp.servers. Dá para adicionar pela CLI ou editando o arquivo:

openclaw mcp add shiftz \
  --url https://api.shiftz.com.br/mcp \
  --transport streamable-http \
  --header "Authorization=Bearer shz_xxx.yyy"

No --header do OpenClaw o separador é = (Authorization=Bearer ...), diferente do : usado por Claude e Gemini. Rode openclaw mcp status para confirmar que o server registrou.

Hermes

O Hermes Agent (Nous Research) lê os MCP servers do bloco mcp_servers da config em YAML (veja o cli-config.yaml.example do projeto). Servidores remotos usam url + headers:

mcp_servers:
  shiftz:
    url: "https://api.shiftz.com.br/mcp"
    headers:
      Authorization: "Bearer shz_xxx.yyy"

Depois de editar o arquivo, recarregue com /reload-mcp dentro do Hermes. Campos opcionais por server incluem timeout e connect_timeout.

Conexão manual

Está construindo um cliente próprio ou só quer testar a conexão na unha? O handshake do MCP é um POST JSON-RPC com a apikey no header:

curl -X POST https://api.shiftz.com.br/mcp \
  -H "Authorization: Bearer shz_xxx.yyy" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1" }
    }
  }'

Exemplos de prompts

Conectado, qualquer cliente entende pedidos em linguagem natural e escolhe a tool sozinho:

• "Lista minhas instâncias do Shiftz" → shiftz_list_instances
• "Cria uma instância chamada marketing-01 e me dá o QR Code" → shiftz_create_instance (com qrcode: true)
• "Como está a conexão da marketing-01?" → shiftz_get_connection_state
• "Manda 'Olá!' do marketing-01 pro 5511999998888" → shiftz_send_text

Não precisa decorar nomes de tool: descreva a intenção e o agente resolve. A apikey limita o alcance: chave org-wide enxerga todas as instâncias, chave instance-scoped só a sua.