Every tool call is checked before it reaches your tools.

Install and run it in five steps

You need Node.js 20 or newer.

1. Install the proxy and the approval command, noa-approve:

   npm install -g noa-mcp-proxy noa-mcp-adapter-core

2. Name three of your server’s tools: one to allow, one that runs only after a person approves it, and one to block. Every other tool is denied. This writes the policy, the approval rule and the approver keys into the noa folder, and prints the start command and an MCP config to paste, both with absolute paths:

   noa-mcp-proxy init --dir noa --allow-tool search_docs --approval-tool refund --block-tool delete_all

3. Start the proxy in front of your server with the start command init printed, which has full paths. Everything after -- is your server’s own command. With the paths shortened, it reads:

   noa-mcp-proxy --policy noa/policy.json --approval-rules noa/approval-rules.json --pending-store noa/pending-store.jsonl --approver-keyring noa/approver-keyring.json --key-file noa/proxy-key.json --keyring-file noa/keyring.json --receipt-log noa/decisions.jsonl --outcome-log noa/outcomes.jsonl -- node your-server.js

4. A held refund call returns an error carrying a receipt id. A person approves it from a separate terminal, then the agent retries the identical call; approving does not run anything by itself:

   noa-approve approve --id <receiptId> --by you@example.com --pending-store noa/pending-store.jsonl --key-file noa/approver-key.json

5. Check the outcome receipts offline. Exit code 0 means VALID, 2 TAMPERED, 3 MALFORMED and 4 a usage error:

   noa-mcp-proxy verify-outcome noa/outcomes.jsonl --keyring noa/keyring.json

init only writes starter files; it does not switch protection on. Nothing is protected until your MCP host starts the proxy with these files, the tool names are your own, a person runs noa-approve for each held call, and the agent retries the identical call.

Required rules for your setup

1. Always pass your own --policy file. Without it the proxy runs a built-in demo policy written for its demo server, and prints a warning at every start.
2. Name every tool that needs approval in both policy.json and approval-rules.json. The proxy refuses to start when an approval rule names a tool the policy does not (POLICY_APPROVAL_MISMATCH).
3. Approvals need three flags together: --approval-rules, --pending-store and --approver-keyring. The proxy refuses to start when either of the first two is given without trusted approver keys.
4. Keep the policy, rule and key files in a folder that only the operator can write, all the way up the path, and pass full paths, as in the command init prints. The proxy refuses a policy or approval file that is a symlink or that others can write, but it cannot see a swapped parent folder.
5. Point your MCP host at the proxy, never straight at the tool server.

The policy file

--policy takes a noa.policy/0.2 file. The first rule that matches decides, and a call that no rule matches is denied.

{
  "spec": "noa.policy/0.2",
  "id": "my-tools-v1",
  "requiredPaths": ["action"],
  "rules": [
    { "id": "allow-search_docs", "when": { "op": "eq", "path": "action", "value": "search_docs" }, "then": "ALLOW" },
    { "id": "small-refunds-only", "when": { "op": "and", "clauses": [
        { "op": "eq", "path": "action", "value": "refund" },
        { "op": "lt", "path": "args.amountMinor", "value": 10000 } ] }, "then": "ALLOW" }
  ]
}

• •action is the tool name; args.<name> is a tool argument (nested: args.a.b). Numbers must be integers.
• •Operators: eq ne lt le gt ge (with value), in (values), exists absent, and or (clauses) and not (clause). A verdict is ALLOW or DENY.
• •The format is closed: an unknown or duplicate key is an error, so comments are not possible.
• •The file is read once, at start: an edit takes effect only after a restart.
• •If the file cannot be used, the proxy does not start. It exits with code 1 and one error line that names the file, the field and the fix. The line starts with one of four stable codes: POLICY_UNREADABLE, POLICY_UNPARSABLE, POLICY_INVALID or POLICY_APPROVAL_MISMATCH.

Check the receipts

There are two kinds of receipt, and each has its own checker.

Outcome receipts (noa.mcp.outcome/0.1, written with --outcome-log) are checked with noa-mcp-proxy verify-outcome, as in step 5.

Decision receipts (noa.receipt/0.1, written with --receipt-log) are checked with the noa command from the noa-receipt package:

noa verify <receipts.json> --keyring <keyring.json>

noa-receipt 0.9.0 on npm

That command reads one JSON array, not one receipt per line, so put the log’s lines inside one [ ... ] array first. Its keyring must hold every key that signed the chain: the proxy’s key from noa/keyring.json and, when a call was approved, the approver’s key from noa/approver-keyring.json, merged into one JSON object.

VALID means every line is a genuine, signed outcome receipt, each for a different decision. It does not prove the log is complete: a deleted line leaves no trace. The same decision’s outcome appearing twice is TAMPERED.

Optional: keep the signing key in its own process

By default the proxy holds its private signing key inside its own process: a new key at every start, or a saved one with --key-file.

noa-signer-sidecar moves the key into a separate process. The proxy asks it for signatures over a local Unix socket meant only for this machine; exposing that socket beyond it, for example through a container mount or an SSH forward, is outside the sidecar’s threat model: do not do it. Start it like this:

npm install -g noa-signer-sidecar
mkdir -p -m 700 /path/to/private-dir
noa-signer-sidecar --key-file /path/to/private-dir/key.json --socket /path/to/private-dir/signer.sock

Then start the proxy with this flag instead of --key-file:

--signer-socket /path/to/private-dir/signer.sock

• •The socket’s folder must already exist with mode 0700, open only to you; the sidecar refuses to start otherwise. It checks this at startup, not continuously: loosening the folder later is not noticed.
• •--signer-socket and --key-file cannot be used together.
• •If the sidecar cannot be reached at start, the proxy does not start; if the sidecar stops during a session, each call fails closed.
• •This is process isolation, not a hardware security module: root, or the same operating-system user, can still read the key file or the sidecar’s memory.
• •The sidecar signs whatever it is asked to sign: anyone who can connect to the socket can get a valid signature.
• •Key rotation is not built into the sidecar.

What the proxy does not do

• •It does not check a call’s arguments against the tool’s own input schema; your tool server must still reject malformed input.
• •It does not prove a receipt log is complete: a deleted line leaves no trace.
• •A receipt does not prove that the action it describes actually happened; that proof comes from the system that performs the action.
• •An approval shows that a trusted key approved; it does not prove the person understood what they approved.
• •It does not stop someone who can rewrite its rule files in place as the same user: an empty rule list is valid and holds nothing.
• •It does not protect against an attacker who controls the proxy process itself.

It is not the NOA Mandate guarantee on its own. That guarantee needs all four no-back-door rules, including a vault that checks Noa’s approval at its own lock.

Read NON-CLAIMS.md before you rely on the proxy for anything that matters.

Status, checked 2026-10-06: noa-mcp-proxy 0.5.0 and noa-mcp-adapter-core 0.5.0 are published on npm as open source (Apache-2.0), and noa-signer-sidecar 0.1.0 is an optional add-on.

Packages and source

• noa-mcp-proxy 0.5.0 on npm
• noa-mcp-adapter-core 0.5.0 on npm
• noa-signer-sidecar 0.1.0 on npm
• noa-mcp-proxy README on GitHub
• noa-signer-sidecar README on GitHub
• NON-CLAIMS.md on GitHub: what NOA does not do

The source links point to the exact public commit this guide was written from.