Provared MCP Executor MCP server

provared-mcp-executor

A guard, called the executor below, in front of an MCP tool server. It holds the server's credential in place of the agent, checks each tool call against a permission a person signed with a passkey, refuses calls outside it with a signed denial, and writes a receipt, countersigned with its own keys, for each call it lets through. The credential is kept from the agent only where the agent cannot read the guard's files or reach the server another way (What it is says when). Evidence, not a verdict.

Quick start

With Node.js 24.7 or later:

npm install -g provared-mcp-executor
provared-mcp-executor demo

demo needs no passkey and no settings. In a new temporary folder, which it names and leaves in place, it puts the executor in front of a made-up tool server, under a permission signed by a development stand-in for a passkey, sends it one tool call that is let through and one that a rule refuses, and checks the book with the Provared checker. The stand-in is not a person: its name ends with "(development)", and nothing the demonstration writes proves anything about anyone. It writes nothing outside that folder.

provared-mcp-executor demo --stdio is for trying the executor from an MCP client or a directory's inspector. Each start makes a new temporary folder, as demo does, and leaves it in place; in it go the settings and a stand-in permission valid for one hour, after which every call is refused until it is started again. It then runs the executor over stdio in front of the made-up server, with its two tools echo and add, until its input closes. Its standard output carries MCP messages only; on its standard error it says, in one line, that this is a demonstration whose records prove nothing about anyone, when the permission ends, and where the book is.

For real use, in a folder of your own:

provared-mcp-executor init
provared-mcp-executor keys --config executor.json
provared-mcp-executor check --config executor.json

init copies the example settings and rules into the folder, as executor.json and content-rules.json. Put in each value written <like this> but the passkey's thumbprint, then make the keys; a person signs the permission with a passkey, and its thumbprint goes in last; check lists every problem left. "Set it up" below gives each step. The executor holds the tool server's credential in place of the agent, and keeps it from the agent only if the agent cannot read the executor's files: see "What it is".

What it is

This is the executor's record of what an agent asked for through it, and what the executor did with each call. It proves nothing about calls that do not go through it. It counts only if the agent has no other way to the tool server behind it: take the server's credential away from the agent, so that the executor alone holds it.

An executor, in the words of the Internet-Draft draft-izmaylov-agent-permission-receipts, is software other than the agent that takes actions for it or holds what they need, and refuses an action the permission does not allow. This one stands between an agent and a tool server that speaks the Model Context Protocol (MCP). It runs in two ways: over the stdio transport, where the agent's MCP client starts the executor as if it were the tool server and the executor starts the real server, with its credential; or over HTTP, where the executor is itself a Streamable HTTP MCP server in front of one upstream HTTP MCP server, and several agents call it, each signing in with a secret of its own (see "Over HTTP, for several agents"). Either way, for every tools/call:

1. works out which action the call is, and its amount, from a rules file the person writes, by the tool's name, not from anything the agent says;
2. asks the agent's stub writer whether the person's signed permission (the slip) allows it: the check before acting of the Provared library;
3. if it does, writes its own copy of the call to the disk, sends the call on, and writes a signed receipt (a stub) that names the executor and binds the arguments and the server's answer by their fingerprints, and countersigns it with keys of its own;
4. if it does not, sends nothing, tells the model why in a tool error, and writes a signed denial.

