# Shiftz MCP

> Servidor MCP (Model Context Protocol) de WhatsApp da Shiftz. Plugue qualquer cliente MCP e o agente opera o WhatsApp em linguagem natural, com a mesma apikey da API REST.

## Conexão

- URL: https://api.shiftz.com.br/mcp
- Autenticação: header `Authorization: Bearer <apikey>` (a mesma chave shz_... da API REST)
- Transport: Streamable HTTP (stateless)
- Escopo: chave org-wide enxerga todas as instâncias; chave instance-scoped enxerga só uma.

Gere uma apikey no formato shz_<prefixo>.<segredo> pelo dashboard ou pela tool shiftz_create_apikey. Trate como senha: quem tem ela envia mensagem pelo seu WhatsApp.

## Clientes

### Claude Code [HTTP nativo]

O CLI do Claude conecta direto no endpoint, sem ponte. O escopo user deixa o Shiftz disponível em qualquer projeto seu.

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

Nota: Versionável: no projeto, um .mcp.json aponta pra mesma URL e lê a chave de uma env (SHIFTZ_API_KEY), sem commitar o segredo. Na sessão, o comando /mcp mostra o status e as tools.
Doc: https://shiftz.com.br/docs#mcp-claude-code

### Claude Desktop [Ponte mcp-remote]

Os conectores nativos só fazem login OAuth, sem campo pra apikey fixa. Use a ponte mcp-remote (precisa de Node.js) no claude_desktop_config.json.

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

Nota: Config em ~/Library/Application Support/Claude/ (macOS) ou %APPDATA%\Claude\ (Windows). Salve e reinicie o app. Se o npx no Windows cortar o espaço do header, mova o valor pra uma env AUTH.
Doc: https://shiftz.com.br/docs#mcp-claude-desktop

### Claude.ai (web) [OAuth (em breve)]

Os conectores customizados do claude.ai usam OAuth, sem campo pra colar apikey. Como o /mcp autentica por Bearer hoje, ainda não dá pra adicionar direto no web: use Claude Code ou Claude Desktop por enquanto.
Doc: https://shiftz.com.br/docs#mcp-claude-ai

### Codex CLI [HTTP nativo (flag)]

O Codex lê os MCP servers de ~/.codex/config.toml. O HTTP remoto é nativo atrás da flag experimental_use_rmcp_client.

```toml
experimental_use_rmcp_client = true

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

Nota: Exporte SHIFTZ_API_KEY antes de abrir o Codex. Sem a flag (ou em versões antigas), use a ponte mcp-remote, igual ao Claude Desktop.
Doc: https://shiftz.com.br/docs#mcp-codex

### Gemini CLI [HTTP nativo]

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

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

Nota: Editando o ~/.gemini/settings.json na mão, use o campo httpUrl. O campo url (sem http) seleciona o transport SSE, que é outro.
Doc: https://shiftz.com.br/docs#mcp-gemini

### OpenCode [HTTP nativo]

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

```json
{
  "$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}"
      }
    }
  }
}
```

Nota: A interpolação de env no OpenCode é {env:VAR}, não a sintaxe com cifrão. Se ele abrir OAuth ao tomar um 401, adicione "oauth": false no bloco do server.
Doc: https://shiftz.com.br/docs#mcp-opencode

### OpenClaw [HTTP nativo]

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

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

Nota: No --header do OpenClaw o separador é = (e não :). Rode openclaw mcp status pra confirmar o registro.
Doc: https://shiftz.com.br/docs#mcp-openclaw

### Hermes [HTTP nativo]

O Hermes Agent (Nous Research) lê os servers do bloco mcp_servers da config em YAML. Servidores remotos usam url + headers.

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

Nota: Depois de editar, recarregue com /reload-mcp dentro do Hermes. Campos opcionais por server: timeout e connect_timeout.
Doc: https://shiftz.com.br/docs#mcp-hermes

### Conexão manual [JSON-RPC]

Construindo um cliente próprio ou só testando na unha? O handshake do MCP é um POST JSON-RPC initialize com a apikey no header.

```bash
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"}}}'
```

Nota: A resposta vem como event-stream com o serverInfo (name: shiftz). A partir daí, tools/list e tools/call seguem o mesmo POST.
Doc: https://shiftz.com.br/docs#mcp-handshake

## Exemplos de prompts

- "Lista minhas instâncias do Shiftz" -> shiftz_list_instances
- "Cria a instância marketing-01 e me dá o QR Code" -> shiftz_create_instance
- "Como está a conexão da marketing-01?" -> shiftz_get_connection_state
- "Manda 'Olá!' do marketing-01 pro 5511999998888" -> shiftz_send_text

## Recursos

- Documentação MCP: https://shiftz.com.br/docs#mcp-overview
- Página MCP: https://shiftz.com.br/mcp
- Índice para IA (llms.txt): https://shiftz.com.br/llms.txt
- OpenAPI: https://api.shiftz.com.br/openapi.json