Pular para o conteúdo principal

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.

O princípio: a IA age como você, nunca além de você

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 é​

PerfilO que ganha
Equipe de compliance e éticaTriagem, consultas e rotinas do dia a dia por conversa, sem navegar por várias telas.
Administração da organizaçãoImplantação mais rápida: criar canais, cadastrar empresas, montar automações e conferir pendências.
DesenvolvedoresUm 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.

OndeQuem mudaPadrãoEfeito
Organização › MCP (Permitir conexões MCP)Quem tem permissão para alterar a organizaçãoLigadoDesligar 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 pessoaDesligadoSem isso, a pessoa não consegue autorizar nenhum aplicativo.
Tela Organização › MCP, bloco Servidor da organização com o estado Disponível, o interruptor Permitir conexões MCP, o campo Nome do servidor e a seção Instruções para o cliente; à direita, o painel Como a conexão funciona.
Em Organização › MCP, o administrador liga ou desliga o servidor (Permitir conexões MCP), define o Nome do servidor e escreve as Instruções para o cliente. Nada vale antes de Salvar alterações. Dados fictícios da organização de demonstração.

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.
Configurações, aba Conexões com IA: interruptor Permitir MCP na minha conta, atalho para o passo a passo e a lista Conexões autorizadas, vazia.
Em Configurações › Conexões com IA cada pessoa liga o MCP na própria conta e vê (e revoga) as conexões que autorizou. Dados fictícios da organização de demonstraçã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.

Guia Conectar sua IA com os seis passos: conferir o MCP, copiar o endereço, adicionar ao assistente, autorizar, testar e segurança.
O guia Conectar sua IA leva do início ao teste em seis passos e mostra como revogar depois. Dados fictícios da organização de demonstração.

Os seis passos do guia:

  1. Confira se o MCP está ligado — na sua conta e na organização.
  2. Copie o endereço do servidor — o endereço do servidor MCP é:
    https://api.trust.nearone.com.br/mcp
  3. Adicione o NearOne Trust ao seu assistente — veja as instruções por assistente abaixo.
  4. Autorize no NearOne Trust — o assistente abre a tela de autorização; você escolhe o que ele pode fazer.
  5. Teste a conexão — o guia sugere perguntas como "Quem sou eu no NearOne Trust?" e mostra a conexão aparecer sozinha.
  6. Segurança e como revogar — onde ver e cortar a conexão.

Claude (site e aplicativo)​

  1. Abra o Claude e entre na sua conta.
  2. Abra as Configurações e procure Conectores (Connectors).
  3. Escolha Adicionar conector personalizado (Add custom connector).
  4. Dê um nome, por exemplo NearOne Trust, e cole https://api.trust.nearone.com.br/mcp no campo do endereço do servidor.
  5. Clique em Conectar. O Claude abre a tela de autorização do NearOne Trust. Se pedir, entre na sua conta primeiro.
observação

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.

Endereços locais não servem para assistentes na nuvem

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:
GrupoO que significa
Ler casosO cliente recebe o texto dos casos que você pode abrir.
Revelar identidadeO 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 casosApaga o conteúdo de caso encerrado e não volta. Só se você for autoridade de concessão.
Avisos e convitesEnvia e-mail às pessoas escolhidas. E-mail de fora só recebe depois de confirmar o link.
Canais e categoriasPublicar canal e, se marcado por completo, ligar ou desligar categoria para a organização inteira.
Outros acessosO 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.
Ações sensíveis pedem o aplicativo autenticador

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​

FerramentaO que faz
casesLê 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_actionsMuda 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_workTarefas, entregas, lembretes, relações entre casos e remoção de anexo com motivo.
case_protectionRevisar e aplicar proteção, conceder e revogar acesso nominal a caso protegido, registrar e liberar impedimentos por conflito de interesse.
case_vaultConsulta o cofre do caso sem revelar identidade: modo de identificação, canal, empresa, estado das evidências e log de acessos.
case_identity_revealSensível. Revela a identidade de quem fez um relato identificado ou confidencial.
case_exportSensível. Prepara o dossiê do caso (ZIP com caso, mensagens, histórico, evidências limpas, log de acesso e manifesto assinado).
retentionPolítica de retenção, casos candidatos ao descarte e, como ações sensíveis, retenção legal (hold) e descarte.
triage_aiTriagem assistida por IA: configuração, pedir triagem de um caso, ver a sugestão, desfazer e registrar a decisão da equipe.
slaPolíticas de prazo, prazo por categoria, feriados, relógio do caso e prorrogação justificada.

