53 · O servidor MCP¶

O stalwart mcp dá ao seu assistente de programação com IA -- Claude Code, Cursor, VS Code -- toda a suíte como ferramentas: o guardrail, construído com você e ensaiado nas suas próprias chamadas; o gateway; o caçador de falhas; o red team; a verificação formal das suas regras e do grafo de um agente; e os certificados, conferidos na sua máquina. O seu assistente faz cada passo pelo servidor e traz o resultado para você, com a página do console para desenvolvedores que o mostra e o capítulo deste guia que o explica.

O servidor roda na sua máquina, por stdio. Ele chama o serviço da Stalwart só onde um passo já chama -- compilar uma planilha de regras, uma caça, um red team, uma prova --, e nunca chama um modelo: onde um passo precisa de um, como rascunhar uma planilha de regras a partir da sua política, o seu próprio assistente o faz, por um prompt, e o servidor confere o que ele fez.

Idiomas

O seletor lê turnos escritos em inglês e em português do Brasil (pt-BR). O idioma é escolhido, nunca adivinhado a partir do turno: na página Settings do console (Language the selector reads), em language numa requisição de plano, ou no settings.language do seu arquivo de vocabulário; sem nenhum deles, inglês. Um turno em português pode ser digitado com os acentos ou sem eles. O português europeu não é uma gramática que o seletor tenha, e um turno em qualquer outra língua não é lido.

Adicionando ao seu assistente¶

Na pasta do seu projeto:

$ stalwart mcp --config claude      # imprime: claude mcp add stalwart -e STALWART_MCP_HOME=<esta pasta> -e QLS_API_KEY=<a sua chave> -- ...
$ stalwart mcp --config cursor      # a entrada mcpServers para o Cursor
$ stalwart mcp --config vscode      # a entrada servers para o VS Code

Rode-o na pasta do seu projeto: a configuração nomeia essa pasta (STALWART_MCP_HOME), então os arquivos do servidor vão para ela, nunca para a pasta pessoal em que um cliente inicia servidores. Ponha a sua chave na configuração também: um servidor lê o seu ambiente uma vez, ao começar, então uma chave definida depois exige iniciar o servidor de novo (o status diz isso).

Depois peça ao seu assistente para chamar o status: ele responde com a pasta em que o servidor trabalha, se ele tem a sua chave, o seu plano e quanto resta de cada medidor neste mês.

Como ele conduz o seu assistente¶

Um assistente usa o que um servidor mostra a ele, então o servidor mostra tudo e diz para onde ir depois:

As instruções dele, que o seu assistente lê primeiro, nomeiam cada produto e a ferramenta de cada um, e dizem ao assistente para fazer cada passo por essas ferramentas, e não escrevendo código nem lendo o código-fonte do pacote.
Toda resposta diz o que vem depois (next): o que o passo não cobriu e a ferramenta que cobre. Depois de uma caça que não encontrou nada, por exemplo, ela diz o que a caça não leu, e que o verify_rules prova uma ação contra as suas regras.
Toda resposta que leva a uma página dá o endereço dela: console para a página do console para desenvolvedores que mostra o resultado, guide para o capítulo deste guia sobre o passo. O links dá todos os endereços de uma vez (abaixo).
O prompt assurance-plan conduz o seu assistente por cada nível em ordem, diz o que cada um cobre e o que usa do seu plano, e pergunta quais você quer.

Uma sessão que começa do zero é assim: status; catalogue_from_server no servidor das suas ferramentas; writes_file, e os tipos que você confere; uma planilha de regras que o seu assistente rascunha a partir da sua política em palavras simples, e que você lê; compile_rules e lint_rules; check_sequence nas chamadas de uma conversa; hunt num projeto; e, onde você quer que fique provado, verify_rules no perfil proof e check_certificate no que ele escreveu.

As ferramentas dele¶

Perguntando o que ele faz¶

