MCP nativo: Conexões MCP, servidor do Maestro e cliente (Model Context Protocol)

Visão geral

O MCP (Model Context Protocol) é o padrão aberto que permite a assistentes de IA (Claude, IDEs, agentes) usarem ferramentas e dados de sistemas externos de forma segura. A Conversa Labs traz MCP nativo, e você opera tudo por telas — sem escrever integração.

São três superfícies:

• Conexões MCP da conta (perfis de acesso) — em vez de uma única configuração da conta, você cria N perfis nomeados. A conexão de Bearer estático de cada perfil tem sua seleção de módulos, modo somente leitura, usuário de execução (membro da conta) e URL + segredo bearer próprios. Essa conexão estática opera como o usuário de execução e só consegue restringir o que ele já pode fazer, nunca ampliar. Quando a instalação habilita o OAuth nativo, o mesmo perfil também tem uma URL OAuth separada: as ferramentas continuam limitadas pelo perfil, mas cada chamada opera como o membro da conta que aprovou o consentimento OAuth — nunca como o usuário estático do perfil.
• Servidor MCP do Maestro — expõe os departamentos do Maestro como ferramentas ask_<departamento> para clientes externos, sob um token por conta. O cliente nunca ganha mais autonomia do que o departamento já tem configurada.
• Robô como cliente MCP — cada Robô pode consumir servidores MCP externos (Linear, Notion, Stripe, GitHub, ERP interno) como ferramentas adicionais, com as mesmas regras de aprovação (HITL), orçamento de ferramentas e auditoria dos demais recursos.

A conexão estática da conta e o servidor do Maestro usam o cabeçalho padrão Authorization: Bearer <credencial>. Os exemplos abaixo configuram esse caminho estático: na conta, a credencial é o segredo do perfil; no Maestro, o token do Maestro. Eles são exemplos de configuração, não prova de que todo produto ou versão foi validado nesta instalação. O OAuth nativo da conta é um recurso separado e condicional, com discovery, PKCE e consentimento no navegador; não aponte um cliente OAuth para a URL estática nem suponha compatibilidade sem testá-la.

Identidade visual do conector

Na inicialização MCP com o protocolo 2025-11-25, o servidor envia o nome e o título da instalação, descrição, site e os ícones da marca (um principal e variantes clara/escura). As telas de login e de consentimento OAuth usam a mesma identidade; se a imagem configurada não carregar, exibem as iniciais da instalação. Esses dados só são publicados quando há uma origem canônica pública e segura em HTTPS. Sem ela, o servidor omite URLs e ícones em vez de expor um endereço interno ou não confiável.

O cliente decide se e como mostra esses campos. Clientes que negociam uma versão MCP mais antiga ainda recebem o nome técnico do servidor, mas o protocolo não entrega os ícones. No Conector personalizado do Claude, use o nome que você digitou na configuração: a interface pode continuar mostrando esse nome até que ela use os metadados do servidor. A aparência não altera escopos, consentimento nem credenciais.

Os endpoints de Conta, Plataforma e Super Admin montam esse retrato seguro a cada inicialização MCP. Depois de uma alteração de White Label ou do emissor canônico, o mesmo retrato versionado é enfileirado para o endpoint direto do Maestro; a próxima requisição autenticada usa o retrato válido persistido mais novo. Uma indisponibilidade temporária do Maestro nunca desfaz a marca salva: o reconciliador agendado tenta de novo. Se o provedor já criou um conector, desconecte e adicione o servidor novamente para forçar um novo initialize — isso não rotaciona token nem muda permissões. A URL do ícone precisa ser um ativo de primeira parte nessa própria origem canônica, público, HTTPS e acessível sem login; CDN externo ou outro host não é publicado como metadado de marca MCP. Um cliente de terceiro pode manter o ícone em cache ou optar por não renderizar metadados de ícone MCP; o servidor não consegue substituir esse comportamento do cliente.

Pré-requisitos

