## 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:

```bash
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:

```json
{
  "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):

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

```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:

```bash
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**:

```bash
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:

```bash
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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

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.

| Cliente | Pré-requisitos externos | Passos do teste | Revogação | Estado |
|---|---|---|---|---|
| **Claude.ai — Conector personalizado** | Plano Claude com conectores personalizados (Free: um); em Team/Enterprise, Owner/Primary Owner cadastra antes; issuer HTTPS público alcançável pela nuvem do Claude e preflight aprovado | Usar a URL OAuth exata, manter Advanced settings opcional/sem segredo e concluir browser/PKCE/consentimento | Revogar em **Configurações → Perfil → Conexões MCP** e confirmar que a próxima chamada falha | ⏳ não validado |
| **Claude Desktop** | Claude Desktop atualizado e conta com conectores personalizados; o servidor também precisa estar alcançável pela nuvem do Claude, não apenas pela máquina local | Configurar somente a URL OAuth exata e registrar versão, sistema e callback/erro seguro | Revogar o mesmo grant e testar nova chamada | ⏳ não validado |
| **Codex** | Organização/produto elegível para conexão MCP remota e método atual de conexão disponível | Adicionar somente a URL OAuth exata no fluxo atual do produto; não usar segredo Bearer como segredo de cliente | Revogar o grant e confirmar negação posterior | ⏳ não validado |
| **ChatGPT / GPT Platform** | Plano/workspace elegível, administrador ou Developer Mode quando aplicável, autorização explícita para o teste | Usar o fluxo de connector/app efetivamente disponível, a URL OAuth exata e o consentimento no navegador | Revogar o grant e confirmar negação posterior | ⏳ não validado |

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](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-pt-br)
- [Referência da API (Swagger/OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-pt-br)
- [Tokens REST, webhooks e autenticação](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-pt-br)
- [Robôs e canal de API](/hc/ajuda/articles/api-developers-agent-bots-and-api-channel-pt-br)