Ferramenta	Responde
`capabilities(language)`	todas as verificações, da própria lista do guardrail: o que barram e o que não conseguem, o que leem e as opções on-fail; onde ele pode rodar; versões; o que é garantido e o que não é
`explain_check(name, language)`	uma verificação inteira, com um exemplo permitido e um barrado e a sua seção do manual
`search_manual(question, language)`	as seções do manual que mais combinam, pelas palavras, em inglês ou português; sem modelo
`how_to(goal, language)`	receitas fixas: "proteger meu servidor MCP", "adicionar ao meu guard do Guardrails AI", "escrever uma regra para reembolsos acima de 100", "avaliar nos meus traces", ...
`explain_decision(decision_id)`	por que uma chamada registrada foi barrada: a verificação, a sua regra e o que ela leu
`status()`	se há uma chave, o plano dela, o que ela pode usar e quanto resta de cada medidor, e a pasta em que o servidor trabalha: leia antes de um passo que usa cota
`links(about, language)`	todo endereço de que uma pessoa precisa: cada página do console para desenvolvedores com o que ela guarda, e onde entrar; o capítulo do guia de cada produto; a referência da API, a documentação do pacote, o pacote e onde se cadastrar

Construindo e ensaiando um guardrail¶

Ferramenta	Faz
`catalogue_from_server(server, out)`	lê as ferramentas de um servidor MCP para `tools.json`: o endereço, uma resposta `tools/list` salva, ou o comando que o inicia (`npx -y @playwright/mcp@latest`), iniciado aqui, listado e parado
`writes_file(tools, out)`	rascunha `tool_kinds.yaml`: o tipo, o motivo e a origem de cada ferramenta, as incertas primeiro
`set_tool_kinds(changes, reasons)`	define tipos como o seu assistente propõe, registrados como `source: assistant`
`compile_rules(sheet, out_dir)`	compila `rules.yaml` com o serviço para `compiled/`
`lint_rules(sheet, tools)`	uma regra para uma ferramenta que você não tem; uma escrita que nenhuma regra nomeia
`check_call(call, context)`	uma resposta de ensaio; nada roda
`check_sequence(calls, context, approve)`	o ensaio de uma sessão: cada chamada respondida com o que as anteriores rodaram, para que regras de ordem, limites e confirmações sejam testados como uma execução os encontra; uma chamada perguntada é respondida de novo com o sim de uma pessoa
`search_wordings(tools, language, checks, seconds)`	a busca de formulações das três verificações que leem o turno
`snippet(where, upstream)`	o código para `python`, `guardrails-ai` ou `nemo`, ou o `catalogue.json` e o `gateway.yaml` do `gateway`

O check_call responde uma chamada sozinha. Regras de ordem (after), limites (at_most) e confirmações só aparecem ao longo de uma conversa, então teste-os com o check_sequence: cada chamada é respondida com o que as anteriores rodaram.

Medindo, caçando e fazendo red team¶

Ferramenta	Faz
`replay(trace, format)`	a resposta de cada chamada; contagens por regra; as chamadas barradas; confirmações por 100 chamadas; tempo p50/p95; determinismo
`evaluate(labelled, format)`	alarmes falsos e falhas contra os seus rótulos, por regra
`counterfactual(trace, outcome_checker)`	a sua própria verificação de resultado, como rodou e sem as chamadas barradas
`hunt(sheet, properties, session_steps, profile, project, branch, commit)`	o caçador de falhas nas suas regras (o serviço, com a sua chave); com um `project`, a varredura fica guardada onde a página Findings do console para desenvolvedores a mostra, e a resposta traz o endereço dos achados do projeto e o da página de cada achado
`redteam(server)`	as ferramentas de um servidor MCP atrás do gateway, provadas para qualquer chamada (o serviço, com a sua chave)
`compare_with_gai(trace, guard)`	o seu guard do Guardrails AI sozinho, e com o nosso validador
`benchmark(name)`	busca os dados de companhia aérea ou varejo do tau2-bench nos seus commits fixados

Provando¶

Ferramenta	Faz
`verify_rules(action, without, sheet, profile, certificate)`	a verificação formal das suas regras: `action` pode rodar sem `without`? Sim, com a testemunha; não, provado com um certificado nos perfis `proof` e `patch`, e a palavra do solver no `fast`
`verify_graph(graph, catalogue, rules, certificate)`	o grafo de um agente verificado antes de ir para produção: toda rota até uma ação de risco sem a sua salvaguarda
`check_certificate(certificate, cnf)`	um certificado conferido aqui, offline, pelo verificador que o pacote traz (`stalwart check`)

Os prompts dele¶