• Recurso MCP habilitado para a conta. Sem a flag, a página Configurações → MCP simplesmente não aparece no menu (e o interruptor global da instalação também precisa estar ligado).
• Perfil de administrador da conta para gerenciar as Conexões MCP (a página e a criação/edição de perfis são restritas a administradores).
• Para a conexão da conta: nenhum token pessoal. Cada perfil (Conexão MCP) gera o seu próprio segredo bearer na criação/rotação — é essa a credencial do cliente. O usuário de execução do perfil precisa ser membro da conta. Tokens de Robô (AgentBot) e o token pessoal de API não são a credencial da conexão da conta.
• Para a conexão opcional de OAuth nativo da conta: o responsável pela instalação precisa habilitar o OAuth nativo do MCP, aplicar as migrations de banco do OAuth MCP desta versão e configurar um emissor público HTTPS válido, além do recurso MCP da conta e do interruptor global. Uma flag não substitui a migration da estrutura do banco nem prova o fluxo. A URL OAuth é diferente da conexão estática; o segredo estático do perfil nunca a autentica. Quem aprova o consentimento no navegador precisa ser membro ativo da conta.
• O host do emissor deve resolver e rotear pelo gateway público para esta mesma instalação. Ele precisa servir os endpoints MCP OAuth e os documentos de Metadados de Recurso Protegido e discovery do servidor de autorização; um endereço HTTPS sintaticamente válido que roteia para outro lugar não basta.
• Antes de adotar OAuth nativo em um cliente de terceiros, exercite discovery, PKCE e consentimento em ambiente controlado. Um endpoint baseado em padrão não prova que um produto, aplicativo desktop ou superfície de IA hospedada suporte o fluxo exigido.
• Para o servidor do Maestro: o Maestro provisionado para a conta. Sem isso, o card do Maestro é substituído por um aviso.
• Para conectar um servidor MCP externo por OAuth: o Robô já salvo e o navegador liberado para abrir pop-ups (a tela de consentimento do provedor abre em uma janela).

Passo a passo

1. Abrir a página MCP

Vá em Configurações → MCP. A tela traz o card Conexões MCP da conta (os perfis de acesso) e o card Servidor MCP do Maestro.

2. Criar uma Conexão MCP (perfil de acesso)

No card Conexões MCP da conta, clique em Novo perfil. Cada perfil é uma conexão independente:

1. Dê um nome ao perfil (por exemplo claude-code-suporte ou bi-somente-leitura) — ele ajuda a identificar qual cliente usa cada conexão.

2. Escolha o usuário de execução — um membro da conta. O perfil executa como esse usuário: a lista de ferramentas efetiva é a interseção da sua seleção com o teto do Super Admin e com as permissões desse usuário. Ou seja, um perfil só restringe — nunca concede mais do que o usuário já tem. Só pertencem a este servidor rotas enraizadas em /api/v{N}/accounts/{account}: rotas pessoais de perfil, MFA, sessões e notificações ficam fora da conexão da conta, mesmo quando o usuário também pertence a outras contas.

3. Escolha os módulos que ficam expostos. É o mesmo seletor de sempre: toda a plataforma (mais de 100 módulos), organizada em áreas recolhíveis — Conversas e atendimento, Contatos e CRM, Catálogo e vendas, Pagamentos, Tarefas e agenda, WhatsApp, Canais e integrações, Automação e IA, Growth e vendas, Relatórios, Equipe e administração e Conteúdo. Use a busca para achar um módulo pelo nome ou pela descrição, e o Selecionar tudo de cada área para ligar a área inteira de uma vez. Cada linha mostra o que o módulo faz e quantas ferramentas ele adiciona (o preço da caixinha); o resumo embaixo da busca soma a seleção atual e avisa se ela passar do teto de ferramentas — que continua valendo por perfil:

   Alguns exemplos (a lista completa está na tela, por área):

   Exemplos de módulo	O que expõe
   Conversas	ler, responder, mudar status, atribuir, aplicar labels (ligado por padrão)
   Contatos	buscar, criar e atualizar contatos (ligado por padrão)
   Relatórios	métricas e análises (somente leitura)
   Tarefas	módulo nativo de tarefas
   Itens de CRM	negócios e pipeline
   Central de Ajuda	artigos da base de conhecimento
   Catálogo	produtos
   Follow-up	cadências de follow-up
   Biblioteca de Mídia	arquivos de mídia

   Toolsets ligados por padrão trazem o selo default. Se o Super Admin não liberou um toolset no teto global, a linha aparece desabilitada e com o selo bloqueado pelo super admin — você não consegue marcá-la.

   Acima da lista há atalhos de ponto de partida: Essencial, Atendimento, Comercial e Tudo. Eles apenas somam módulos à seleção atual — nada é removido, e nenhum módulo some da lista porque um atalho não o menciona. Use um deles para começar e ajuste na mão; módulos bloqueados pelo teto continuam de fora, como sempre.

4. Modo somente leitura: marque a caixa para o perfil expor apenas ferramentas que leem dados (nada de criar, atualizar ou apagar).

