@multiagentcoordinationprotocol/mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/multiagentcoordinationprotocol/macp-mcp-typescript/compare/v0.2.0...v0.3.0) (2026-10-25)
+
+
+### Features
+
+* **gate:** macp-mcp gate — quorum-gated upstream tool calls (W3.8) ([#5](https://github.com/multiagentcoordinationprotocol/macp-mcp-typescript/issues/5)) ([503f5f4](https://github.com/multiagentcoordinationprotocol/macp-mcp-typescript/commit/503f5f413ee77de1d95d9e7802f647313d6e1df7))
+
 ## [0.2.0](https://github.com/multiagentcoordinationprotocol/macp-mcp-typescript/compare/v0.1.0...v0.2.0) (2026-10-25)
 
 

package/README.md

@@ -6,6 +6,8 @@ session. It is the TypeScript twin of the Python
 [macp-mcp](https://github.com/multiagentcoordinationprotocol/macp-mcp). Both
 expose the same tool surface: the same names, input schemas and outputs,
 pinned by one shared manifest ([Tool contract](#tool-contract)).
+Package versions are independent of the Python macp-mcp; tool parity is
+enforced by `make verify-contract`, not by matching version numbers.
 
 MCP decides which tools a model can call. MACP decides who may use them and
 when, and records what was decided. The model drives every step through
@@ -69,8 +71,8 @@ claude mcp add macp \
   -- npx -y @multiagentcoordinationprotocol/mcp
 ```
 
-Then ask the model something like: *"Start a MACP decision with alice on
-which deployment plan to use, propose a canary rollout, and vote for it."*
+Then ask the model something like: _"Start a MACP decision with alice on
+which deployment plan to use, propose a canary rollout, and vote for it."_
 
 ### Against a production runtime
 
@@ -89,31 +91,31 @@ this agent:
 
 These are the same variables, with the same defaults, as the Python server.
 
-| Variable | Default | Meaning |
-|---|---|---|
-| `MACP_RUNTIME_TARGET` | `127.0.0.1:50051` | Runtime gRPC address (`host:port`). |
-| `MACP_AGENT_ID` | `mcp-agent` | The MACP agent this server acts as. With dev-agent auth it is also the bearer token. With `MACP_AUTH_TOKEN` it is the identity the runtime must bind the token to. |
-| `MACP_AUTH_TOKEN` | unset | Bearer token issued by the runtime. When unset, dev-agent auth is used, which needs a runtime started with `MACP_ALLOW_INSECURE=1`. |
-| `MACP_ALLOW_INSECURE` | off | `1`/`true`/`yes`/`on` uses plaintext gRPC. For a local runtime only. |
-| `MACP_TLS_CA_FILE` | system trust | PEM bundle for a private CA. Cannot be combined with `MACP_ALLOW_INSECURE`. |
-| `MACP_DEFAULT_TTL_MS` | `300000` | Session TTL used when `start_session` is called without `ttl_ms`. |
-| `MACP_REPLAY_IDLE_MS` | `1000` | How long a history read waits for the next envelope before treating the replay as complete. |
+| Variable              | Default           | Meaning                                                                                                                                                            |
+| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MACP_RUNTIME_TARGET` | `127.0.0.1:50051` | Runtime gRPC address (`host:port`).                                                                                                                                |
+| `MACP_AGENT_ID`       | `mcp-agent`       | The MACP agent this server acts as. With dev-agent auth it is also the bearer token. With `MACP_AUTH_TOKEN` it is the identity the runtime must bind the token to. |
+| `MACP_AUTH_TOKEN`     | unset             | Bearer token issued by the runtime. When unset, dev-agent auth is used, which needs a runtime started with `MACP_ALLOW_INSECURE=1`.                                |
+| `MACP_ALLOW_INSECURE` | off               | `1`/`true`/`yes`/`on` uses plaintext gRPC. For a local runtime only.                                                                                               |
+| `MACP_TLS_CA_FILE`    | system trust      | PEM bundle for a private CA. Cannot be combined with `MACP_ALLOW_INSECURE`.                                                                                        |
+| `MACP_DEFAULT_TTL_MS` | `300000`          | Session TTL used when `start_session` is called without `ttl_ms`.                                                                                                  |
+| `MACP_REPLAY_IDLE_MS` | `1000`            | How long a history read waits for the next envelope before treating the replay as complete.                                                                        |
 
 The server logs to stderr only, because stdout carries the MCP protocol. A bad
 configuration exits with status 2 and a one-line message.
 
 ## Tools
 
-| Tool | Kind | What it does |
-|---|---|---|
-| `start_session` | write | Start a Decision session with this agent as initiator. Takes `intent`, `participants` and optional `ttl_ms` and `context_id`. Returns the `session_id` to share. |
-| `propose` | write | Put an option (`proposal_id`, `option`, `rationale`) up for decision. |
-| `evaluate` | write | Record a scored assessment (`APPROVE` / `REVIEW` / `BLOCK` / `REJECT`, confidence 0..1) before voting. |
-| `vote` | write | Cast this agent's `APPROVE` / `REJECT` / `ABSTAIN` vote on a proposal. |
-| `commit` | write | Resolve the session with a binding Commitment (`action`, `authority_scope`, `reason`). Under the default policy only the initiator can commit. |
-| `get_session` | read | The session's state, participants, proposals, evaluations, votes, approve totals and majority winner. |
-| `get_commitment` | read | The resolved session's binding Commitment, the exact payload bytes (`payload_b64`) and its RFC-MACP-0013 `commitment_hash`. |
-| `verify` | read | Recompute a commitment hash with the SDK verifier, either from the runtime's recorded history (`session_id`) or from bytes you hold (`payload_b64`). Returns `match`, `mismatch` or `cannot_verify`. |
+| Tool             | Kind  | What it does                                                                                                                                                                                         |
+| ---------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start_session`  | write | Start a Decision session with this agent as initiator. Takes `intent`, `participants` and optional `ttl_ms` and `context_id`. Returns the `session_id` to share.                                     |
+| `propose`        | write | Put an option (`proposal_id`, `option`, `rationale`) up for decision.                                                                                                                                |
+| `evaluate`       | write | Record a scored assessment (`APPROVE` / `REVIEW` / `BLOCK` / `REJECT`, confidence 0..1) before voting.                                                                                               |
+| `vote`           | write | Cast this agent's `APPROVE` / `REJECT` / `ABSTAIN` vote on a proposal.                                                                                                                               |
+| `commit`         | write | Resolve the session with a binding Commitment (`action`, `authority_scope`, `reason`). Under the default policy only the initiator can commit.                                                       |
+| `get_session`    | read  | The session's state, participants, proposals, evaluations, votes, approve totals and majority winner.                                                                                                |
+| `get_commitment` | read  | The resolved session's binding Commitment, the exact payload bytes (`payload_b64`) and its RFC-MACP-0013 `commitment_hash`.                                                                          |
+| `verify`         | read  | Recompute a commitment hash with the SDK verifier, either from the runtime's recorded history (`session_id`) or from bytes you hold (`payload_b64`). Returns `match`, `mismatch` or `cannot_verify`. |
 
 Errors the model can act on, such as a runtime rejection or a bad argument,
 come back as tool errors with the text `"<CODE>: <message>"`, for example
@@ -124,6 +126,87 @@ the gRPC status name.
 The server is stateless. Every read replays the session from the runtime, so a
 restart loses nothing, and several servers (agents) can share one session.
 
+## Gate upstream tool calls (`macp-mcp gate`)
+
+`macp-mcp gate` is a second mode of the same binary. It runs as an MCP server
+in front of another (upstream) MCP server, and puts the tool calls you name
+behind a MACP session: a matching call reaches the upstream only after a
+Quorum or Decision session commits `approve`. Every other call passes straight
+through.
+
+```bash
+macp-mcp gate --policy gate.json --upstream npx -y @modelcontextprotocol/server-filesystem /srv/data
+```
+
+`--upstream` takes the rest of the command line as the upstream's stdio
+command. The gate uses the same environment variables as the base server
+(`MACP_AGENT_ID` is the gate's identity: it initiates and commits every
+session). The upstream inherits the gate's environment minus
+`MACP_AUTH_TOKEN`, so the gate's credential never reaches it.
+
+`gate.json` names the rules; the first rule whose `tool` matches wins (exact
+name, or a glob with `*` and `?`):
+
+```json
+{
+  "version": 1,
+  "server": "filesystem",
+  "rules": [
+    { "tool": "write_*", "mode": "macp.mode.quorum.v1", "participants": ["alice", "bob", "carol"], "threshold": 2 },
+    { "tool": "move_file", "mode": "macp.mode.decision.v1", "participants": ["alice", "bob"], "ttl_ms": 60000 }
+  ]
+}
+```
+
+| Field            | Meaning                                                                                           |
+| ---------------- | ------------------------------------------------------------------------------------------------- |
+| `server`         | The upstream's name, bound into every gated call's `context_id`.                                  |
+| `tool`           | Exact tool name or glob.                                                                          |
+| `mode`           | `macp.mode.quorum.v1` (ApprovalRequest + ballots) or `macp.mode.decision.v1` (Proposal + votes).  |
+| `participants`   | The approvers. Must not include the gate's own agent id.                                          |
+| `threshold`      | APPROVE ballots needed, in either mode. Default: a strict majority of `participants`.             |
+| `ttl_ms`         | Session TTL. Default `300000`.                                                                    |
+| `policy_version` | Optional RFC-MACP-0012 policy to bind the session to, for example one of the spec's policy packs. |
+
+For a gated call the gate:
+
+1. Starts a session whose `context_id` is `sha256:` + the hex SHA-256 of the
+   RFC 8785 (JCS) form of `{"arguments", "server", "tool"}`. The same canonical
+   JSON travels in the ApprovalRequest `details` (Quorum) or the Proposal
+   `rationale` (Decision), so an approver can recompute the binding.
+2. Commits `approve` as soon as the approvers' latest ballots reach the
+   threshold, or `deny` as soon as they no longer can (REJECT and ABSTAIN both
+   count as not-approve).
+3. On `approve`, forwards the call and adds the commitment to the result,
+   beside any `_meta` the upstream set:
+
+   ```json
+   "_meta": {
+     "io.multiagentcoordinationprotocol/commitment": {
+       "session_id": "…", "mode": "macp.mode.quorum.v1", "outcome": "approve",
+       "commitment_hash": "sha256:…"
+     }
+   }
+   ```
+
+   `commitment_hash` is the RFC-MACP-0013 hash; the base server's `verify`
+   tool recomputes it from the runtime's history.
+
+4. Otherwise refuses with a tool error, and never calls the upstream:
+   `POLICY_DENIED: …` when the session commits `deny` (or a bound policy
+   refuses the commitment), `SESSION_NOT_OPEN: …` when the session expires or
+   is cancelled without a commitment. If the session is still open 5 s after
+   its TTL, the gate cancels it. A call whose arguments hold an integer
+   outside ±(2^53−1) is refused with `INVALID_ARGUMENT: …` before any session
+   opens: JSON may already have rounded it, so it has no canonical form.
+
+Approvers are ordinary MACP agents, for example a base `macp-mcp` server
+driven by a person or another model, voting through the runtime. See
+[examples/gated-tool-call.md](examples/gated-tool-call.md) for a full
+transcript. The policy schema, CLI flags, wire values and `context_id` test
+vectors live in [`contract/gate/`](contract/gate), byte-identical to the
+Python macp-mcp's.
+
 ## Tool contract
 
 [`contract/tools.json`](contract/tools.json) pins the tool names,
@@ -135,7 +218,8 @@ arguments against it with Ajv, so the advertised surface cannot drift from
 the file. The file also ships in the npm package as
 `@multiagentcoordinationprotocol/mcp/contract/tools.json`.
 
-CI fails if the copy drifts from the Python repo's (`make verify-contract`).
+The gate's contract (`contract/gate/`) is vendored the same way. CI fails if
+any of these files drifts from the Python repo's (`make verify-contract`).
 After a deliberate surface change lands in macp-mcp, run `make sync-contract`
 and implement the change here.
 

package/contract/gate/cli.json

@@ -0,0 +1,32 @@
+{
+  "contract_version": "1",
+  "command": "macp-mcp gate",
+  "usage": "macp-mcp gate --policy <gate.json> --upstream <command> [args...]",
+  "flags": [
+    {
+      "name": "--policy",
+      "required": true,
+      "value": "PATH",
+      "description": "The gate.json policy file (contract/gate/gate.schema.json)."
+    },
+    {
+      "name": "--upstream",
+      "required": true,
+      "value": "COMMAND [ARGS...]",
+      "description": "The upstream MCP server's stdio command line. Must be the last option: every argument after it belongs to the upstream command."
+    }
+  ],
+  "environment": {
+    "read": ["MACP_RUNTIME_TARGET", "MACP_AGENT_ID", "MACP_AUTH_TOKEN", "MACP_ALLOW_INSECURE", "MACP_TLS_CA_FILE"],
+    "withheld_from_upstream": ["MACP_AUTH_TOKEN"],
+    "note": "The upstream process inherits the gate's environment minus withheld_from_upstream. The gate is the MACP agent MACP_AGENT_ID; it initiates and commits every approval session."
+  },
+  "exit_codes": {
+    "2": "Unusable configuration: bad MACP_* environment, an invalid gate.json, or a missing --upstream command. One line on stderr."
+  },
+  "server": {
+    "name": "macp-mcp-gate",
+    "proxies": ["tools/list", "tools/call"],
+    "instructions": "Some tools on this server are gated by MACP: a call to one opens a MACP session and runs only after the named approvers approve it. A refused call returns an error starting POLICY_DENIED or SESSION_NOT_OPEN; do not retry it unchanged."
+  }
+}

package/contract/gate/context-id-vectors.json

@@ -0,0 +1,164 @@
+{
+  "contract_version": "1",
+  "description": "macp-mcp gate context_id vectors. context_id = \"sha256:\" + lowercase hex SHA-256 of the RFC 8785 (JCS) canonical JSON (UTF-8) of {\"arguments\": input.arguments or {}, \"server\": input.server, \"tool\": input.tool}. preimage is that canonical JSON. Numbers are IEEE-754 doubles, as JSON.parse reads them. A vector with expected_error instead of preimage and context_id is refused with exactly that text, before any session is opened.",
+  "vectors": [
+    {
+      "name": "arguments-absent",
+      "note": "Absent arguments hash as {}.",
+      "input": {
+        "server": "filesystem",
+        "tool": "list_allowed_directories"
+      },
+      "preimage": "{\"arguments\":{},\"server\":\"filesystem\",\"tool\":\"list_allowed_directories\"}",
+      "context_id": "sha256:d79291c4a1ee28e189486c939345523709718be643a11d098f2254eae7b3f63a"
+    },
+    {
+      "name": "spec-worked-example",
+      "note": "The worked example in the spec repo's docs/mcp-tool-gating.md.",
+      "input": {
+        "server": "filesystem",
+        "tool": "write_file",
+        "arguments": {
+          "mode": "w",
+          "path": "/etc/hosts"
+        }
+      },
+      "preimage": "{\"arguments\":{\"mode\":\"w\",\"path\":\"/etc/hosts\"},\"server\":\"filesystem\",\"tool\":\"write_file\"}",
+      "context_id": "sha256:e8272f181497f6286a735f2bd9a2bd535b65e377fc85b6ece9d3a6bac5b73057"
+    },
+    {
+      "name": "simple",
+      "note": "Flat string arguments; keys sorted.",
+      "input": {
+        "server": "filesystem",
+        "tool": "write_file",
+        "arguments": {
+          "path": "/srv/reports/q3.md",
+          "content": "Q3 revenue: up 4%"
+        }
+      },
+      "preimage": "{\"arguments\":{\"content\":\"Q3 revenue: up 4%\",\"path\":\"/srv/reports/q3.md\"},\"server\":\"filesystem\",\"tool\":\"write_file\"}",
+      "context_id": "sha256:330ccb8df9d72d67b7d4835a591e313b5882bf79f69726d9fbfd06d896d77196"
+    },
+    {
+      "name": "nested",
+      "note": "Nested objects and arrays, booleans and null; array order is kept.",
+      "input": {
+        "server": "github",
+        "tool": "create_issue",
+        "arguments": {
+          "repo": "acme/api",
+          "labels": [
+            "bug",
+            "p1"
+          ],
+          "assignee": null,
+          "draft": false,
+          "body": {
+            "steps": [
+              3,
+              1,
+              2
+            ],
+            "env": {
+              "os": "linux",
+              "arch": "arm64"
+            }
+          }
+        }
+      },
+      "preimage": "{\"arguments\":{\"assignee\":null,\"body\":{\"env\":{\"arch\":\"arm64\",\"os\":\"linux\"},\"steps\":[3,1,2]},\"draft\":false,\"labels\":[\"bug\",\"p1\"],\"repo\":\"acme/api\"},\"server\":\"github\",\"tool\":\"create_issue\"}",
+      "context_id": "sha256:d7f3bdf9be0c206ff4afa7b605f9f3e9b8386a850b76e2933a09f125dc8b1ce2"
+    },
+    {
+      "name": "numbers",
+      "note": "ECMAScript number formatting: 1.0 -> 1, -0.0 -> 0, small exponents, shortest round-trip, the largest safe integer.",
+      "input": {
+        "server": "payments",
+        "tool": "transfer",
+        "arguments": {
+          "amount": 1250.5,
+          "fee": 0.1,
+          "whole": 1.0,
+          "negzero": -0.0,
+          "small": 1.5e-07,
+          "tiny": 1e-07,
+          "edge": 1e-06,
+          "thirds": 333333333.3333333,
+          "max_safe": 9007199254740991,
+          "neg": -42
+        }
+      },
+      "preimage": "{\"arguments\":{\"amount\":1250.5,\"edge\":0.000001,\"fee\":0.1,\"max_safe\":9007199254740991,\"neg\":-42,\"negzero\":0,\"small\":1.5e-7,\"thirds\":333333333.3333333,\"tiny\":1e-7,\"whole\":1},\"server\":\"payments\",\"tool\":\"transfer\"}",
+      "context_id": "sha256:f5b6ab689bbd1d567b0729312865fc20a4666dc39644a65fdc41636740793482"
+    },
+    {
+      "name": "strings-escapes",
+      "note": "Escapes: quote, backslash, \\b \\f \\n \\r \\t, other controls as \\u00XX; DEL, U+2028, U+2029, '/' and non-ASCII stay literal.",
+      "input": {
+        "server": "mail",
+        "tool": "send",
+        "arguments": {
+          "subject": "Re: \"Q3\" \\ final",
+          "body": "line1\nline2\ttab\u0007bell\u0001soh\b\f\rdel
ls
ps",
+          "url": "https://example.com/a/b",
+          "to": "zoë@example.com",
+          "greeting": "שלום 😀"
+        }
+      },
+      "preimage": "{\"arguments\":{\"body\":\"line1\\nline2\\ttab\\u0007bell\\u0001soh\\b\\f\\rdel
ls
ps\",\"greeting\":\"שלום 😀\",\"subject\":\"Re: \\\"Q3\\\" \\\\ final\",\"to\":\"zoë@example.com\",\"url\":\"https://example.com/a/b\"},\"server\":\"mail\",\"tool\":\"send\"}",
+      "context_id": "sha256:fe91dc79441555be100f7e181af5b940e071aeebb8d89eb6bac9127f71f812b9"
+    },
+    {
+      "name": "key-order-utf16",
+      "note": "Keys sort by UTF-16 code units, not code points: U+20AC < U+1F600 (D83D) < U+FB01 < U+FB33.",
+      "input": {
+        "server": "kv",
+        "tool": "put",
+        "arguments": {
+          "דּ": 4,
+          "fi": 3,
+          "😀": 2,
+          "€": 1,
+          "ö": 0,
+          "€": 0,
+          "b": 0,
+          "B": 0,
+          "_": 0,
+          "1": 0,
+          "\r": 0,
+          "": 0
+        }
+      },
+      "preimage": "{\"arguments\":{\"\":0,\"\\r\":0,\"1\":0,\"B\":0,\"_\":0,\"b\":0,\"€\":0,\"ö\":0,\"€\":1,\"😀\":2,\"fi\":3,\"דּ\":4},\"server\":\"kv\",\"tool\":\"put\"}",
+      "context_id": "sha256:199c7c5bcee590b3c55b44e33c1fed2fcfac4b7d4e54e8f76b4ddb3d8d1ef355"
+    },
+    {
+      "name": "unsafe-integer",
+      "note": "An integer outside ±(2^53−1) has no canonical form: JSON.parse may already have rounded it. The call is refused with expected_error; no session is opened.",
+      "input": {
+        "server": "ledger",
+        "tool": "post_entry",
+        "arguments": {
+          "entry_id": 9007199254740993
+        }
+      },
+      "expected_error": "INVALID_ARGUMENT: tool call post_entry arguments contain an integer outside ±(2^53−1), which has no canonical JSON form"
+    },
+    {
+      "name": "unsafe-integer-exponent",
+      "note": "The same holds for an integral value written with an exponent (1e21), here nested in an array.",
+      "input": {
+        "server": "ledger",
+        "tool": "post_entry",
+        "arguments": {
+          "ids": [
+            1,
+            1e+21
+          ]
+        }
+      },
+      "expected_error": "INVALID_ARGUMENT: tool call post_entry arguments contain an integer outside ±(2^53−1), which has no canonical JSON form"
+    }
+  ]
+}

package/contract/gate/example.gate.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "server": "filesystem",
+  "rules": [
+    {
+      "tool": "write_file",
+      "mode": "macp.mode.quorum.v1",
+      "participants": ["alice", "bob", "carol"],
+      "threshold": 2,
+      "ttl_ms": 120000,
+      "policy_version": "policy.packs.two-agent-rule",
+      "description": "Four eyes on every write: two of three reviewers approve."
+    },
+    {
+      "tool": "move_*",
+      "mode": "macp.mode.decision.v1",
+      "participants": ["alice", "bob"],
+      "ttl_ms": 60000,
+      "description": "Moves and renames need a majority vote (2 of 2)."
+    }
+  ]
+}

package/contract/gate/gate.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://multiagentcoordinationprotocol.io/schemas/macp-mcp/gate.schema.json",
+  "title": "macp-mcp gate policy (gate.json)",
+  "description": "Which tool calls on one upstream MCP server need a MACP session, and how that session is run. Rules are tried in order; the first whose tool pattern matches decides. A call that matches no rule is forwarded to the upstream untouched. Loaders also enforce two rules a schema cannot: threshold <= the rule's participant count, and participants never contains the gate's own MACP_AGENT_ID.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "server", "rules"],
+  "properties": {
+    "version": {
+      "description": "gate.json format version.",
+      "const": 1
+    },
+    "server": {
+      "description": "The upstream's configured name. It is the \"server\" member of the context_id preimage, so changing it changes every context_id.",
+      "type": "string",
+      "minLength": 1
+    },
+    "rules": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/rule" }
+    }
+  },
+  "$defs": {
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tool", "mode", "participants"],
+      "properties": {
+        "tool": {
+          "description": "Tool name: an exact name, or a glob where * matches any run of characters (including none) and ? matches exactly one. No other wildcard syntax; matching is case-sensitive and covers the whole name.",
+          "type": "string",
+          "minLength": 1
+        },
+        "mode": {
+          "description": "The MACP mode of the approval session.",
+          "enum": ["macp.mode.quorum.v1", "macp.mode.decision.v1"]
+        },
+        "participants": {
+          "description": "MACP agent ids of the approvers. The gate itself is the session initiator and never one of them.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "threshold": {
+          "description": "APPROVE ballots (Quorum) or votes (Decision) needed to forward the call. Defaults to a strict majority of participants: floor(n/2) + 1. Must not exceed the participant count. With a bound policy that overrides the threshold (for example policy.packs.two-agent-rule), set the same value here.",
+          "type": "integer",
+          "minimum": 1
+        },
+        "ttl_ms": {
+          "description": "Session TTL. A session still open after ttl_ms plus a 5000 ms grace is cancelled by the gate and the call refused.",
+          "type": "integer",
+          "minimum": 1,
+          "default": 300000
+        },
+        "policy_version": {
+          "description": "An RFC-MACP-0012 policy registered with the runtime, bound to the session at SessionStart and evaluated at commitment. The gate must keep commitment authority (initiator_only or any_participant); a designated_role policy such as policy.packs.human-signoff cannot be used. Omitted means the runtime default policy.",
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "description": "Free text for humans; ignored by the gate.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/contract/gate/session.json

@@ -0,0 +1,82 @@
+{
+  "contract_version": "1",
+  "description": "What a gated tool call puts on the MACP wire, and what the MCP caller gets back. Strings with {placeholders} are templates: substitute literally, no other formatting. {server} is gate.json's server, {tool} the tool name, {context_id} and {preimage} as in context-id-vectors.json, {gate} the gate's MACP_AGENT_ID, {threshold} the rule's effective threshold, {session_id} the approval session's id, {state} its SessionState name without the SESSION_STATE_ prefix (EXPIRED, CANCELLED), {runtime_message} the runtime's Ack failure message.",
+  "session_start": {
+    "intent": "Approve MCP tool call {server}/{tool}",
+    "context_id": "{context_id}",
+    "ttl_ms": "rule.ttl_ms",
+    "policy_version": "rule.policy_version, or the runtime default when omitted",
+    "initiator": "{gate}"
+  },
+  "modes": {
+    "macp.mode.quorum.v1": {
+      "participants": "rule.participants",
+      "first_message": {
+        "message_type": "ApprovalRequest",
+        "request_id": "{context_id}",
+        "action": "tools/call:{tool}",
+        "summary": "{server}/{tool}",
+        "details": "UTF-8 bytes of {preimage}",
+        "required_approvals": "{threshold}"
+      },
+      "ballots": "The first Approve / Reject / Abstain from each approver for request_id {context_id} counts (the runtime rejects a second one); Approve is an approval."
+    },
+    "macp.mode.decision.v1": {
+      "participants": "[{gate}] followed by rule.participants; the gate never votes and is not counted",
+      "first_message": {
+        "message_type": "Proposal",
+        "proposal_id": "call",
+        "option": "tools/call:{tool}",
+        "rationale": "{preimage}"
+      },
+      "ballots": "The first Vote from each approver on proposal_id call counts (the runtime rejects a second one); APPROVE (case-insensitive) is an approval, REJECT and ABSTAIN are not."
+    }
+  },
+  "outcome": {
+    "approve_when": "approvals >= {threshold}",
+    "deny_when": "approvals + approvers_yet_to_vote < {threshold}",
+    "counted": "Only ballots from rule.participants."
+  },
+  "commitment": {
+    "approve": {
+      "action": "macp.gate.approve",
+      "outcome_positive": true
+    },
+    "deny": {
+      "action": "macp.gate.deny",
+      "outcome_positive": false
+    },
+    "authority_scope": "tools/call:{server}/{tool}",
+    "reason": "Free text; not part of the contract.",
+    "reported": "The Commitment envelope the runtime records for the session (its payload bytes are what commitment_hash covers)."
+  },
+  "forwarded_result": {
+    "meta_key": "io.multiagentcoordinationprotocol/commitment",
+    "meta_value": {
+      "session_id": "the approval session id",
+      "mode": "rule.mode",
+      "outcome": "approve",
+      "commitment_hash": "RFC-MACP-0013 hash of the recorded Commitment payload"
+    },
+    "note": "Added to the upstream's CallToolResult _meta; every key the upstream set is preserved. outcome is \"approve\" or \"deny\"; only forwarded calls carry the key, so it is always \"approve\" there."
+  },
+  "refusals": {
+    "note": "The upstream is never called. The result is an MCP tool error (isError: true) whose only content is one text block with exactly the rendered template.",
+    "templates": {
+      "denied": "POLICY_DENIED: tool call {tool} denied by session {session_id}",
+      "policy_denied": "POLICY_DENIED: {runtime_message}",
+      "not_open": "SESSION_NOT_OPEN: session {session_id} ended {state} without a commitment",
+      "unsafe_integer": "INVALID_ARGUMENT: tool call {tool} arguments contain an integer outside ±(2^53−1), which has no canonical JSON form"
+    },
+    "cases": {
+      "denied": "The session committed outcome_positive = false (the threshold became unreachable).",
+      "policy_denied": "The runtime rejected the gate's positive Commitment with POLICY_DENIED (a bound RFC-0012 policy); the gate cancels the session.",
+      "not_open": "The session ended EXPIRED or CANCELLED with no Commitment. A session still OPEN at ttl_ms + expiry_grace_ms is cancelled by the gate first, so {state} is CANCELLED there.",
+      "unsafe_integer": "The arguments hold a number that is integral with |v| > 2^53−1 (Python: an int, or a float with is_integer(); TypeScript: Number.isInteger(v) && !Number.isSafeInteger(v)), at any depth. Checked before any session is opened.",
+      "other": "Any other failure (runtime unreachable, a rejected SessionStart, ...) is \"<CODE>: <message>\" with the base server's code precedence: Ack failure code, then the macp-error-code trailer, then the gRPC status name. Not a template; codes and messages vary."
+    }
+  },
+  "timing": {
+    "expiry_grace_ms": 5000
+  }
+}

package/dist/bridge.d.ts

@@ -9,7 +9,7 @@
  * `get_commitment` reflect every participant's messages, not just this
  * agent's. Mirrors the Python macp-mcp `bridge.py` call for call.
  */
-import { MacpClient, type Envelope } from 'macp-sdk-typescript';
+import { MacpClient, type CommitmentPayload, type Envelope } from 'macp-sdk-typescript';
 import { type Settings } from './config';
 import type { CommitAckResult, CommitmentResult, ProposalAckResult, SessionResult, StartSessionResult, VerifyResult, VoteAckResult } from './results';
 /** RFC-MACP-0013 hash label, the `label` part of the hash preimage. */
@@ -26,6 +26,8 @@ export type ClientFactory = (settings: Settings) => BridgeClient;
 export declare function defaultClientFactory(settings: Settings): BridgeClient;
 /** SessionState enum name without the `SESSION_STATE_` prefix (OPEN, RESOLVED, ...). */
 export declare function stateName(state: string | undefined): string;
+/** A decoded CommitmentPayload with proto3 defaults filled in (protobufjs omits them). Commitment is a core message, so any mode decodes it. */
+export declare function decodeCommitment(client: BridgeClient, wire: Buffer): CommitmentPayload;
 /** Decision-mode actions for one MACP agent identity. */
 export declare class MacpBridge {
     readonly settings: Settings;

package/dist/bridge.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MacpBridge = exports.ToolArgumentError = exports.REPLAY_MAX_MS = exports.COMMITMENT_HASH_LABEL = void 0;
 exports.defaultClientFactory = defaultClientFactory;
 exports.stateName = stateName;
+exports.decodeCommitment = decodeCommitment;
 const macp_sdk_typescript_1 = require("macp-sdk-typescript");
 const config_1 = require("./config");
 const version_1 = require("./version");
@@ -56,7 +57,7 @@ function ackDict(ack) {
 function int64(value) {
     return value === undefined || value === '' ? 0 : Number(value);
 }
-/** A decoded CommitmentPayload with proto3 defaults filled in (protobufjs omits them). */
+/** A decoded CommitmentPayload with proto3 defaults filled in (protobufjs omits them). Commitment is a core message, so any mode decodes it. */
 function decodeCommitment(client, wire) {
     const raw = client.protoRegistry.decodeKnownPayload(macp_sdk_typescript_1.MODE_DECISION, 'Commitment', wire) ?? {};
     const str = (key) => (typeof raw[key] === 'string' ? raw[key] : '');

package/dist/cli.d.ts

@@ -1,3 +1,7 @@
 #!/usr/bin/env node
-/** Entry point: `macp-mcp` (stdio transport). stdout carries only the MCP protocol; everything else goes to stderr. */
+/**
+ * Entry point (stdio transport): `macp-mcp` serves the Decision tools;
+ * `macp-mcp gate ...` proxies an upstream MCP server behind gate rules.
+ * stdout carries only the MCP protocol; everything else goes to stderr.
+ */
 export {};

package/dist/cli.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
 "use strict";
-/** Entry point: `macp-mcp` (stdio transport). stdout carries only the MCP protocol; everything else goes to stderr. */
+/**
+ * Entry point (stdio transport): `macp-mcp` serves the Decision tools;
+ * `macp-mcp gate ...` proxies an upstream MCP server behind gate rules.
+ * stdout carries only the MCP protocol; everything else goes to stderr.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const macp_sdk_typescript_1 = require("macp-sdk-typescript");
 const config_1 = require("./config");
+const cli_1 = require("./gate/cli");
 const server_1 = require("./server");
 async function main() {
     // The SDK's default sink sends debug/info to console.log, i.e. stdout; route every level to stderr.
@@ -12,8 +17,15 @@ async function main() {
         sink: (level, args) => process.stderr.write(`[macp-sdk] ${level} ${args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')}\n`),
     });
     let settings;
+    const [command, ...rest] = process.argv.slice(2);
     try {
         settings = (0, config_1.loadSettings)();
+        if (command === 'gate') {
+            process.stderr.write(`macp-mcp gate: agent=${settings.agentId} runtime=${settings.target} ` +
+                `auth=${(0, config_1.authMode)(settings)} tls=${settings.allowInsecure ? 'off' : 'on'}\n`);
+            await (0, cli_1.runGate)(rest, settings);
+            return;
+        }
     }
     catch (err) {
         if (err instanceof config_1.ConfigError) {