Pular para o conteúdo principal

Clientes

Qualquer cliente que fale MCP sobre Streamable HTTP e saiba executar o fluxo OAuth 2.1 do MCP consegue conectar. Você só informa a URL; o cliente descobre sozinho onde autenticar, abre o login da Kobana no navegador e guarda o token — veja Autenticação.

Um cliente sem suporte a OAuth também conecta, com um token pessoal: crie-o em Conta Kobana → Tokens e Acesso → Novo Token Pessoal, com o app Inbox Autônomo e o uso MCP, e configure o cliente para enviá-lo como Authorization: Bearer <token>. Esse também é o caminho para um agente que precisa escrever, já que hoje o fluxo OAuth concede acesso somente leitura.

Quando sua organização tem mais de um workspace, escolha um por conexão com o header X-Workspace-Id.

Claude Code​

claude mcp add --transport http kobana-inbox https://mcp.inbox.kobana.com.br

Depois, rode /mcp em uma sessão e escolha Authenticate para entrar na Kobana.

Com um token pessoal, sem o fluxo OAuth:

claude mcp add --transport http kobana-inbox https://mcp.inbox.kobana.com.br \
  --header "Authorization: Bearer <personal token>"

Clientes configurados por arquivo​

Clientes que leem um arquivo de configuração JSON pedem a URL e o transporte. Pelo fluxo OAuth não há header de autenticação:

{
  "mcpServers": {
    "kobana-inbox": {
      "type": "http",
      "url": "https://mcp.inbox.kobana.com.br"
    }
  }
}

Na primeira conexão, o cliente abre o navegador para você autorizar. Você escolhe a organização na tela de consentimento, e ela fica registrada no token.

Com um token pessoal, acrescente os headers — a organização é a da conta em que você criou o token:

{
  "mcpServers": {
    "kobana-inbox": {
      "type": "http",
      "url": "https://mcp.inbox.kobana.com.br",
      "headers": {
        "Authorization": "Bearer <personal token>",
        "X-Workspace-Id": "<workspace-id>"
      }
    }
  }
}

X-Workspace-Id só é necessário quando sua organização tem mais de um workspace. Trate o arquivo como segredo: quem o lê usa o token.

Clientes que conectam por URL​

Claude e ChatGPT conectam um servidor remoto colando https://mcp.inbox.kobana.com.br nas configurações de conectores. O fluxo OAuth roda dentro do próprio app.

Usando outros servidores Kobana junto​

As tools daqui não têm prefixo (emails_list), e os resources ficam sob kobana://inbox/; os outros servidores MCP da Kobana prefixam os seus (billing_, finance_, kobana://billing/, kobana://finance/). Eles convivem no mesmo cliente sem colidir.

Postura recomendada para agentes​

  • Autorize com a conta certa. As tools são restritas ao que a pessoa que autorizou pode fazer no dashboard. Um cliente autorizado por um analista somente-leitura expõe só as tools de leitura, tente o modelo do outro lado o que tentar. É a forma mais forte de restringir um agente.
  • Mantenha o token somente-leitura. Um token com escopos de recurso mas sem o verbo write fisicamente não altera nada. O fluxo OAuth é somente leitura por construção; num token pessoal, marque escrita só nos recursos que o agente precisa alterar.
  • Token pessoal: validade curta, escopo mínimo. Revogá-lo na Kobana não corta o acesso antes de ele expirar — veja Revogação do token pessoal.
  • Deixe as tools destrutivas de fora a menos que precise delas. Exclusões, ações para fora (teste e reenvio de webhook, reprocessamento de e-mail), rotação de segredo e mudanças na lista de remetentes exigem o verbo write e uma permissão que o administrador da organização concede explicitamente, e o servidor pede ao usuário que confirme cada uma — só um cliente no protocolo 2026-07-28 com formulários de elicitation consegue executá-las.

Servidores stdio locais​

O repositório também traz sete servidores MCP stdio, um por recurso (workspaces, inboxes, emails, agents, agent-runs, webhooks, system-events). Eles rodam na sua máquina, falam com a API pública por HTTPS e usam a pilha completa de autenticação REST — JWT, certificado mTLS de cliente e segredo de origem.

Continuam sendo uma opção válida e não são substituídos por este servidor. Use-os quando você já tem um certificado de cliente e quer o escopo mínimo garantido por rodar apenas o servidor de que precisa; use o servidor remoto quando não puder distribuir um certificado ao cliente.