assurance-plan: cada nível de garantia em ordem -- construir, ensaiar, caçar, red team, provar, certificar, acompanhar --, o que cada um cobre e não cobre e o que usa do seu plano; o seu assistente pergunta quais você quer e faz só esses.
build-guardrail: a construção inteira, em ordem: ferramentas, tipos, uma planilha de regras rascunhada a partir da sua política em palavras simples, compilar e verificar, ensaios, busca e caça, o trecho de código. O seu assistente rascunha a planilha; você a lê antes de ela ser usada.
classify-tools: o seu assistente propõe tipos para as ferramentas de que a dedução não tem certeza.
set-up-guardrail: uma receita do how_to, seguida passo a passo.
evaluate-guardrail: replay e evaluate nas suas chamadas, sem citar nada delas.

Os resultados no console para desenvolvedores¶

O que o servidor faz com o serviço fica listado no console para desenvolvedores, na sua organização:

Findings: o hunt com um project (um nome; o projeto é criado na primeira vez) guarda a varredura nele, num branch e num commit quando você os informa. A resposta dá o endereço do projeto na página Findings e o de cada achado. Ali você aceita um achado com o motivo, ou o deixa para corrigir, e a próxima varredura do projeto lê as suas decisões (capítulo 28).
Jobs: cada caça, red team e prova é um job, com o seu estado, o seu veredito e os seus arquivos, entre eles um certificado (capítulo 9).
Usage: o que cada medidor usou neste mês contra o seu limite -- o status dá os mesmos números ao seu assistente (capítulo 16).

O links dá ao seu assistente todos os endereços: cada página do console para desenvolvedores com o que ela guarda, e onde entrar; o capítulo deste guia de cada produto; a referência da API, a documentação do pacote, o pacote e onde se cadastrar. links(about="findings") restringe cada lista ao que o nomeia. O capítulo 5 tem todas as páginas do console.

Uma prova, ou a palavra do solver¶

O verify_rules faz uma pergunta -- esta ação pode rodar sem esta condição? -- e a responde no perfil que você indica (capítulo 10):

Sim vem com a testemunha: a conversa em que ela roda. Corrija a regra que ela atravessa, compile e pergunte de novo.
Não, em proof ou patch, é uma prova derivada, com um certificado. O servidor o grava em certificates/, e o check_certificate o confere na sua máquina, offline, com o verificador que o pacote traz (capítulo 7).
Não, em fast, é a palavra do solver, sem certificado. A resposta diz isso, e diz para perguntar de novo em proof para ter um.

Uma prova responde à pergunta feita, e a nenhuma outra (o que isto prova). O verify_graph prova o grafo de um agente antes de ele ir para produção (capítulo 47).

Os arquivos que ele lê e grava¶

Todo caminho fica dentro da pasta em que o servidor trabalha; um caminho que sairia dela é recusado.

Arquivo	Gravado por	Lido por
`tools.json`	`catalogue_from_server`	todas as ferramentas do guardrail
`tool_kinds.yaml`	`writes_file`, `set_tool_kinds`	todas as ferramentas do guardrail
`rules.yaml`	o seu assistente, a partir da sua política	`compile_rules`, `lint_rules`, `hunt`, `verify_rules`
`compiled/`	`compile_rules`	`check_call`, `check_sequence`, `replay`, `evaluate`
`catalogue.json`, `gateway.yaml`	`snippet` com `gateway`	`stalwart gateway`
`certificates/`	`verify_rules`, `verify_graph`	`check_certificate`

Plano e cota¶

Caças, red teams e provas são do serviço e contam no seu plano; o status diz o que resta antes de o seu assistente começar uma, e uma prova no perfil proof é contada à parte (capítulo 16). Construir, ensaiar, reproduzir chamadas e conferir um certificado rodam na sua máquina, e não contam nada.

Os limites¶

O servidor conduz o seu assistente; ele não o obriga a seguir. Um assistente que escreve o próprio código em vez disso ainda pode, e os resultados dele são dele.
Um relatório traz nomes de ferramentas, nomes de regras, contagens, ids de decisão e digests, nunca um valor de argumento nem uma palavra que uma pessoa disse. Para ver a testemunha de um achado inteira, abra a página dele no console.
O red team lê o servidor das suas ferramentas, não o roteamento próprio do seu agente: o verify_graph é o passo para isso.