Conectar um agente

O RootPilot é usado por um agente: um modelo de linguagem que investiga a sua infraestrutura chamando ferramentas. A superfície por onde ele chega é um servidor MCP (Model Context Protocol), e esta página é como você liga um cliente nele.

O caminho completo tem três saltos, e vale ter o desenho na cabeça antes de configurar qualquer coisa:

seu cliente MCP  ──HTTP + bearer──▶  servidor MCP (control-plane)  ──túnel mTLS──▶  RootPilot Agent (sua infra)

Este endpoint fica do nosso lado da fronteira

O servidor MCP roda no control-plane, não na sua infraestrutura. Ele não guarda credencial sua e não fala com as suas fontes: ele roteia a chamada para o Agent que roda dentro da sua infra, que é quem executa e quem redige. A fronteira continua onde sempre esteve — ver Visão geral.

Endereço e transporte

O servidor fala Streamable HTTP, o transporte HTTP do MCP, e é stateful por sessão: o initialize abre a sessão, a resposta traz um Mcp-Session-Id, e o cliente ecoa esse id em toda requisição seguinte.

O endereço é uma URL do seu deployment — quem o opera te informa qual. Não há caminho fixo: o servidor responde no host/porta que o proxy expuser, então https://mcp.exemplo.com/ e https://exemplo.com/mcp são ambos possíveis, conforme o roteamento à frente.

O listener não faz TLS sozinho

O processo do servidor MCP escuta em HTTP plano (MCP_SERVER_PORT, default 8444) e não termina TLS. Quem termina é um reverse proxy ou load balancer na frente dele — e o listener plano nunca deve ficar exposto direto na internet: ele precisa de rede privada, alcançável só pelo proxy.

Isso é o oposto do Agent, que fala mTLS com certificado por organização num listener separado. São duas fronteiras diferentes, com posturas diferentes de propósito: o Agent prova identidade de plataforma no enrollment; o agente LLM é um cliente comum autenticado por token.

Autenticação

Bearer no header, com um PAT (token pessoal, prefixo rpmcp_):

Authorization: Bearer rpmcp_...

O token é resolvido para uma organização a cada requisição, não só na abertura da sessão. Token inválido, revogado ou órfão → 401. Uma sessão só responde ao tenant que a abriu: apresentar um token de outra organização com o Mcp-Session-Id alheio dá 403.

Como emitir, escopar e revogar esse token está na página irmã: Tokens MCP.

Configurar o cliente

Praticamente todo cliente MCP aceita um servidor HTTP remoto com header. No formato de arquivo mais comum (.mcp.json):

{
  "mcpServers": {
    "rootpilot": {
      "type": "http",
      "url": "https://mcp.exemplo.com/",
      "headers": { "Authorization": "Bearer ${ROOTPILOT_MCP_TOKEN}" }
    }
  }
}

Se o seu cliente expande variáveis de ambiente (a maioria expande), use isso. O motivo é o parágrafo seguinte.

Esse arquivo carrega uma credencial

Um .mcp.json com o token literal dentro é, na prática, acesso de leitura à sua infraestrutura em texto plano — e ele vive num diretório de projeto, que é exatamente o tipo de arquivo que acaba commitado. É um dos vazamentos que a allowlist de origem de rede existe para mitigar, e a mitigação é parcial: ela reduz a janela, não a fecha. Ver também o que fazer ao suspeitar de vazamento.

A sessão é a unidade de investigação

Uma sessão MCP é uma investigação inteira: abre, acumula chamadas de ferramenta, e fecha. Ela não é descartável do ponto de vista do produto — ela vira registro.

