MCP: conectar assistentes de IA
O NearOne Trust tem um servidor MCP (Model Context Protocol). MCP é um protocolo aberto que permite a um assistente de IA, como o Claude, descobrir e usar ferramentas de um sistema externo. Com ele, uma pessoa da equipe pode pedir em linguagem natural:
"Quais casos da empresa Matriz estão com prazo vencido?" "Mostre o que falta para publicar o canal de denúncias da filial." "Cadastre a empresa de CNPJ 00.000.000/0001-00 e ligue ao canal de denúncias."
e o assistente consulta ou age no NearOne Trust em nome dela, com as mesmas regras que valem na tela.
Cada conexão representa uma pessoa. O assistente só pode o que essa pessoa marcou na autorização e ainda pode fazer no momento de cada ação. Se o papel dela perder um acesso, o pedido seguinte do assistente já vale menos. Casos protegidos continuam invisíveis para quem não tem concessão. Nada é "liberado para a IA" que não esteja liberado para a pessoa.
Para quem é
| Perfil | O que ganha |
|---|---|
| Equipe de compliance e ética | Triagem, consultas e rotinas do dia a dia por conversa, sem navegar por várias telas. |
| Administração da organização | Implantação mais rápida: criar canais, cadastrar empresas, montar automações e conferir pendências. |
| Desenvolvedores | Um servidor MCP padrão (Streamable HTTP + OAuth 2.1 com PKCE e registro dinâmico) para clientes próprios. |
Antes de começar: dois interruptores
O MCP precisa estar ligado em dois lugares. Os dois existem para que nenhuma conexão aconteça sem decisão explícita.
| Onde | Quem muda | Padrão | Efeito |
|---|---|---|---|
| Organização › MCP (Permitir conexões MCP) | Quem tem permissão para alterar a organização | Ligado | Desligar corta todas as conexões de IA da organização no pedido seguinte. |
| Configurações › Conexões com IA (Permitir MCP na minha conta) | A própria pessoa | Desligado | Sem isso, a pessoa não consegue autorizar nenhum aplicativo. |

Na mesma tela (Organização › MCP) também ficam:
- Nome do servidor (até 120 caracteres): como o assistente vai apresentar a conexão.
- Instruções para o cliente (opcional, até 4.000 caracteres): contexto adicional que o assistente recebe ao conectar, como propósito, limites e convenções da sua organização. Um guia fixo do NearOne Trust vem antes dessas instruções. As instruções não mudam permissões nem criam ferramentas: são só orientação.

Conectar passo a passo (pelo painel)
O jeito mais fácil é o guia Conectar sua IA, no rodapé do menu lateral (ou pelo botão Abrir o passo a passo em Configurações › Conexões com IA). Ele mostra o estado dos dois interruptores e deixa você ligá-los ali mesmo, copia o endereço certo e detecta sozinho quando a conexão foi autorizada.

