Record MCP tool calls

Put signafaide gateway in front of an MCP server and every tool call that passes through it is written as a signed, chained record. No tool is wrapped by hand, and the agent can be written in any language.

Every option: Tool coverage. The gateway is part of the signafaide npm package and needs Node.js 18 or later. For tools that are not MCP tools, see the quickstart.

The change #

In the agent's MCP settings, start the gateway in place of the server. Everything after -- is the command that was there before. The gateway runs the server and relays every message unchanged.

Before

JSON

{
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/data"
  ]
}

After

JSON

{
  "command": "npx",
  "args": [
    "-y", "signafaide", "gateway",
    "--agent", "support-bot", "--",
    "npx", "-y",
    "@modelcontextprotocol/server-filesystem",
    "/data"
  ]
}

A verify run #

Run the agent once, then npx signafaide verify. This is a local run of two tool calls through the gateway: fifteen records for the tool list (the list and each of the server's 14 tools), then a decision and an outcome for each call.

$ npx signafaide verify
local state: /home/dev/support-agent/.signafaide
 1. Envelope schema              PASS         19 records
 2. Record hashes                NOT CHECKED  0 records; 19 not yet shipped (no receipt); nothing co-signed yet
 3. Client signatures            PASS         19 records
 4. Agent chains                 PASS         19 records
 5. Merkle proofs                NOT CHECKED  0 records; nothing co-signed yet
 6. Batch hashes and signatures  NOT CHECKED  0 batches; nothing co-signed yet
 7. Batch chain                  NOT CHECKED  0 batches; nothing co-signed yet
 8. Signed heads                 NOT CHECKED  0 heads; nothing co-signed yet
 9. drand rounds                 NOT CHECKED  0 rounds
10. Anchors                      NOT CHECKED  0 anchors; local state holds no anchors
11. OpenTimestamps               NOT CHECKED  0 proofs
12. Content hashes               PASS         19 records
coverage: _pending/nokey/support-bot: all 14 declared tools are recorded
checked here: signatures, chain links and content hashes of all 19 records, using this machine's keys
co-signature, public timestamp: not yet. Run `signafaide init` to send hashes, or self-host (SIGNAFAIDE_URL)
PASS: 4 of 12 checks passed, 8 not checked (nothing co-signed yet)

What is recorded and what is not #

Recorded. A decision before each tool call is forwarded and an outcome when the answer comes back, including an error, a cancelled call and a server that stops mid-call.
Not recorded. A call the application makes around the gateway leaves no record. The deployment has to make the gateway the only route to those tools: for example, only the gateway holds the credentials of the server behind it.
Fail closed. A call that cannot be recorded is not forwarded. The agent gets an error that says so, and the tool does not run.
Strict. With --strict, or --strict-tools a,b for named tools, a call is forwarded only once the witness has co-signed its decision. Without an API key a strict call is refused with no_key.
The tool list. The gateway writes the server's tool list into the agent's chain as signed notes. That is where the coverage line comes from. It is the program's own statement of its tools, not proof that the list is complete.
Evidence, not certification. Records prove integrity and timing, not that a decision was right. Nothing is sent until you run npx signafaide init, and then only salted hashes unless you add --store-content.

Next: the gateway's options, remote servers and what an auditor sees. Tool coverage