provared-mcp-executor
OfficialProvides ProvaredMiddleware for LangChain agents, placing every tool call behind Provared permission checks and receipt recording with configurable action mappings.
Provides recordTools integration and examples for the Vercel AI SDK, allowing JavaScript agents to record and receipt tool calls under Provared permissions.
Provared
A guard for an AI agent's tools: it holds the tools' credentials in place of the agent, and stops any tool call that the person did not allow in a permission they signed with a passkey.
The guard, provared-mcp-executor, stands between the agent and a tool server that speaks the Model Context Protocol (MCP), the common way for AI agents to reach tools. It holds the tool server's credential in place of the agent, and refuses a call the permission does not allow before the call reaches the tool. It can also test what a call would change, for example which paths a file tool may touch. It starts a tool server itself on the same computer, for one agent (MCP's "stdio" transport), or, from version 0.3.0, stands in front of one reached over the network (MCP over HTTP, the protocol of the web), for several agents, each with its own secret, permission and record.
The record follows from it. For each call it lets through, the guard writes a signed receipt and countersigns it with keys of its own; for a call the permission does not allow, a signed note of the refusal (a denial). Anyone can check these records later, on their own computer, with the free checker.
What it does not do yet. One guard stands in front of one tool server, and over the network the credential it holds is a bearer token read from a file. Over HTTP it has been tried with the official MCP software on protocol version 2025-11-25 only, with every program on one computer; on the newer 2026-07-28 it has met only a test server of its own. The agents' secrets travel in the clear unless something else encrypts the connection to the guard, and so does the tool server's credential if the tool server is reached by plain HTTP. Sealing the record and keys held in a key service are designed but not built. And it proves nothing about a tool the agent can reach without it: the tool's credential must be taken away from the agent. It keeps the credential, and its own keys, from the agent only where the agent cannot read the guard's files: an agent with a shell or file tools that runs as the same computer user can read them. So run the guard under a separate user account that the agent cannot use, or give the agent no shell or file tools. Over HTTP the guard can also run apart from the agent, where the agent cannot read the guard's files: an example puts them in separate Docker containers on one computer, and its seven checks passed with Docker Desktop on Windows; on separate computers it has not been tried.
Evidence, not a verdict. A record shows what was signed and by which keys. People decide what it means.
npm install -g provared-mcp-executor # Node.js 24.7 or laterIts README sets it up in five steps: write its settings, make its keys, sign the permission with a passkey at https://sign.prova.red, check the settings, and name the guard in the agent's MCP client where the tool server was named. For a client whose settings are JSON:
{
"mcpServers": {
"files": {
"command": "provared-mcp-executor",
"args": ["stdio", "--config", "/etc/provared-mcp/files/executor.json"]
}
}
}To see it work first, with no passkey and no settings,
provared-mcp-executor demo (from version 0.4.0) runs the guard in front
of a made-up tool server in a new temporary folder, lets one call through,
refuses one and checks the book, under a permission signed by a
development stand-in, not a person, so its records prove nothing about
anyone; then
provared-mcp-executor init copies the example settings into the current
folder. The guard is listed in the
official MCP Registry as io.github.provared/mcp-executor. "Executor"
is the Internet-Draft's word for software, other than the agent, that
acts for it and refuses what the permission does not allow.
Other ways to record an agent
The guard is one way to put an agent's actions behind a signed permission. The others write the same kind of record, read by the same checker:
The library, in JavaScript or Python, for an agent you write yourself: each action is checked against the permission first and receipted after (see "A first record of your own", below).
The recorder beside Claude Code (
provared-claude-code, also a Claude Code plugin), which checks and receipts every tool call Claude Code makes.Packages for two Python agent frameworks, LangChain and Pydantic AI, and an example for the Vercel AI SDK.
The gateway, for agents that act through web interfaces: it stands in front of each system an agent uses, holds that system's credential and receipts each call. In the repository, not yet on npm.
Related MCP server: Agentomy MCP Gateway
The checker, and the sample record
npm install provared # Node.js 24.7 or later, no dependencies
pip install provared # Python 3.11 or later, one dependency
npx provared-check --sample # the checker's answer for the sample recordThe sample is an invented office agent that goes over its limit at its fifth order. The checker's answer ends:
Summary
Is the record intact? yes
Was every signature checked? yes
Did the agent stay within its slip? NO: first at entry 5
Time-stamped in a way you trust? yes: the first 9 entries existed by 2026-10-05T10:16:00Z
Checked against keys you named? yes: the passkey you trust, and the recorder you expectA first record of your own
Three commands. The permission is signed with a development stand-in
for a passkey: a key made in memory, which no person confirmed. Every
permission it signs says so in its issuer's name, and the checker prints
that name. A real permission is signed by a person, in a browser, with a
real passkey (provared/passkey-browser, and the checking page).
npm install provared
node first-record.mjs
npx provared-check book.jsonl --issuer <the thumbprint it prints>first-record.mjs (examples/first-record.mjs):
import { writeFileSync } from 'node:fs';
import { developmentRecorder } from 'provared/dev';
const SEND = 'provared.message.send';
// A permission: the agent may send messages, at most two.
const { recorder, issuerKeys } = await developmentRecorder({
actions: [SEND],
limits: [{ action: SEND, count: 2 }],
purpose: 'Send a few messages, to make a first record.',
});
// Each action is asked for first, taken only if the permission allows it,
// and receipted after. The third message is outside it, so it is not sent.
for (let i = 1; i <= 3; i++) {
const outcome = await recorder.act({ action: SEND }, async () => console.log(`message ${i} sent`));
if (!outcome.done) console.log(`message ${i} not sent: ${outcome.answer.breaches[0].message}`);
}
writeFileSync('book.jsonl', recorder.book());
console.log(`npx provared-check book.jsonl --issuer ${issuerKeys[0]}`);The same in Python is
python/examples/first_record.py, with
from provared.dev import development_recorder. For a LangChain agent,
pip install provared-langchain puts every tool call behind the same
check with no change to the tools
(python/integrations/provared-langchain):
from langchain.agents import create_agent
from provared_langchain import ProvaredMiddleware
agent = create_agent(model, tools=[order_supplies, send_message],
middleware=[..., ProvaredMiddleware(writer, {
'order_supplies': {'action': 'supplies.order', 'with': 'supplier',
'amount': lambda a: {'unit': 'GBP', 'value': a['total_gbp']}},
'send_message': 'provared.message.send',
})]) # last among the middleware that wrap tool callsThe package is listed among the middleware in
LangChain's own documentation.
For JavaScript agents, examples/frameworks/ shows the
same with the Vercel AI SDK, through recordTools.
The four parts
Part | What it is |
The permission (a Slip) | A person signs it with a passkey: which agent, which actions, what limits and conditions, with whom, from when until when, and why |
The receipt (a Stub) | The agent signs one for each action, pointing back to its slip; the other side countersigns it where it can, and the person approves it where the slip asks |
The sealed book (a Seal) | The receipts chained, gathered under one fingerprint, signed by whoever keeps the book and time-stamped by an outside service |
One page with proof (a Show) | One entry handed to a checker with proof that it is in the book, and when the book was sealed, with the names it does not need kept covered |
The checker answers two questions and keeps them apart: is the record intact, and did the agent stay within its slip. Going over a limit is not a fault in the record. It is what a sound record shows.
What the author found nowhere else
Signed, chained and time-stamped receipts for an agent's actions exist in other open projects too, some with quantum-safe signatures. As far as the author knows, in October 2026, three things are only here: limits a machine can check in a permission the person signs, with the checker's answer "did the agent stay within it"; passing a permission on to a helper agent so that it can narrow and never widen; and cancelling with the agent's signed acknowledgement, so that a record shows when the agent's side was told. If you know of another project that does any of these, open an issue: the list is kept honest.
What a record does not prove
It shows what was recorded, not what was left out: an agent that acts and writes no stub leaves no trace. A one-sided stub shows what the agent's side said. It does not show that an action was wise, lawful or wanted, nor who was holding the device when the passkey signed. A name in a record is a label; only keys are checked. The full list, with what each part protects against, is in docs/threat-model.md.
Where everything else is
The guide: the whole library, in one document. Installing and importing; the command-line checker; what a slip can say; seals, time-stamps, witnesses and the chain of block headers; cancelling; who stands behind a name; covered fields; passing a slip on; the check before acting; the stub writer beside an agent and the connector for its tools; what the checker returns; what it never does; what is not built yet.
The format, described exactly, and the shared test files in test-vectors/ that any implementation can be held to.
The Python version, which gives the same answers, with examples for three agent frameworks and packages for two of them.
Two programs beside an agent, each on npm with its own README: the recorder beside Claude Code (
npm install -g provared-claude-code, also installable as a Claude Code plugin), which checks and receipts every tool call Claude Code makes; and the executor for MCP tool servers (npm install -g provared-mcp-executor), which stands between agents and a tool server, holds the server's credential, and countersigns each receipt with keys of its own.The pages at prova.red: the checker's answer for the sample record, a worked example for developers, and the same in plain words for a reader who does not write code.
The checking page, which checks a record in a browser and loads nothing from anywhere; also built as one file, attached to each release. It uses only the signing methods the browser has built in. Tried on the author's computer on 13 October 2026: Chrome 155, Edge 155 and Brave 155 each check the quantum-safe signatures on receipts (ML-DSA). None of the three has the third method a seal is signed with (SLH-DSA), so in a browser a book with a seal is never a pass. The command-line checker checks all three.
The core of the format as an individual Internet-Draft at the IETF: draft-izmaylov-agent-permission-receipts. An Internet-Draft is a working document, not a standard.
Status
Version 0.8.0, a draft. Published as it is, by one author in their own time, built with AI tools since 3 October 2026; fixes as time allows. The code has been through more than 80 rounds of review by AI reviewers, each a fresh session given the code, the documents and a brief of what to look at. Until 7 November 2026 each reviewer likely also had the author's private planning notes loaded, so could see the author's reasoning; since then reviewers start without them. Every fault was fixed, or stated as a limit, and kept as a test. No person other than the author has reviewed it yet. That is an invitation. The format may still change. Every published version stays on npm and the Python Package Index, so a record made with one version can always be checked by that version.
Questions, faults and suggestions: hello@prova.red, or issues on GitHub.
Licences
Copyright 2026 Pavel Izmaylov.
The code, the pages and the sample files: Apache License 2.0
(LICENSE). The format description and the other documents: Creative
Commons Attribution 4.0 International (LICENSE-CC-BY-4.0.txt).
Available Tools
2 toolsaddA
Demonstration only: a made-up tool that adds two whole numbers and hands back the sum.
Inputs: a (required), b (required).
echoA
Demonstration only: a made-up tool that hands back the text it is given. In the Provared demonstration, a rule on content refuses any text with the lower-case word "password", so that a refusal can be seen.
Inputs: text (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools do entirely different things: echo returns its input text and add sums two integers. There is no plausible scenario where an agent would confuse one for the other.
Both names are single lower-case verbs in the same style (echo, add), so there is no mixing of conventions or casing. The lack of a noun or domain prefix is a minor deviation from a verb_noun pattern but internally consistent.
Two tools is borderline thin even for a demonstration server, and neither corresponds to an actual execution task implied by the 'executor' name. The surface feels like a placeholder rather than a scoped toolset.
The tools are explicitly 'made-up' demos with no lifecycle or domain coverage, so there is no real workflow an agent could complete beyond trivial smoke tests. Against the apparent purpose of an executor server, the surface is a significant gap.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Authorize AI agent tool calls before they run: policy-as-code, human approval, signed receipts.
Guard wraps stdio MCP servers: risky calls wait for a person; no answer, no run. Remote: cooperative
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Related MCP Servers
- AlicenseBqualityCmaintenanceSecurity gateway that wraps any MCP server with per-tool policies, approval gates, and optional Ed25519-signed decision receipts. Shadow mode logs every tool call without blocking; enforce mode applies block, rate-limit, and minimum-tier rules. Receipts are independently verifiable offline with no accounts needed.52,368 npm11MIT

Agentomy MCP Gatewayofficial
AlicenseNot gradedqualityCmaintenanceGoverns any stdio MCP server by interposing between the agent and the server, enforcing policy on every tools/call and refusing denied actions before they reach the upstream server.18 npmApache 2.0- AlicenseNot gradedqualityBmaintenanceEnables developers to wrap existing MCP servers with a deterministic policy enforcement gate that intercepts tool discovery and tools/call requests over stdio, allowing only authorized calls to reach the downstream server. It supports dynamic tool exposure or hiding, allow/deny/approval-required decisions, configurable error disclosure modes, and Ed25519-signed retry credentials for approved workflows.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceSits in front of any MCP server to enforce allow/ask/block policies on tool calls, paths, shell commands, and network domains, with local approval prompts and an audit log.MIT