Canal de denúncias e ouvidoria​

FerramentaO que faz
channelsListar, ver, conferir prontidão, criar (vazio ou a partir de modelo), alterar, definir empresas e categorias, publicar, pausar ou desativar canais.
channel_setupMonta um canal de ponta a ponta: garante o canal, liga empresas, ajusta categorias e tenta publicar.
categoriesCategorias de denúncia: tirar ou pôr num canal, ou ligar e desligar na organização inteira.
authoritiesConcedente e contingência independente (quem libera acesso a casos protegidos) e recebedores.
automationsAutomações do canal: listar, ver, salvar rascunho, testar sobre um caso (sem enviar nada), publicar, pausar, retomar, apagar.
notice_addressesE-mails externos que recebem avisos (com confirmação por link).
company_notice_setGarante o aviso por e-mail de relatos de uma empresa.
integrationsSlack (link de instalação, canais, teste, desconectar), Microsoft Teams (cadastrar, testar, remover) e a opção de metadados em avisos externos.
posterGera o cartaz em PDF (A4, QR e link) de um canal.
reportsIndicadores agregados do período (com grupos pequenos suprimidos) e panorama de prazos. Nunca abre um caso.
preventionAções preventivas contra riscos psicossociais.
org_overviewProntidão da organização para receber denúncias.

Empresas, equipe e organização​

FerramentaO que faz
companies / company_ensureEmpresas: listar, ver, consultar CNPJ na Receita, cadastrar, atualizar, remover; ou garantir uma empresa pelo CNPJ sem duplicar.
company_contactsContatos de empresas, com e-mail, telefone ou WhatsApp.
company_groupsGrupos de empresas (conglomerados).
company_extrasPor empresa: canais que a atendem e quem recebe os avisos.
membersListar, convidar, reenviar convite, mudar papéis e escopo, bloquear, desbloquear e remover membros.
member_groupsGrupos de membros e seus integrantes.
rolesPapéis e permissões. Só concede permissões que a própria conexão tem.
organizationDados da organização e política de segurança.
tagsEtiquetas de empresas e de casos.
filesArquivos da organização (logos e similares), com link de download de 15 minutos.
inboxA caixa de entrada da própria pessoa.
auditTrilha de auditoria (somente leitura).
webhooksWebhooks de saída: listar, criar, alterar, pausar, retomar, revogar, trocar segredo, testar, ver e reenviar entregas.

Fluxos e configuração do motor de casos​

FerramentaO que faz
workflowsFluxos de trabalho: modelos, versões, rascunho, validação e simulação.
request_categories / request_typesCategorias e tipos de solicitação e seus rascunhos.
whoamiMostra 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.
O que o assistente não faz, por desenho
  • 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​

LimiteValor
Chamadas ao MCP por pessoa60 por minuto
Revelações de identidade por pessoa30 por hora
Exportações de dossiê por pessoa10 por hora
Descartes por pessoa5 por hora
Tamanho máximo de um resultadocerca de 900 KB
Arquivos (ZIP, PDF, anexos) via resources/readaté 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.

Boas práticas
  • 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​

EndpointFunção
GET /.well-known/oauth-protected-resourceIndica o recurso (/mcp) e o servidor de autorização. Escopo suportado: mcp.
GET /.well-known/oauth-authorization-serverMetadados: 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/registerRegistro 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/authorizeLeva a pessoa à tela de consentimento do painel. PKCE com S256 é obrigatório.
POST /oauth/tokenTroca o code (válido por 10 minutos, uso único) mais o code_verifier por tokens; ou renova com grant_type=refresh_token.
POST /oauth/revokeRevoga 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 action com o nome da ação (ferramentas de uma ação só dispensam o campo). O inputSchema publicado em tools/list descreve 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: true e um objeto com code, message (em português), retryable, next_actions e details. Se retryable for false, não repita em laço.
  • Se a organização desligou o MCP, a resposta é 403 com mcp_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çãoO que fazer
Não encontro o botão para adicionar um conectorO 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á desligadoLigue 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 recusadaAutorize 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 expirouConecte de novo pelo mesmo conector e autorize outra vez.

Veja também: Segurança e privacidade e Webhooks.