Os seis passos do guia:
- Confira se o MCP está ligado — na sua conta e na organização.
- Copie o endereço do servidor — o endereço do servidor MCP é:
https://api.trust.nearone.com.br/mcp
- Adicione o NearOne Trust ao seu assistente — veja as instruções por assistente abaixo.
- Autorize no NearOne Trust — o assistente abre a tela de autorização; você escolhe o que ele pode fazer.
- Teste a conexão — o guia sugere perguntas como "Quem sou eu no NearOne Trust?" e mostra a conexão aparecer sozinha.
- Segurança e como revogar — onde ver e cortar a conexão.
Claude (site e aplicativo)
- Abra o Claude e entre na sua conta.
- Abra as Configurações e procure Conectores (Connectors).
- Escolha Adicionar conector personalizado (Add custom connector).
- Dê um nome, por exemplo NearOne Trust, e cole
https://api.trust.nearone.com.br/mcpno campo do endereço do servidor. - Clique em Conectar. O Claude abre a tela de autorização do NearOne Trust. Se pedir, entre na sua conta primeiro.
Os nomes e a posição dos botões mudam conforme a versão e o plano do Claude. Em alguns planos, quem administra a conta do Claude precisa liberar conectores personalizados antes.
Claude Code (terminal)
claude mcp add --transport http trust https://api.trust.nearone.com.br/mcp
Depois, dentro do Claude Code, execute /mcp, escolha trust na lista e autorize no navegador que abrir.
Outros assistentes (ChatGPT e demais clientes MCP)
Qualquer assistente que aceite servidores MCP remotos com autorização OAuth funciona da mesma forma. Procure na configuração dele por "MCP", "conectores" ou "ferramentas externas" e informe o endereço https://api.trust.nearone.com.br/mcp. O próprio assistente descobre o servidor de autorização, registra-se e abre a tela de consentimento. Não é preciso criar chave de API nem copiar token.
Um assistente que roda na nuvem (como o Claude no site) só alcança endereços públicos. Por isso o guia avisa quando o endereço é local ou de rede interna.
A tela de autorização (consentimento)
Quando o assistente pede acesso, o NearOne Trust abre Autorizar aplicativo. É uma tela do próprio NearOne Trust, com a sua sessão: o assistente nunca vê a sua senha.
- Tudo o que você pode delegar já vem marcado. Desmarque o que não quiser. O que você desmarcar não existe para aquela conexão.
- As permissões aparecem agrupadas, cada grupo com uma frase que diz o que o assistente recebe ou pode fazer:
| Grupo | O que significa |
|---|---|
| Ler casos | O cliente recebe o texto dos casos que você pode abrir. |
| Revelar identidade | O cliente recebe a identidade de quem pediu sigilo. Cada consulta fica registrada, com motivo, e o dado passa pelo serviço de IA que você conectou. |
| Exportar dossiê | O cliente pode obter o pacote do caso, com evidências limpas. Identidade só se você marcar também. |
| Descartar casos | Apaga o conteúdo de caso encerrado e não volta. Só se você for autoridade de concessão. |
| Avisos e convites | Envia e-mail às pessoas escolhidas. E-mail de fora só recebe depois de confirmar o link. |
| Canais e categorias | Publicar canal e, se marcado por completo, ligar ou desligar categoria para a organização inteira. |
| Outros acessos | O cliente usa os demais acessos marcados do mesmo jeito que você usa na tela, dentro do que você pode fazer. |
- Desmarcando tudo, o assistente só consegue confirmar quem você é e em qual organização está.
- Clique em Autorizar para concluir ou Cancelar para desistir.
Revelar identidade, Exportar dossiê e Descartar casos só podem ser delegados se você digitar, na tela de autorização, o código de 6 dígitos do aplicativo autenticador (TOTP). Outros segundos fatores não servem para isso; se você ainda não cadastrou um autenticador, a tela avisa e esses grupos ficam bloqueados. Esse código vale por 24 horas para ações sensíveis; depois disso o assistente avisa que é preciso autorizar de novo. O código é sempre digitado por você na tela do NearOne Trust, nunca no chat.
O que o assistente consegue fazer
O servidor expõe 40 ferramentas. Cada uma agrupa uma ou mais ações (241 ao todo, na versão atual). O assistente só vê, em tools/list, as ações que a conexão permite: se você não marcou ou não tem a permissão, a ação simplesmente não aparece.
Casos
| Ferramenta | O que faz |
|---|---|
cases | Lê casos que você pode abrir: listar (com filtros por empresa, fase, prioridade, sem responsável, aguardando resposta, meus), ficha, mensagens, histórico, transições disponíveis, candidatos a responsável, contadores, minhas atividades, calendário, quadros, lembretes, relações, anexos (link de 15 minutos), evidências, prazo e análise. |
case_actions | Muda o estado de um caso: executar transição, atribuir responsável, triagem (inclui a prioridade), corrigir empresa, nota interna, mensagem a quem relatou, cancelar, marcar como duplicado, reabrir, decidir pedido de reabertura, corrigir campos, prorrogar prazo e gravar a análise. |
case_work | Tarefas, entregas, lembretes, relações entre casos e remoção de anexo com motivo. |
case_protection | Revisar e aplicar proteção, conceder e revogar acesso nominal a caso protegido, registrar e liberar impedimentos por conflito de interesse. |
case_vault | Consulta o cofre do caso sem revelar identidade: modo de identificação, canal, empresa, estado das evidências e log de acessos. |
case_identity_reveal | Sensível. Revela a identidade de quem fez um relato identificado ou confidencial. |
case_export | Sensível. Prepara o dossiê do caso (ZIP com caso, mensagens, histórico, evidências limpas, log de acesso e manifesto assinado). |
retention | Política de retenção, casos candidatos ao descarte e, como ações sensíveis, retenção legal (hold) e descarte. |
triage_ai | Triagem assistida por IA: configuração, pedir triagem de um caso, ver a sugestão, desfazer e registrar a decisão da equipe. |
sla | Políticas de prazo, prazo por categoria, feriados, relógio do caso e prorrogação justificada. |
Canal de denúncias e ouvidoria
| Ferramenta | O que faz |
|---|---|
channels | Listar, ver, conferir prontidão, criar (vazio ou a partir de modelo), alterar, definir empresas e categorias, publicar, pausar ou desativar canais. |
channel_setup | Monta um canal de ponta a ponta: garante o canal, liga empresas, ajusta categorias e tenta publicar. |
categories | Categorias de denúncia: tirar ou pôr num canal, ou ligar e desligar na organização inteira. |
authorities | Concedente e contingência independente (quem libera acesso a casos protegidos) e recebedores. |
automations | Automações do canal: listar, ver, salvar rascunho, testar sobre um caso (sem enviar nada), publicar, pausar, retomar, apagar. |
notice_addresses | E-mails externos que recebem avisos (com confirmação por link). |
company_notice_set | Garante o aviso por e-mail de relatos de uma empresa. |
integrations | Slack (link de instalação, canais, teste, desconectar), Microsoft Teams (cadastrar, testar, remover) e a opção de metadados em avisos externos. |
poster | Gera o cartaz em PDF (A4, QR e link) de um canal. |
reports | Indicadores agregados do período (com grupos pequenos suprimidos) e panorama de prazos. Nunca abre um caso. |
prevention | Ações preventivas contra riscos psicossociais. |
org_overview | Prontidão da organização para receber denúncias. |
Empresas, equipe e organização
| Ferramenta | O que faz |
|---|---|
companies / company_ensure | Empresas: listar, ver, consultar CNPJ na Receita, cadastrar, atualizar, remover; ou garantir uma empresa pelo CNPJ sem duplicar. |
company_contacts | Contatos de empresas, com e-mail, telefone ou WhatsApp. |
company_groups | Grupos de empresas (conglomerados). |
company_extras | Por empresa: canais que a atendem e quem recebe os avisos. |
members | Listar, convidar, reenviar convite, mudar papéis e escopo, bloquear, desbloquear e remover membros. |
member_groups | Grupos de membros e seus integrantes. |
roles | Papéis e permissões. Só concede permissões que a própria conexão tem. |
organization | Dados da organização e política de segurança. |
tags | Etiquetas de empresas e de casos. |
files | Arquivos da organização (logos e similares), com link de download de 15 minutos. |
inbox | A caixa de entrada da própria pessoa. |
audit | Trilha de auditoria (somente leitura). |
webhooks | Webhooks de saída: listar, criar, alterar, pausar, retomar, revogar, trocar segredo, testar, ver e reenviar entregas. |
Fluxos e configuração do motor de casos
| Ferramenta | O que faz |
|---|---|
workflows | Fluxos de trabalho: modelos, versões, rascunho, validação e simulação. |
request_categories / request_types | Categorias e tipos de solicitação e seus rascunhos. |
whoami | Mostra a pessoa da conexão, o teto de permissões, o escopo de empresas e até quando o segundo fator vale para ações sensíveis. |
- Publicar uma nova versão de fluxo ou de tipo de solicitação: o assistente prepara e valida o rascunho, e uma pessoa publica no painel.
- Mexer em senha, segundo fator, sessões, chaves de API, chaves de provedores de IA ou no interruptor do MCP da organização.
- Tornar alguém titular ou gestor de conta, ou transferir a titularidade.
- Usar o protocolo de quem relatou para achar um caso: casos são identificados pelo código de 4 caracteres.
Segurança
Delegação com teto
A cada chamada, o servidor calcula o que vale agora: as permissões que você tem hoje, somadas apenas ao que você marcou no consentimento. Em termos práticos, é a interseção das duas coisas. Remover alguém de um papel, bloquear o membro ou desligar o MCP tem efeito imediato no pedido seguinte.
Rastreabilidade
- Cada chamada de ferramenta gera uma linha de auditoria (
mcp.tool_call) com a ferramenta, a ação, o resultado e os identificadores envolvidos. - Os registros de acesso ao cofre e de descarte guardam também qual conexão de IA (a chave da conexão) executou a ação, além da pessoa.
- Ações sensíveis exigem que o assistente informe a frase do seu pedido e um motivo; o descarte exige também que você confirme o código do caso.
Conteúdo de terceiros não vira ordem
Textos de relatos, mensagens e nomes de anexos chegam ao assistente marcados como não confiáveis (untrusted). O guia que o servidor entrega ao assistente diz explicitamente que esse conteúdo é dado, nunca instrução, mesmo que o texto do relato "peça" para ignorar regras.
Confirmações e segredos
Ações destrutivas ou que geram segredo exigem confirm=true, ou seja, o assistente deve pedir sua confirmação antes. Entre elas: enviar mensagem a quem relatou, cancelar ou marcar caso como duplicado, proteger caso, remover empresas, contatos, grupos, etiquetas e papéis, bloquear ou remover membros, trocar as permissões de um papel, alterar a organização e a política de segurança, criar ou revogar webhook e trocar o segredo dele, mudar o estado de um canal e ligar ou desligar categorias. O confirm é um freio para o assistente, não um controle de segurança: quem decide é sempre a permissão. Segredos de webhook e de integração passam uma única vez pelo chat.
Limites de uso
| Limite | Valor |
|---|---|
| Chamadas ao MCP por pessoa | 60 por minuto |
| Revelações de identidade por pessoa | 30 por hora |
| Exportações de dossiê por pessoa | 10 por hora |
| Descartes por pessoa | 5 por hora |
| Tamanho máximo de um resultado | cerca de 900 KB |
Arquivos (ZIP, PDF, anexos) via resources/read | até 8 MB, link válido por 15 minutos |
Revogar uma conexão
Em Configurações › Conexões com IA, na lista Conexões autorizadas, clique em Revogar ao lado da conexão e confirme em Revogar conexão. O assistente perde o acesso na hora. Para reconectar, adicione o conector de novo e autorize outra vez.
- Marque só o necessário. Uma conexão para "consultas" não precisa de Revelar identidade.
- Use instruções da organização para registrar convenções ("use sempre o código do caso", "não envie mensagens a quem relatou sem aprovação do comitê").
- Revise periodicamente as conexões autorizadas e revogue as que não usa.
- Lembre que, com Ler casos marcado, o texto dos relatos passa pelo serviço de IA que você conectou. Use assistentes aprovados pela política de dados da sua empresa.
Detalhes técnicos (para quem integra um cliente próprio)
O servidor segue a especificação MCP com transporte Streamable HTTP e autorização OAuth 2.1 para clientes públicos.
Descoberta e registro
| Endpoint | Função |
|---|---|
GET /.well-known/oauth-protected-resource | Indica o recurso (/mcp) e o servidor de autorização. Escopo suportado: mcp. |
GET /.well-known/oauth-authorization-server | Metadados: authorization_endpoint, token_endpoint, registration_endpoint, revocation_endpoint; response_types_supported: ["code"]; grant_types_supported: ["authorization_code", "refresh_token"]; code_challenge_methods_supported: ["S256"]; token_endpoint_auth_methods_supported: ["none"]. |
POST /oauth/register | Registro dinâmico de cliente. Envie client_name e redirect_uris (pelo menos uma, http:// ou https://). Só clientes públicos (token_endpoint_auth_method: "none"). Responde 201 com o client_id. |
GET /oauth/authorize | Leva a pessoa à tela de consentimento do painel. PKCE com S256 é obrigatório. |
POST /oauth/token | Troca o code (válido por 10 minutos, uso único) mais o code_verifier por tokens; ou renova com grant_type=refresh_token. |
POST /oauth/revoke | Revoga um refresh_token. |
A resposta do token:
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "Yx3..."
}
O access_token vale 1 hora; o refresh_token, 30 dias. Um token emitido para MCP só funciona em POST /mcp: qualquer outra rota da API responde 403.
Chamadas JSON-RPC
POST /mcp recebe uma mensagem JSON-RPC 2.0 por requisição e responde em JSON. Versão do protocolo anunciada: 2025-03-26. Métodos suportados: initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read e notificações (respondidas com 202).
curl https://api.trust.nearone.com.br/mcp \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"cases","arguments":{"action":"list","phase":"in_progress"}}}'
- Cada ferramenta recebe o argumento
actioncom o nome da ação (ferramentas de uma ação só dispensam o campo). OinputSchemapublicado emtools/listdescreve os demais argumentos e recusa campos desconhecidos. - Ações de escrita levam
request_nonce(um UUID novo por pedido). Repetir o mesmo nonce com o mesmo conteúdo devolve o recibo da primeira execução em vez de executar de novo. - Erros de ferramenta voltam como resultado com
isError: truee um objeto comcode,message(em português),retryable,next_actionsedetails. Seretryableforfalse, não repita em laço. - Se a organização desligou o MCP, a resposta é
403commcp_org_disabled. Se o catálogo ganhou ações que o consentimento não viu, o servidor pede nova autorização (mcp_reauthorization_required).
Referência gerada: Mcp Http, Register Client, Authorize, Token, Revoke e configuração do MCP da organização.
Problemas comuns
| Situação | O que fazer |
|---|---|
| Não encontro o botão para adicionar um conector | O nome e o lugar mudam conforme a versão e o plano do assistente. Em alguns planos, só quem administra a conta do assistente libera conectores personalizados. |
| A tela de autorização diz que o MCP está desligado | Ligue na sua conta (Configurações › Conexões com IA) e confirme com o administrador que o MCP da organização está ligado. |
| Uma ação responde "sem permissão" | A IA só pode o que você pode. Peça a quem administra os papéis para incluir a permissão; no pedido seguinte ela já vale. |
| Uma ação sensível foi recusada | Autorize de novo digitando o código do aplicativo autenticador (vale 24 horas) e confira se marcou o grupo correspondente. |
| A conexão foi revogada ou expirou | Conecte de novo pelo mesmo conector e autorize outra vez. |
Veja também: Segurança e privacidade e Webhooks.