5. Compatibilidade com a pesquisa profunda do ChatGPT (opcional): o conector de pesquisa profunda do ChatGPT exige, pelo nome, duas ferramentas chamadas search e fetch, e recusa um servidor que não as tenha. Marque a caixa só nos perfis usados por esse conector. As duas ferramentas apenas descrevem o que o perfil já expõe — não concedem nenhum acesso extra —, mas ocupam espaço na lista dos outros clientes. Deixe desmarcado para Claude, Claude Code e clientes genéricos.

6. Salve o perfil. Nesse momento o segredo bearer é exibido em texto puro uma única vez (formato mcp_...) — copie na hora. Só o hash e os quatro últimos caracteres ficam guardados; a plataforma nunca mostra o segredo de novo.

7. Copie a URL da conexão. O formato é https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO, onde ID_PUBLICO é um identificador não secreto (um slug na URL) — quem autentica é o segredo bearer, não a URL. Essa é a URL de Bearer estático.

Se a instalação habilitou OAuth nativo do MCP, o mesmo perfil tem outro recurso exato: https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/oauth/c/ID_PUBLICO. Não troque mcp/c por esse caminho em um cliente estático existente e não cole nele o segredo do perfil. O perfil continua selecionando as ferramentas, mas chamadas OAuth executam como o membro que aprovar o consentimento.

Depois, cada perfil tem, no card, os botões Editar (troca nome, usuário de execução, módulos e modo somente leitura), Rotacionar token (gera um novo segredo e invalida o anterior na hora) e Excluir. Desativar ou excluir o perfil — ou o usuário de execução deixar de ser membro da conta — faz a conexão parar de responder (401/404).

3. Configurar o servidor MCP do Maestro

1. No card Servidor MCP do Maestro, veja o status: Token configurado ou Ainda sem token.
2. Clique em Gerar token (ou Rotacionar token, se já existir um).
3. O token em texto puro é exibido uma única vez — copie na hora. Ele nunca mais é mostrado. Rotacionar invalida o token anterior imediatamente.
4. Copie a URL do endpoint do Maestro (termina em /mcp).
5. Um cliente externo com essa URL + token enxerga uma ferramenta ask_<departamento> por departamento ativo da conta.

Se o Maestro não estiver configurado para a conta, o card é substituído por um aviso — provisione o Maestro antes.

4. Conectar um cliente MCP com Bearer estático

Esta seção configura somente a conexão de Bearer estático: use Streamable HTTP, a URL estática do perfil no passo 2 (ou a URL do Maestro no passo 3) e a credencial no cabeçalho Authorization: Bearer .... Na conta, ela é o segredo do perfil (o mcp_... revelado ao criar ou rotacionar); no Maestro, o token do Maestro. Formatos de configuração dos clientes mudam fora desta documentação; valide a versão exata em ambiente controlado. Nenhum snippet abaixo configura OAuth nativo.

Claude Code — pelo terminal:

claude mcp add --transport http helpdesk \
  https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO \
  --header "Authorization: Bearer SEGREDO_DO_PERFIL"

Ou no .mcp.json do projeto:

{
  "mcpServers": {
    "helpdesk": {
      "type": "http",
      "url": "https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO",
      "headers": { "Authorization": "Bearer SEGREDO_DO_PERFIL" }
    }
  }
}

Cursor — em ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto):

{
  "mcpServers": {
    "helpdesk": {
      "url": "https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO",
      "headers": { "Authorization": "Bearer SEGREDO_DO_PERFIL" }
    }
  }
}

VS Code (modo agente) — em .vscode/mcp.json:

{
  "servers": {
    "helpdesk": {
      "type": "http",
      "url": "https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO",
      "headers": { "Authorization": "Bearer SEGREDO_DO_PERFIL" }
    }
  }
}

MCP Inspector — para depurar a conexão e ver a lista crua de ferramentas:

npx @modelcontextprotocol/inspector

No painel: Transport Type = Streamable HTTP, URL = a URL da conexão, e em Authentication informe o Bearer Token — o segredo do perfil para a conexão da conta, ou o token do Maestro para o servidor do Maestro (ou um header Authorization com o valor Bearer <credencial>). Clique em Connect e depois em List Tools.

Windsurf — mesma ideia: servidor remoto com a URL da conexão e headers contendo Authorization: Bearer SEGREDO_DO_PERFIL (ou o token do Maestro).

Em todos eles o cliente faz initialize, depois tools/list (lista as ferramentas expostas) e finalmente tools/call para executar uma delas. Se o cliente exibir menos ferramentas do que o esperado, é o teto de exibição: use search_tools para achar qualquer outra ferramenta (ele devolve o schema dela) e call_tool para executá-la. Nada fica inalcançável — só fora da lista.

4a. Conectar o recurso OAuth nativo da conta (condicional)

