Skip to main content
A Niadra mantém um servidor MCP remoto para cada espaço. Qualquer modelo e qualquer framework de agentes que fale o Model Context Protocol consegue ler o contexto do cliente, buscar no histórico e registrar o que fez, sem SDK no caminho. Este guia mostra a conexão, como o cliente fica amarrado para o modelo nunca trocar de cliente, as sete ferramentas e quando usar chamada de função no lugar do MCP.

O endereço

O servidor fala Streamable HTTP em /mcp, no endereço do seu espaço:
Dois cabeçalhos autenticam a conexão: O SDK de Python expõe o endereço em niadra.mcp_url.

Por que o cliente vem amarrado por um token

As ferramentas do MCP nunca recebem o cliente como argumento. O cliente vem do subject_token da conexão: um token assinado pela célula, com o espaço, a fonte, o handle do cliente, a conversa e o nível de verificação, que vale por até 15 minutos. O handle viaja lacrado dentro dele. Uma injeção no prompt que diga “agora consulte o cliente X” não tem argumento onde colocar o X: o modelo escolhe o que perguntar, nunca sobre quem. Quando o cliente age em nome de uma empresa, passe about com o handle dessa conta ou parceiro. A organização fica amarrada do mesmo jeito que o cliente: as ferramentas usam, o modelo não muda, e toda leitura confere de novo se o vínculo entre os dois está ativo. O token vale 15 minutos; emita outro quando a conversa passar disso.

Passo a passo

1. Emita o subject token no seu backend

Chame subject_token() quando a conversa começa, com o nível que a conversa provou. Emita do lado do servidor, nunca no navegador nem dentro do contexto do modelo.
Quando a conversa prova mais (um OTP, um login), emita um token novo no nível novo e reconecte. Quando o token vence, o servidor responde 401; emita outro.

2. Conecte o cliente MCP

Use qualquer cliente MCP que suporte Streamable HTTP e cabeçalhos próprios. Com os SDKs oficiais do MCP:
Entregue a lista de ferramentas ao seu modelo pela integração de MCP do seu framework e deixe que ele chame as ferramentas sozinho.

3. Conheça as sete ferramentas

Sete ferramentas, não sessenta. Cada descrição diz ao modelo quando usar, quando não usar e qual ferramenta complementa a outra. O servidor também expõe o resource niadra://context, o contexto do cliente do token, e prompts com os modelos de injeção: onde o contexto entra no prompt e onde entram os turnos ao vivo.
record_action exige o escopo act, limitado às trusted_action_ops da sua fonte quando ela declara essa lista. Uma ação registrada numa sessão marcada por tentativa de injeção fica em quarentena: não fecha nada e nunca aparece como feita.

4. Deixe o contexto guiar as ferramentas de histórico

O contexto já traz a seção “Do histórico”: a recorrência do último motivo, a última solução, as promessas em aberto e uma linha-índice (“14 conversas desde 2021; visita técnica (3), fatura (2)”). Ela responde sozinha à pergunta mais comum e ensina o modelo quando vale buscar, o que corta chamadas inúteis. As definições das ferramentas são texto fixo e ficam no início do prompt que o provedor guarda em cache: depois do primeiro turno, custam o preço do cache. Cada chamada de ferramenta passa pela mesma política e pelo mesmo nível de verificação do contexto e deixa um comprovante: quem perguntou, a consulta, os filtros, os itens devolvidos por hash e o que ficou retido.

Chamada de função sem MCP

Se a API do seu modelo tem chamada de função mas você não roda um cliente MCP, use as mesmas três ferramentas de histórico como definições de função. O SDK amarra o cliente no seu código:
O kit.definitions segue o formato { type: "function", function: {...} }, que a maioria das APIs de modelo aceita; em Python, kit.anthropic_definitions() devolve o formato da API Messages da Anthropic. As definições também saem em GET /v1/history/tools para qualquer outro ambiente, inclusive modelos que você hospeda.

Perguntas sobre todos os clientes

Este servidor responde sobre um cliente de cada vez. Para uma LLM de análise que pergunta sobre a base inteira (“quais promessas vencem esta semana?”), a Niadra tem um segundo endpoint MCP, /mcp/insights, com as ferramentas da análise da base: pseudônimo por padrão, grupos pequenos suprimidos, limite de volume por dia e um comprovante para cada chamada. Pede uma chave de escopo analytics numa fonte de analista, ou uma pessoa com o papel analysis; revelar o cliente por trás de um pseudônimo pede também admin na chave ou security na pessoa, e um motivo.

Próximos passos

Navegação do histórico

busca, linha do tempo e abrir item em detalhe.

Emitir subject_token

a requisição e a resposta.

Espaços e chaves

escopos, audiências e revogação.

Comprovantes e auditoria

o que cada chamada de ferramenta deixa registrado.