Provared MCP executor

provared-mcp-executor

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 servers behind it: take the servers' credentials away from the agent, so that the executor alone holds them.

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) over the stdio transport. The agent's MCP client starts the executor as if it were the tool server; the executor starts the real server, with its credential, and 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; a tested recipe for this is not written yet. 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.2.0.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).

Set it up

1. Write the settings (executor.example.json is a start): the server to start and where its credential is read from; the paths of the agent's keys, slip and book; the executor's keys and copy; the tools and the action each is. Paths are read from the settings file's folder.

1. 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

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.

1. The person signs the permission with their passkey (on the signing page at https://sign.prova.red, or with the library) and saves it where the settings say (agent.slip). The thumbprint of the passkey goes into agent.issuerKeys.

1. 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.

1. 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.

The settings

{

"name": "Provared MCP executor for the files server", "service": "executor", "server": { "command": "node", "args": ["files-server.mjs"], "cwd": "servers/files", "path": ["/usr/local/bin"], "env": { "FILES_API_TOKEN": { "file": "secrets/files-token" } }, "passEnv": ["PATH", "HOME"] }, "agent": { "slip": "slip.json", "book": "book.jsonl", "keys": "keys/agent.jwk", "issuerKeys": [" "] }, "executor": { "keys": "keys/executor.jwk", "copy": "copy.jsonl", "copyKey": "copy.jsonl.key" }, "tools": { "read_file": { "action": "provared.data.read" }, "order_supplies": { "action": "supplies.order", "amount": { "unit": "GBP", "pointer": "/total" } }, "send_messages": { "action": "provared.message.send", "amount": { "unit": "messages", "count": "/recipients" } } }, "unlisted": "refuse", "hideUnlisted": true, "timeout": 300000, "denialsPerHour": 600, "callIdInMeta": true, "shutdownWait": 5000, "maxWaiting": 16 }

• name: the executor's name; part of the tag on each line of its copy.
• service: the id the permission gives the executor in with; written into each stub's with. Default executor.
• server.command: the program to start, best named by its path. A bare name (node) is looked for in the folders of server.path, or, where that is not given, in the folders of the executor's own PATH, with a warning: that environment is set by the agent's client, which could then choose which program is given the credential. On Windows a bare name is tried with .exe and .com only; the server is started without a shell, which cannot run a .cmd or .bat shim (name the program the shim starts, such as node.exe with the script as an argument). A program that is not found stops the start.
• server.env: each variable the server needs, and where its value is read from: a file (file; one line ending at its end is dropped), the executor's own environment (env, warned against: that environment is only as safe as the agent's client that set it), or the settings themselves (value, warned against). The server's environment holds these and the variables in passEnv (by default PATH, PATHEXT, SYSTEMROOT, COMSPEC, WINDIR, TEMP, TMP, HOME, USERPROFILE, LANG, LC_ALL, TZ), and nothing else of the executor's environment: the agent's client, which starts the executor, passes the agent's environment to it, and the server must not inherit that.
• agent.issuerKeys: the thumbprints of the passkeys the executor trusts. With a slip signed by any other passkey the executor does not start.
• executor.copy, executor.copyKey: the executor's own copy of every call, and the key its lines are tagged under (32 random bytes, made the first time). Put them, and the executor itself, under a user the agent's side cannot write as; the copy shows a receipt left out of the book only if the agent's side cannot change the copy.
• tools: each tool the agent may call, by its exact name, with the action name the slip uses for it and, where it applies, its amount: a fixed value, the whole number at a JSON Pointer (RFC 6901) in the call's arguments (pointer), or the length of the list there (count). A call whose amount cannot be read is refused, and so is one whose arguments name one member twice in one object, or two that differ only in capitals (total and TOTAL): a server may read the other one. (A member name given twice exactly is refused in every message; names that differ only in capitals are refused only where a rule reads the amount from the arguments.)
• contentRules: optional; the path of a file of rules on the content of a change, tested before a call is let through (see "Rules on the content of a change" below). Its fingerprint is named in every receipt and denial.
• unlisted: refuse (default) refuses a call to a tool no rule names and writes a denial named executor.unlisted; forward sends it on with no receipt and no denial, and the record then leaves those calls out. With forward, a content rule that names a tool no rule in tools names stops the start.
• hideUnlisted: whether tools/list comes back without such tools. Default true.
• timeout: how long the server is given to answer a call, in milliseconds (default 300,000; from 1,000 to 86,400,000). After it the executor cancels the call and writes the receipt with an error.
• callIdInMeta: whether the executor's own identifier for the call is sent to the server in params._meta["red.prova/call-id"], so that a server that logs _meta can be matched line for line with the record. Default true. Off, the stub names the identifier under executor.call alone.
• denialsPerHour: the most denials written in any hour (default 600).
• shutdownWait: how long the server is given to exit after its input is closed before it is ended (default 5,000 milliseconds).
• maxWaiting: the most tool calls in progress or waiting their turn at once (default 16; 1 to 1,000). A call past it is answered with error 1001 and nothing is written. At most 256 tools/list requests may wait for the server's answer.

Rules on the content of a change

A permission allows kinds of action. Being allowed to change a file is not being allowed to change everything the file controls: a call that changes a label in a settings file and, with the same edit, switches on a scan setting is one call of one kind, and the permission accepts both. The executor can hold rules on content, in a JSON file of its own named by contentRules, and test each proposed change against them before it is let through. content-rules.example.json is a start:

{

"version": 1, "rules": [ { "name": "the scan setting in settings.json stays off", "tool": "write_file", "when": { "pointer": "/path", "matches": "settings.json" }, "content": { "pointer": "/content", "as": "json" }, "test": { "pointer": "/scan", "equals": false, "orAbsent": true } }, { "name": "settings.json is written whole, never edited in part", "tool": ["edit_file", "apply_patch"], "when": { "pointer": "/path", "matches": "settings.json" } } ] }

A rule has:

• name: text of 1 to 200 characters, different for each rule. It is shown to the model when the rule refuses, and written into the executor's log and copy.
• tool: the tool's exact name, or a list of 1 to 64 names.
• when (optional): one condition, or a list of up to 16, on the call's arguments; all must hold for the rule to apply. With no when the rule applies to every call to the tool.
• content (optional): where the proposed content is in the arguments (pointer, a JSON Pointer, RFC 6901) and