O endereço
O servidor fala Streamable HTTP em/mcp, no endereço do seu espaç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 dosubject_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
Chamesubject_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.
2. Conecte o cliente MCP
Use qualquer cliente MCP que suporte Streamable HTTP e cabeçalhos próprios. Com os SDKs oficiais do MCP: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.
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: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.