Este é um caminho de conexão separado, disponível somente quando o OAuth nativo do MCP está habilitado na instalação e o recurso/perfil MCP da conta estão disponíveis. Ele não converte a conexão de Bearer estático e não é uma alternativa para um segredo de perfil perdido.

1. Configure o cliente com a URL exata do recurso OAuth: https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/oauth/c/ID_PUBLICO.
2. Comece pelos Metadados de Recurso Protegido desse recurso, não por uma URL de host adivinhada: https://SEU-DOMINIO/.well-known/oauth-protected-resource/mcp/oauth/accounts/ID_DA_CONTA/connections/ID_PUBLICO. Eles só anunciam o servidor de autorização canônico enquanto o recurso estiver disponível.
3. Descubra o servidor de autorização em https://SEU-DOMINIO/.well-known/oauth-authorization-server/oauth/mcp (ou use o emissor anunciado pelos metadados). O servidor usa Authorization Code público, PKCE S256 obrigatório, vínculo ao recurso exato e nenhum segredo de cliente. Os metadados de discovery declaram authorization_response_iss_parameter_supported: valide o emissor canônico retornado no parâmetro iss nos callbacks de sucesso e de erro redirecionável. O handoff de navegador guarda os valores da autorização de forma assinada e aceita no máximo 1.024 bytes somados entre os parâmetros persistidos (incluindo client_id, redirect_uri, resource e state). Use um state curto e opaco; não tente ampliar o fluxo com URLs ou estados grandes.
4. Um cliente público pode usar Client ID Metadata público verificado (CIMD). Registro Dinâmico de Cliente (DCR) é condicional e desligado por padrão: só aparece no discovery depois que um Super Admin habilita Dynamic Client Registration em MCP Settings. Se estiver desligado, o discovery omite registration_endpoint e o registro devolve 404 — isso não é falha de OAuth. Quando ligado, o operador acompanha o cliente em MCP OAuth clients e pode desativá-lo; a desativação confirmada, com razão e reautenticação, é irreversível e revoga a família de consentimento/tokens. DCR continua sendo um caminho governado de teste, não uma promessa de compatibilidade de fornecedor. Nunca envie para esse fluxo segredo de perfil, token pessoal de API, credencial de Super Admin ou segredo de cliente.
5. No navegador, se já houver uma sessão ativa do painel da conta ou do Console do Super Admin para uma identidade que seja membro da conta alvo, ela é validada no servidor e reutilizada: você vai direto à revisão do consentimento, sem digitar a senha novamente. A aprovação continua obrigatória. Uma identidade Super Admin só entra por este fluxo quando também possui vínculo de membro da conta, e o grant/token permanece limitado à conta, ao perfil e aos escopos — nenhuma autoridade global é herdada. Se a sessão estiver ausente, expirada, inválida ou for de outra conta, o formulário manual aparece e exige uma identidade de membro válida. mcp:read é o escopo de leitura; ferramentas de escrita também exigem mcp:write e um perfil que não seja somente leitura. offline_access pede explicitamente um refresh token rotativo.
6. Em Configurações → Perfil → Conexões MCP, um membro revisa e revoga suas próprias conexões aprovadas. Um administrador da conta revisa todos os grants da conta e precisa selecionar uma razão fechada quando revoga pelo fluxo administrativo. Revogar invalida a família de credenciais conectada.

4b. Verificar o recurso público antes de conectar um cliente OAuth

Antes de abrir o Claude.ai, Claude Code ou outro cliente remoto, um operador pode verificar o contrato público sem fornecer credencial alguma:

ruby scripts/mcp_oauth_preflight.rb \
  --base-url https://SEU-DOMINIO \
  --account-id ID_DA_CONTA \
  --profile-public-id ID_PUBLICO

Para a autoridade separada do Super Admin, use:

ruby scripts/mcp_oauth_preflight.rb \
  --base-url https://SEU-DOMINIO \
  --super-admin

O verificador aceita somente origem HTTPS pública com nome DNS (recusa IP literal e host interno), não segue redirecionamentos e confere os Metadados de Recurso Protegido exatos, emissor e audiência, discovery, Client ID Metadata (CIMD), PKCE S256, retorno iss, escopos e o desafio 401 de um tools/list JSON-RPC sem Bearer. Quando o discovery anunciar DCR, ele confere também o endpoint exato; a ausência explícita por gate desligado é um estado válido. Só avance para o teste controlado quando ele terminar com RESULT: PASS. Em falha, corrija a publicação antes de conectar qualquer cliente. Esse resultado confirma a publicação do servidor; não comprova compatibilidade de um provedor externo.