Every other message (server/discover, initialize, ping, resources, prompts, notifications, a legacy server's own requests to the client) passes through unchanged. tools/list comes back without the tools that have no rule.

The executor holds the agent's keys and the server's credential. The agent holds neither, so it cannot write, change or skip a receipt, as long as it cannot read the executor's files: an agent with a shell or file tools that runs as the same computer user can read them, and then the copy, the keys and the credential are all in its reach. Run the executor under a separate user account that the agent cannot use, or give the agent no shell or file tools. Over HTTP it can also run apart from the agent, where the agent cannot read the executor's files: an example (in the repository, not in the npm package) 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. The executor also keeps its own copy of every call, apart from the agent's log, which can be held against the log to find a receipt that was left out (compare).

Evidence, not a verdict. The whole design, with every choice numbered for review, is in DESIGN.md. The format is described in the Provared format description (spec/provared-format.md in the repository); the library is the npm package provared.

Install

npm install -g provared-mcp-executor

Or from a copy of the repository: in mcp-executor, npm pack, then npm install -g ./provared-mcp-executor-0.4.1.tgz.

It needs Node.js 24.7 or later, and depends only on the provared library, at version 0.7.0 or a later 0.7 version (^0.7.0): its receipts name provared.tool-name and provared.tool-result, which the format reserved in 0.7.0 and which a checker of 0.5.0 or 0.6.0 refuses (0.4.0 and earlier read them as labels). provared-mcp-executor --version prints the version installed.

The example files (executor.example.json, executor-http.example.json and content-rules.example.json) are in the installed package's folder, provared-mcp-executor inside the folder that npm root -g prints; provared-mcp-executor init copies them into the current folder.

Node.js says that its ML-DSA-87 signing is experimental each time it is first used in a program. The executor signs every receipt with ML-DSA-87 beside Ed25519, so the notice is expected; the command does not print that one notice, and prints every other warning. A program of your own that uses the executor's or the library's code sees the notice: it is not an error.

Set it up

1. Write the settings. provared-mcp-executor init copies the example settings and rules into the current folder as executor.json and content-rules.json (init --http copies the HTTP executor's as executor-http.json), and overwrites nothing. Then put in each value written <like this>: the server to start, the folder it runs in and the file its credential is read from. Set tools to the server's tools and the action each is, and change content-rules.json to rules of your own, or take contentRules out. The paths of the agent's keys, slip and book and of the executor's keys and copy can stay as they are. Paths are read from the settings file's folder. Leave the passkey's thumbprint (agent.issuerKeys) for step 3.

2. Make the keys. This makes the two key files if there are none, and prints what goes into the permission:

   provared-mcp-executor keys --config executor.json
   

   It does not need the passkey's thumbprint yet. It reads and checks everything before it writes: the settings, the rules file, any key file already there, and that the folder of each file it would write can be made. With --out <file> it writes what it prints to a new file instead (not one of the key files), making its folder where needed. The printed agent.keys go into the permission as the agent's keys; the printed with entry (the executor's id, name and keys) goes into the permission's with; and requires should hold {"need": "countersignature"}, so that a receipt without the executor's countersignature is a finding.

3. The person signs the permission with their passkey (on the signing page at https://sign.prova.red, or from a web page of your own with the library's browser part, provared/passkey-browser) and saves it where the settings say (agent.slip). The thumbprint of the passkey goes into agent.issuerKeys.

4. Check the settings. This reads every rule, the keys, the slip and the credentials, and says what is wrong. It prints no credential.

   provared-mcp-executor check --config executor.json
   

   It writes nothing: no line to the book, no copy key. It lists in one run every problem it can find on its own: each value still written <like this>, the server's program and folder, each credential, the rules file, each key file and the slip. Once none is left, it holds the slip against the keys and the rules, as a start does, and stops at the first difference there.

5. Point the agent's MCP client at the executor where it named the server. For a client whose settings are JSON:

   {
     "mcpServers": {
       "files": {
         "command": "provared-mcp-executor",
         "args": ["stdio", "--config", "/etc/provared-mcp/files/executor.json"]
       }
     }
   }
   

   The client starts the executor; the executor starts the server named in server.command with server.args, in server.cwd, with the credentials in server.env.

Over HTTP, for several agents

provared-mcp-executor http --config executor-http.json

The executor listens as a Streamable HTTP MCP server (one endpoint, /mcp unless the settings say otherwise, on 127.0.0.1:8796 unless they say otherwise) in front of one upstream HTTP MCP server named in upstream.url. Each agent signs in with a secret of its own, in one header, Authorization: Bearer <secret>, and has its own slip, keys, book and copy under agents.<name>. provared-mcp-executor secret makes a secret and prints its hash; the hash goes into the settings as the agent's secretHash, the secret goes to the agent and is stored nowhere else. init --http copies the example settings (executor-http.json) and rules into the current folder. keys makes the executor's key file and one for each agent, and prints the entries for each agent's permission (it needs no secret hash and no passkey's thumbprint yet); check reads every agent's slip; compare --agent <name> holds one agent's copy against its book.

What the executor does with each request:

• A tools/call goes through the same rules, check, receipt, countersignature and copy as on stdio, under the slip and into the book of the agent that sent it. The check happens before anything reaches the upstream. One call at a time goes through each agent's writer; agents do not wait for each other. maxWaiting holds for each agent on its own.
• The agent's Authorization header is removed. The upstream is sent the executor's own credential, a bearer token read from the file upstream.credential.file. Of the agent's headers only Accept, Accept-Language, Content-Type, Mcp-Session-Id and Last-Event-ID go on, with the MCP-Protocol-Version the body states, and the mirrored headers of the 2026-07-28 revision where each agrees with the body: Mcp-Method with the body's method, Mcp-Name with its params.uri on a resources/read or its params.name on a tools/call or prompts/get, and Mcp-Param-<name> with the call's argument at the property of the tool's inputSchema that the upstream's tools/list annotated x-mcp-header: <name> (a value wrapped as =?base64?…?= is decoded before comparing, and a number in the body is compared as a number with a header in JSON's form of one, so 42.0 agrees with 42 and 0x2A does not). Every other header is dropped, and the names of the dropped ones are logged. A mirrored header that does not agree with the body, or that the executor cannot check (no tools/list seen yet, no such annotation, a GET or a response, an Mcp-Name on any other method), is refused with 400 and JSON-RPC error -32020 (the specification's HeaderMismatch), and nothing reaches the upstream; a request with none of these headers is not refused, and the executor never generates Mcp-Method, Mcp-Name or Mcp-Param-* itself, though the protocol version the body states goes on as its header. Of the upstream's headers only Content-Type, Mcp-Session-Id, MCP-Protocol-Version and Cache-Control come back.
• One message per POST, read as strictly as a line on stdio: a batch, a repeated member name, an id that is not text or a whole number, a number beyond 2^53 - 1, or a shape that is not a message is refused (400) and goes no further. A tools/call sent as a notification is dropped (202).
• The upstream's answer comes back as it came: a JSON body, or a stream of events forwarded one by one as they arrive. The response under the call's id is the outcome and ends the call; a response under another id is never taken as the outcome. The stream to the upstream is closed once the outcome is in. An upstream that refuses a call with a 4xx status and a JSON-RPC error under the call's id (the specification's way: 400 for a header mismatch or an unsupported protocol version, 404 for a method it does not have) has that error recorded as the outcome and relayed, with its status, under the agent's id; a non-2xx with no such body is recorded as "outcome not known", and its body is not relayed.
• Legacy sessions pass through: the Mcp-Session-Id the upstream gives comes back as it is, the GET stream of server messages and initialize pass through, and a session belongs to the agent that opened it. Another agent's request under it, or an unknown id (after a restart, the executor knows none), is answered 404, and the client begins a new session.
• Cancellation follows the era. On the 2026-07-28 revision, closing the response stream is the cancellation: the executor then closes its stream to the upstream, the outcome is recorded as not known, as on stdio, and the agent's own notifications/cancelled for a call in progress does the same and is answered 202, with nothing sent on. On a legacy session (a session id, or a protocol version before 2026-07-28), where the specification says a disconnection is not a cancellation, the agent's notifications/cancelled is sent on to the upstream under the upstream's id for the call, answered as the upstream answers it, and then the stream is closed; the agent merely disconnecting leaves the call running, bounded by timeout, and its real outcome is recorded.
• A request that names an Origin is refused (403) unless allowedOrigins lists it; a body over bodyLimit (10 MiB) is refused (413), and one that does not arrive whole within timeout is refused (408); an answer or an event of the upstream over 16 MiB is cut off; a call the upstream does not answer within timeout is cancelled and gets a receipt that says its outcome is not known; an agent whose connection does not take what the executor has waiting within timeout has that exchange cut, the upstream's stream having been paused meanwhile rather than buffered, and a very slow reader can be cut too, since the clock stops only when all that is waiting has gone; each agent may have 256 requests in flight and 1,000 sessions remembered, its own oldest forgotten first. A JSON answer the agent does not read is still held after its place among the 256 is freed, up to 16 MiB for each connection, until that connection closes; the executor does not limit the number of connections.
• A stop on request (SIGINT, SIGTERM) with a call in flight settles the call as the executor's stop ("The executor stopped while this call was with the tool server, so its outcome is not known."), writes its receipt, answers the agent with that error, and then closes; a call still waiting its turn is not sent and is answered so. A stop without warning, followed by a start, writes the receipt from the agent's copy before the executor listens, as on stdio.

When the credential is kept from the agent, and when it is not. The upstream's token never goes to an agent in a header, a body, an error or a log: the executor forwards none of the upstream's headers but the four named, and those with the token's text replaced too; relays nothing of an upstream answer that refuses the token (401 or 403; the agent is told the executor's credential was refused, and no more); never follows a redirection; and replaces the token's text wherever it occurs in anything it sends an agent (a tool result that echoes it, an error text, an event, a header) with the words "[a credential was removed by the Provared executor]". That holds for the token as it is in the file; a token the upstream encodes or splits before echoing it is not seen, and JSON's own escaping of a /, " or \ in the token counts as encoding. It holds only for what passes through the executor: an agent that can reach the upstream by another way, or read the executor's files, has the token. And the agents' secrets are only as safe as the connection they travel on: the executor listens on the local address by default and speaks plain HTTP, so an agent on another computer should reach it through an encrypted connection that something else provides.

The settings (executor-http.example.json is a start): name, service, tools, contentRules, unlisted, hideUnlisted, timeout, denialsPerHour, callIdInMeta and maxWaiting as below; and

• listen: host (default 127.0.0.1; another address is warned about) and port (default 8796). path: the endpoint (default /mcp).
• upstream: url (http or https; plain http off this computer is warned about) and credential: {"file": <path>}, the file that holds the bearer token, readable by the executor alone. Without credential the upstream is called with none, and the start says so.
• agents: one member for each agent, by name (1 to 64 lower-case letters, digits, full stops, hyphens or underscores): secretHash, slip, book, keys, issuerKeys, and copy and copyKey (defaults copies/<name>.jsonl and copies/<name>.jsonl.key). No two agents may share a secret or a file.
• executor: keys, the executor's own key file.
• bodyLimit: the most a POST body may be, in bytes (default 10,485,760).
• allowedOrigins: the origins (scheme, host and port) whose pages may call the executor. Default none.