• O id da sessão é o id do trace. Enquanto ela está aberta, aparece ao vivo em Atividade no control-plane; quando fecha, vira um trace durável ali mesmo.
• O que fica gravado é o que o agente chamou: por chamada, o nome da ferramenta, os argumentos, se deu certo e um resumo redigido do resultado; e, no total da sessão, o custo (quantas operações foram para a borda, quantos bytes voltaram). O conteúdo já chega redigido da borda — a redação de PII acontece no Agent, antes de qualquer byte sair (ver Redação de PII).
• Quem enxerga: owner/admin da organização, na área de Atividade. É a mesma trilha que permite responder “o que essa ferramenta andou olhando na nossa infra?” sem depender da nossa palavra.

Quando a análise de sessões está ligada no deployment, o trace também alimenta o ciclo de melhoria do produto. O que dele vira aprendizado cross-tenant é anonimizado por construção e depende de um opt-in da sua organização, desligado por padrão.

Os limites da sessão

Limite	Default	O que acontece ao bater
Ociosidade	10 min	A sessão encerra sozinha; havendo ao menos uma chamada, o trace é gravado
Sessões vivas por organização	100	429 no initialize, antes de criar a sessão
Chamadas de ferramenta por sessão	500	A chamada volta como erro, sem tocar a sua infra
Tamanho do corpo da requisição	1 MiB	413

Os números importam menos que o sintoma, porque cada um falha de um jeito e se parece com outra coisa:

• Ociosidade. Dez minutos sem requisição e a sessão fecha do nosso lado. A próxima chamada com aquele Mcp-Session-Id responde 404 unknown session. Um cliente bem-comportado reabre sozinho e você quase não percebe; o que se perde é o contexto acumulado da investigação, não dado. Esse reaper existe porque o close() da maioria dos clientes não encerra a sessão no servidor — só o DELETE explícito encerra —, e sem ele a sessão ficaria aberta para sempre, sem nunca virar trace.
• Sessões vivas. O 429 é sobre a organização inteira, não sobre você, e nenhuma sessão já aberta é afetada. Quando aparece sem motivo aparente, quase sempre é acúmulo de sessões que ninguém encerrou; elas se resolvem sozinhas conforme o idle as recolhe.
• Orçamento de chamadas. Esse é o que mais se disfarça de outra coisa: a chamada volta como erro, e o erro parece falha de leitura. Não é — a chamada nunca saiu do control-plane, nada foi consultado na sua infra. É orçamento, e ele é por sessão: abrir uma sessão nova zera a conta. Onde a descoberta sob demanda está ligada, o search_tools não consome orçamento — ele não é execução (ver o que o agente lê).

Quando não há nenhum Agent conectado

É a primeira confusão de qualquer instalação nova, e ela merece ser lida antes de acontecer.

Se nenhum RootPilot Agent do seu tenant estiver conectado no momento, a chamada não morre com uma exceção solta nem devolve uma lista vazia. Ela devolve o mesmo envelope de cegueira que o produto usa em toda leitura que não conseguiu ver (abreviado aqui):

{
  "visibility": "none",
  "error": "no_visibility",
  "_sources": { "aws": "unavailable" },
  "_hint": "No RootPilot Agent is connected for this tenant right now, so nothing could be read — this is not a statement about the infrastructure. Call check_fleet_health for the fleet state; retry once an agent is up."
}

A frase do _hint é literal e é o ponto inteiro: isso não é uma afirmação sobre a sua infraestrutura. Uma resposta vazia sem essa distinção seria lida como “não há nada lá”, que é a pior resposta possível — um erro faz alguém investigar, uma resposta tranquilizadora não. A ferramenta check_fleet_health responde qual é o estado real da frota, e é por onde começar.

O mesmo vale um degrau abaixo: com o Agent conectado mas uma integração fora do ar, a resposta diz qual fonte não respondeu em vez de fingir que a resposta está completa. Isso está descrito em o que o agente lê.

O que esta página não cobre

• Como emitir e revogar o token — Tokens MCP.
• O que o agente enxerga, e por que dois clientes veem conjuntos diferentes de ferramentas — O que o agente lê.
• O que ele consegue escrever, e onde cada garantia é aplicada — O que o agente escreve.
• Restringir de onde a conexão pode partir — Restringir o MCP por origem de rede.