Ele não registra cliente, não abre consentimento, não troca/revoga token e não altera perfil, grant ou credencial. A instância remota pode gravar a telemetria de auditoria sem segredo normal de discovery e do desafio 401; isso é observabilidade, não um cliente OAuth criado pelo verificador.

Claude.ai — Conector personalizado

Depois de o operador habilitar o OAuth MCP e a página Configurações → MCP mostrar o Endereço de conexão OAuth do perfil, use a área de conectores correspondente ao seu plano do Claude:

Use este roteiro como teste controlado da versão de Claude disponível na sua organização. Só libere a conexão para outras pessoas depois de registrar discovery, consentimento, tools/list, uma leitura e uma revogação bem-sucedidos.

O conector remoto do Claude alcança o servidor pela infraestrutura de nuvem do Claude, inclusive quando você está no Claude Desktop. Portanto o issuer precisa ser HTTPS público e alcançável fora da VPN/rede privada; estar acessível apenas pelo seu navegador não basta. Conectores personalizados remotos estão disponíveis no Claude, Cowork e Claude Desktop nos planos Free, Pro, Max, Team e Enterprise; no Free há limite de um conector personalizado. Consulte também o guia atual de conectores remotos do Claude.

1. Em Team/Enterprise, Owner ou Primary Owner abre Organization settings → Connectors → Add → Custom → Web e cadastra a URL MCP remota. Depois cada membro vai a Customize → Connectors e clica em Connect. Em Free/Pro/Max, vá a Customize → Connectors → + → Add custom connector na própria conta (Free permite um conector).
2. Dê um nome claro, por exemplo Conversa Labs — Suporte, e cole o Endereço de conexão OAuth em URL MCP remota. Não use a URL Bearer estática.
3. Advanced settings é opcional. Neste servidor de cliente público, nunca preencha Client Secret nem use token Bearer, segredo do perfil ou credencial de Super Admin em qualquer campo. Se a versão do Claude precisar de DCR, habilite-o previamente e de forma explícita pelo Super Admin; caso contrário, ela precisa usar CIMD ou cliente já provisionado.
4. Clique em adicionar, entre como membro ativo da conta e leia/aprove o consentimento. O Claude passa a agir como essa pessoa, limitado pelo perfil, pelos seus próprios papéis e pelos scopes.

O callback é controlado pelo cliente e é informação de registro, não uma URL que você deve trocar manualmente no recurso MCP. Registre a versão do Claude e o callback efetivamente recebido no teste; não cole tokens, códigos ou parâmetros de callback na evidência.

Para desconectar, revogue o grant em Configurações → Perfil → Conexões MCP (ou, sendo administrador, na mesma tela da conta). Não rotacione um token bearer estático: ele é outro tipo de conexão e não desconecta o Claude OAuth.

Não marque um produto de terceiro como compatível apenas porque ele oferece MCP ou OAuth. Valide produto, versão, redirecionamento e resultado do consentimento ponta a ponta antes de liberá-lo para usuários.

Matriz de conectores externos — teste controlado

Estado de todas as linhas abaixo: não validado nesta instalação. A matriz explica como preparar uma tentativa segura; ela não declara suporte do fornecedor. Comece sempre por mcp:read, initialize, tools/list e uma leitura em dado de teste. Só teste escrita depois de autorização explícita.

O recurso OAuth de Super Admin é outro plano de autoridade e usa outra URL; nunca substitua a URL de Conta acima por /super_admin/mcp/oauth. Para ele, siga o artigo de Operador e faça um teste separado. Registre versão, plano/entitlement, resultado de discovery, consentimento, tools/list, leitura, evento de auditoria, revogação e a chamada negada — sem copiar tokens, códigos, verifiers ou URLs com parâmetros.

Claude Code: a autorização local usa callback loopback com porta efêmera. A política restrita de redirect RFC 8252 para esse callback já tem matcher e teste HTTP locais; uma URL fixa localhost/127.0.0.1 não representa sozinha a porta real. Isso não é prova de compatibilidade: o E2E externo continua bloqueado até haver issuer HTTPS público, Inspector e evidência do cliente real.

5. Dar servidores MCP externos a um Robô (o Robô como cliente)

1. Vá em Configurações → Robôs, abra o Robô e localize a seção Servidores MCP.
2. Clique em Adicionar servidor e preencha:
   • Nome técnico — letras minúsculas, números e _, começando por letra (2 a 33 caracteres), por exemplo github. É o prefixo das ferramentas desse servidor.
   • URL do servidor MCP (a que o provedor publica).
   • Transporte: Streamable HTTP (recomendado) ou SSE (legado).
   • Timeout em segundos.
