MCP: Claude, ChatGPT, Cursor e outros apps

O MB Suite tem um servidor MCP remoto (Streamable HTTP) que expõe as mesmas operações da API, com as mesmas permissões, cotas e auditoria. Esta é a URL que se cola no cliente:

https://mcp.mb-suite.com

Claude

1. 1No Claude, abra Configurações → Conectores → Adicionar conector personalizado.
2. 2Cole a URL do servidor e salve.
3. 3O Claude leva você ao MB Suite para escolher a organização e revisar as permissões; ao voltar, já está conectado.
4. 4Teste com «O que posso fazer no MB Suite?»: a primeira ferramenta é mb_context.

O Claude se conecta com OAuth: não é preciso criar uma API key.

ChatGPT

1. 1No ChatGPT, abra Configurações → Apps e conectores → Configurações avançadas e ative o modo desenvolvedor (nos planos empresariais quem habilita é o administrador).
2. 2Volte a Apps e conectores, escolha Criar e cole a URL do servidor como servidor MCP.
3. 3O ChatGPT leva você ao MB Suite para autorizar: revise a organização e as permissões e confirme.
4. 4Ative o app na conversa e peça algo do CRM.

Cursor

O Cursor se conecta com uma API key como bearer. Em Cursor Settings → Tools & MCP → New MCP Server, com esta configuração e a sua API key:

{
  "mcpServers": {
    "mb-suite": {
      "url": "https://mcp.mb-suite.com",
      "headers": {
        "Authorization": "Bearer mbs_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code

1. 1No VS Code, abra a paleta de comandos e escolha «MCP: Add Server». Você precisa do GitHub Copilot.
2. 2Escolha HTTP, cole a URL do servidor e salve para o seu usuário ou para o projeto (abaixo, a configuração do .vscode/mcp.json).
3. 3Na primeira vez, o VS Code pede permissão para entrar e leva você ao MB Suite para escolher a organização e revisar as permissões.
4. 4No chat do Copilot, no modo Agente, teste com «O que posso fazer no MB Suite?».

{
  "servers": {
    "mb-suite": {
      "type": "http",
      "url": "https://mcp.mb-suite.com"
    }
  }
}

O VS Code se conecta com OAuth: não é preciso criar uma API key.

Claude Code

1. 1No terminal, adicione o servidor (com --scope user ele fica disponível em todos os seus projetos).
2. 2Abra o Claude Code, digite /mcp e escolha mb-suite para se autenticar.
3. 3O Claude Code abre o MB Suite no navegador para escolher a organização e revisar as permissões; ao voltar, já está conectado.

claude mcp add --transport http mb-suite https://mcp.mb-suite.com

O Claude Code se conecta com OAuth: não é preciso criar uma API key.

Outros apps

Qualquer app compatível com MCP se conecta. Se ele aceita servidores remotos com OAuth, cole a URL e ele traz você ao MB Suite para autorizar. Se pede uma API key, use uma como bearer; na maioria dos apps a configuração é esta:

{
  "mcpServers": {
    "mb-suite": {
      "url": "https://mcp.mb-suite.com",
      "headers": {
        "Authorization": "Bearer mbs_live_YOUR_API_KEY"
      }
    }
  }
}

Se o app só aceita servidores locais, conecte-o com a ponte mcp-remote (precisa do Node.js). A API key vai em env e o cabeçalho sem espaços, como a ponte pede:

{
  "mcpServers": {
    "mb-suite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.mb-suite.com",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer mbs_live_YOUR_API_KEY"
      }
    }
  }
}

Um cliente próprio usa o mesmo Authorization: Bearer mbs_live_…, ou faz o fluxo OAuth com resource=https://mcp.mb-suite.com (veja Autenticação). Cada chamada tem até 60 segundos.

As ferramentas

Cada credencial escolhe uma superfície: na API key, «Modo de ferramentas do MCP» em Avançado; no OAuth, em Avançado do consentimento.

• A lista depende só da credencial: os escopos, o papel da pessoa e os módulos da organização. O que ela não pode executar não aparece; se mesmo assim pedir uma operação que existe e lhe faltar o escopo, a exclusão ou o papel, recebe um 403 que diz o que falta (scope_insufficient, delete_not_allowed, role_required), não um 404. mb_search_operations avisa em not_runnable as escritas que coincidem e ela não pode executar, e em screen_only o que só se faz na tela do MB Suite (como as API keys).
• O em massa, o irreversível, o que envia ou muda algo fora do MB Suite, o que tem um custo à parte e o que sempre pede levam dry_run e confirm_token: o agente pede primeiro a prévia e depois confirma com o token (10 minutos); sem token, 409 confirmation_required. Algumas poucas pedem só com certos dados (needs_confirmation_when em mb_describe_operation). Pelo MCP, dry_run vale em qualquer escrita: o needs_confirmation dela diz se executá-la pede o token. Veja Prévia e confirmação.
• Em mb_execute_operation, dry_run, confirm_token, audit_note, idempotency_key e org_id vão junto de id (dentro de input também valem; se vierem nos dois lugares com valores diferentes, 400). Numa ferramenta tipada vão com o resto dos argumentos.
• Se a credencial alcança Contas, as ferramentas somam org_id (opcional) para apontar para uma.
• Para repetir uma escrita sem risco (depois de uma queda ou de um timeout), envie a mesma idempotency_key (até 255 caracteres): durante 24 horas, a mesma chamada devolve o resultado guardado (idempotent_replayed: true) em vez de rodar de novo; com outra chamada é 422 idempotency_key_reused, e enquanto a primeira roda, 409 idempotency_in_progress. É a Idempotency-Key da API (Idempotência).
• Uma exclusão que deixa cópia devolve trash_item_id (num lote, trash_item_ids) e trash_expires_at; platform.trash.restore a restaura por esse item_id ou por entity_type + entity_id (owner ou admin). Se algo pode ser desfeito está na descrição de cada operação.
• Cada resultado traz structuredContent (JSON em snake_case) e, como texto, o mesmo JSON (ou um resumo, se for muito grande). Um erro chega com isError, o mesmo corpo da API e um texto que diz o código, o campo (Field: …), os primeiros problemas (Problems: …), quanto esperar quando se aplica e o request_id.
• Uma resposta grande demais para uma mensagem chega cortada, com mcp_notice: uma página de uma lista volta com um limit menor e o next_cursor dela segue logo depois do que veio; se não, o aviso diz o que ficou de fora e como pedir o resto.

O que o MCP não faz

• Não cria, edita, testa nem exclui webhooks, nem rotaciona o segredo, nem reenvia entregas: isso é da tela. Pelo MCP se leem as assinaturas, os eventos e as entregas.
• Não cria nem rotaciona API keys (a API também não).
• E-mail e calendário conectados, só com as três travas (veja Permissões).

Desconectar

Cada pessoa vê e desconecta os seus apps em Configurações → API e MCP → MCP; owners e admins veem os de toda a organização. Desconectar corta na hora.