3. Autenticação: escolha o tipo — nenhuma, bearer, header, query, basic ou OAuth. Nos tipos com segredo, informe o nome do segredo — nunca o valor. O valor fica no cofre de segredos e nunca é enviado ao modelo. No tipo OAuth não há campo de segredo: a credencial é obtida no passo 6.
4. Cabeçalhos adicionais (opcional): pares chave/valor, só se o servidor exigir.
5. Marque Exigir aprovação (HITL) para que toda chamada às ferramentas desse servidor passe por aprovação humana.
6. Clique em Descobrir: a plataforma conecta ao servidor agora e lista as ferramentas antes de você salvar. Servidores grandes (Linear, Notion) devolvem dezenas de ferramentas com descrições longas — use a busca e o Selecionar tudo / Limpar para curar sem rolar a lista inteira; o contador mostra quantas você marcou. Você pode selecionar um subconjunto (allowlist) — se não selecionar nenhuma, todas as ferramentas do servidor ficam disponíveis.
7. Salve o Robô. As ferramentas são descobertas e armazenadas no momento de salvar; o turno do agente nunca faz descoberta de rede.

Para que a descoberta resolva segredos já armazenados, salve o Robô primeiro e só então clique em Descobrir.

6. Conectar um servidor externo por OAuth (botão Conectar)

Alguns servidores (o Notion, por exemplo) só aceitam OAuth — não existe chave estática. Nesses casos:

1. No servidor MCP do Robô, escolha Autenticação → OAuth. Os campos de segredo somem — não há o que preencher.
2. Salve o Robô (a conexão é guardada por Robô + nome do servidor).
3. Clique em Conectar. Uma janela neutra de autorização abre imediatamente; mantenha-a aberta. Quando a plataforma recebe o endereço do provedor, a janela navega para a tela de consentimento em contexto isolado — o provedor não recebe acesso à aba do Studio. Faça login e autorize.
4. A janela se fecha sozinha ao terminar e o status vira Conectado (com validade e escopo, quando o provedor informa). Se ela permanecer aberta depois da confirmação do provedor, feche-a para que o Studio consulte o status. Se o navegador bloquear a janela, permita popups para este site e tente de novo.
5. Clique em Descobrir e siga normalmente: as ferramentas do servidor passam a valer para o Robô.
6. Desconectar esquece as credenciais desse par Robô + servidor. Para trocar de conta no provedor: desconecte e conecte de novo.

As credenciais OAuth ficam cifradas no Maestro, atreladas ao par Robô + servidor. Elas nunca são guardadas na Conversa Labs, nunca aparecem em telas ou logs e nunca são enviadas ao modelo.

Configurações & opções

• Perfis (Conexões MCP) da conta: cada perfil tem nome, usuário de execução estático, seleção de toolsets, modo somente leitura, URL estática (com public_id) e segredo bearer próprio (revelado uma única vez, rotacionável). A seleção estática efetiva é sempre seleção ∩ teto do Super Admin ∩ permissões do usuário de execução.

• OAuth nativo da conta (condicional): o recurso OAuth é a URL separada /mcp/oauth/c/ID_PUBLICO. Ele usa a superfície de ferramentas do perfil, mas o membro que consentiu, não o usuário estático. Seus grants são visíveis/revogáveis em Configurações → Perfil → Conexões MCP; grants existentes continuam visíveis para revogação se o servidor for desabilitado depois.

• Modo somente leitura: por perfil, expõe só ferramentas de leitura.

• Compatibilidade com a pesquisa profunda do ChatGPT: por perfil, acrescenta as duas ferramentas search e fetch que aquele conector exige pelo nome. Elas apenas descrevem o que o perfil já expõe. Custam duas vagas do teto de ferramentas (o servidor reserva quatro em vez de duas quando ligado), então deixe desligado para Claude e clientes genéricos.

• Teto de ferramentas: há um limite por servidor (512), aplicado por perfil — ele corta a lista, não o acesso. As meta-ferramentas search_tools (descobre, com o schema) e call_tool (executa pelo nome) alcançam tudo o que o perfil habilitou, sempre respeitando o modo somente leitura, as permissões do usuário de execução e o teto do Super Admin.

• Token do Maestro: um por conta, revelado uma única vez, rotacionável a qualquer momento.

• Servidores externos por Robô: nome técnico, URL, transporte, timeout, autenticação, cabeçalhos extras, aprovação (HITL) e allowlist de ferramentas.

• Tipos de autenticação (servidor externo):

  Tipo	Como funciona	Quando usar
  nenhuma	nada é enviado	servidores realmente públicos (raro)
  bearer	envia Authorization: Bearer <segredo>	o caso mais comum — segredo guarda a chave de API
  header	envia um cabeçalho com nome à sua escolha e valor do segredo	o provedor usa um esquema próprio
  query	envia o segredo como parâmetro na URL	provedores legados
  basic	usuário + senha (dois segredos)	servidores internos
  OAuth	botão Conectar → consentimento no provedor	o provedor só aceita OAuth (Notion)

• Orçamento de ferramentas: as ferramentas de cada servidor externo contam no orçamento de ferramentas do Robô — servidores demais estouram o limite.

• Proteção SSRF: endereços privados/internos são bloqueados ao adicionar um servidor externo.

Casos de uso

• Operar a caixa de entrada a partir do Claude Code ou de uma IDE: listar conversas, responder, resolver.
• Um perfil por cliente: cada IDE, script ou parceiro recebe a sua própria conexão, com escopo mínimo e — nos clientes de leitura — o modo somente leitura ligado.
• Puxar relatórios da conta para dentro de um assistente com um perfil somente leitura, executado por um usuário de perfil restrito.
• Revogar um único cliente: rotacione (ou exclua) o perfil daquele cliente — os demais perfis continuam funcionando.
• Dar ao Robô acesso a um sistema interno (ERP, base de conhecimento) via servidor MCP externo, com aprovação humana nas ações sensíveis.
• Deixar o Robô abrir tarefas no Linear ou ler uma base no Notion durante o atendimento.
• Deixar o time de dados perguntar ask_risco / ask_financeiro e receber as descobertas do departamento sem abrir o painel.

Dicas, limites e boas práticas

• Qual autenticação escolher em cada servidor externo popular (a maioria responde 401 com desafio OAuth, mas aceita uma chave de API comum em Authorization: Bearer — deixar em nenhuma é a causa número 1 de falha na descoberta):

  Servidor MCP externo	Autenticação a escolher
  Linear	bearer + segredo com a chave de API
  Stripe	bearer + segredo com a chave restrita
  GitHub	bearer + segredo com um token pessoal (PAT)
  Atlassian (Jira/Confluence)	bearer + segredo com o token de API
  Sentry	header com nome Authorization e segredo cujo valor é Sentry-Bearer SEU_TOKEN
  Notion	OAuth (botão Conectar) — não aceita chave estática
  Servidor interno próprio	conforme o servidor exigir

• Segredo estático versus consentimento OAuth: o segredo estático do perfil carrega as permissões do usuário de execução estático — nunca mais do que ele já tem. Um grant OAuth nativo roda como o membro que consentiu e fica vinculado ao recurso OAuth exato. Trate ambos como credenciais e nunca os troque entre as duas URLs.

• Um perfil por cliente: assim você dá escopo mínimo a cada um e pode rotacionar/excluir um perfil para cortar só aquele cliente, sem tocar nos outros.

• Somente leitura primeiro: comece cada perfil com o modo somente leitura ligado e habilite a escrita por toolset conforme a confiança no cliente.

• Menos é mais: exponha só os toolsets que o cliente realmente usa — listas enormes de ferramentas pioram a escolha do modelo.

• Copie o segredo do perfil na hora: ele não é exibido de novo. Perdeu? Rotacione o token do perfil (o anterior é invalidado na hora) e atualize o cliente que o usava.

• Segredos por referência: em servidores MCP externos, nunca cole o valor do segredo no campo — informe a chave do segredo.

• Copie o token do Maestro na hora: ele não é exibido de novo. Perdeu? Rotacione (e atualize os clientes que usavam o anterior).

• Aprovação (HITL): para servidores externos que escrevem em sistemas críticos, marque Exigir aprovação.

Solução de problemas

• O cliente mostra menos ferramentas do que os módulos que liguei no perfil: é o teto de exibição do servidor. As demais continuam alcançáveis: peça ao cliente para usar search_tools (encontra a ferramenta e devolve o schema dela) e call_tool (executa pelo nome). Para vê-las na lista, desmarque módulos ou peça ao operador para aumentar o teto.
• O card do Maestro mostra um endereço interno (aviso âmbar): a instalação não declarou o endereço público do Maestro. Um cliente na mesma máquina conecta; uma IDE fora da rede, não. O operador precisa definir MAESTRO_PUBLIC_BASE_URL com o endereço público do Maestro (e reiniciar a aplicação).
• O cliente conecta pelo endereço público do Maestro e recebe "Invalid Host header" (ou 421): o Maestro só aceita o Host que a instalação declarou. É o mesmo MAESTRO_PUBLIC_BASE_URL — depois de defini-lo, o host público passa a ser aceito (a proteção contra DNS rebinding continua ligada).
• Um conector ainda mostra ícone antigo ou genérico: confirme que a origem canônica pública HTTPS e a URL do ícone carregam sem autenticação, salve o White Label e reconecte o provedor para ele executar initialize outra vez. O servidor preserva a última marca válida enquanto o Maestro tenta novamente após uma indisponibilidade temporária; o provedor ainda pode manter cache ou decidir não exibir seus metadados de ícone.
• A página MCP não aparece no menu: o recurso MCP está desligado para a conta (peça ao operador) ou o seu usuário não é administrador.
• 404 no endpoint da conexão: o recurso está desligado para a conta, o interruptor global da instalação está desativado, ou o ID_PUBLICO da URL não existe (perfil excluído ou desativado).
• 401 na conexão da conta: o segredo do perfil está errado ou foi rotacionado (o anterior é invalidado na hora), o perfil foi excluído/desativado, ou o usuário de execução deixou de ser membro da conta. Use o segredo revelado ao criar/rotacionar o perfil — token pessoal de API e token de Robô não são a credencial dessa conexão.
• Um cliente estático tenta fazer login por OAuth: a URL estática da conta termina em /mcp/c/ID_PUBLICO e aceita apenas o segredo do perfil em Authorization: Bearer ...; ela não anuncia servidor OAuth. Mantenha esse cliente na configuração de Bearer estático.
• O recurso OAuth ou o discovery retorna 404: o OAuth nativo é propositalmente dark-shipped. Confira a habilitação do OAuth nativo, o recurso/perfil MCP da conta e o emissor público; então recomece pelos Metadados de Recurso Protegido exatos. Não substitua por segredo estático nem token de outro plano.
• A URL OAuth retorna 401: o Bearer OAuth está ausente, expirou, foi revogado ou pertence a outro recurso/plano. Leia o cabeçalho WWW-Authenticate: ele aponta para os Metadados de Recurso Protegido exatos (e traz invalid_token apenas quando um Bearer enviado foi recusado). Recomece por esse metadado; nunca cole o segredo estático do perfil nessa URL.
• A URL OAuth retorna 403: o Bearer é válido, mas a chamada pediu uma ferramenta de escrita sem o escopo mcp:write. Peça esse escopo no consentimento e confirme que o perfil não é somente leitura; um mcp:write também não libera ferramentas fora do perfil.
• A URL OAuth retorna 413: a requisição JSON-RPC ou a resposta ultrapassou 1 MiB. Reduza a carga ou use paginação. Uma requisição grande é recusada antes da execução; uma resposta grande só é medida após a operação terminar, então não repita uma escrita cegamente — confira o recurso ou a auditoria primeiro.
• Um cliente OAuth ainda não conclui o consentimento: registre cliente e versão, URI de redirecionamento, resultado do discovery e código de erro seguro em um teste controlado. Não contorne PKCE, vínculo ao recurso ou consentimento no navegador; compatibilidade só existe após prova ponta a ponta.
• Toolset acinzentado com selo “bloqueado”: o Super Admin não liberou esse toolset no teto global. Só ele pode liberar.
• Perdi o segredo do perfil: gere outro com Rotacionar token no perfil — o anterior é invalidado na hora.
• Perdi o token do Maestro: gere outro com Rotacionar token no card do Maestro — o anterior é invalidado na hora.
• A descoberta (“Descobrir”) falha com 401: quase sempre a autenticação está em nenhuma. Escolha bearer e aponte o segredo com a chave de API do provedor (Sentry usa header; Notion usa OAuth).
• A descoberta falha por outro motivo: confira URL, transporte (Streamable HTTP ou SSE) e credenciais; salve o Robô antes se a autenticação usa um segredo armazenado; endereços privados/internos são recusados pela proteção SSRF.
• O botão Conectar não abre nada: o navegador bloqueou o pop-up — libere pop-ups para o domínio e clique de novo.
• Conectado, mas a ferramenta falha depois de um tempo: a autorização do provedor expirou — Desconecte e Conecte de novo.
• Ferramenta externa falha em uso: o erro volta como texto para o agente (que se autocorrige) e nunca derruba o turno.
• ask_<departamento> responde “disabled”: o departamento está desativado para a conta — ative-o na tela do Cérebro (Account Brain).

Veja também

• SDK, API REST e MCP de Dashboard Apps
• Referência da API (Swagger/OpenAPI)
• Tokens REST, webhooks e autenticação
• Robôs e canal de API