Output Gate: JS policies for MCP tool calls
The Output Gate is ToolMesh’s content control layer. JavaScript policies run before (pre) and after (post) every tool execution, enabling input validation, output filtering, and PII redaction.
How It Works
Section titled “How It Works”Gate policies are top-level JavaScript files in the policies/ directory. They are executed by goja, a Go-native JavaScript engine, with a 5-second timeout per policy.
Each policy receives a single global variable named ctx and runs in one of two phases:
pre— before the tool executes. Mutatectx.paramsto rewrite the request, orthrowto reject it.post— after the tool executes. Mutatectx.response.contentto filter the response.
Throwing a string or Error rejects the call. If the script completes without throwing, the call is allowed.
ctx reference
Section titled “ctx reference”| Field | Description |
|---|---|
ctx.phase | "pre" or "post" |
ctx.tool | Tool name with backend prefix (e.g. github_merge_pull) |
ctx.toolAccess | DADL access tag: "read", "write", "admin", "dangerous", or empty |
ctx.params | Tool parameters (mutate in pre to rewrite); for REST tools checked against their DADL types, see What policies see |
ctx.response.content | Tool response (mutate in post to filter; only populated in post) |
ctx.user.userID | Authenticated user identifier |
ctx.user.callerId | Caller identity (e.g. cli, claude-desktop) |
ctx.user.callerClass | "trusted", "standard", or "untrusted" |
ctx.user.roles | Array of user role strings |
ctx.kits | The kits the caller holds, whole or in part, by name; an empty array without any |
ctx.kitCovered | true when one of them covers the tool |
ctx.rateLimitExceeded(n) | Function — returns true if the user exceeded n calls/hour |
What policies see
Section titled “What policies see”For tools of REST backends, the parameters in ctx.params have passed the check against their declared DADL types before any policy runs, so a policy sees what the API receives:
- A value of the wrong type never reaches a policy. The call is refused with
invalid_inputfirst: a boolean given as the string"false", for example. - Numeric strings for
integerandnumberparameters arrive as numbers ("007"becomes7). An integer beyond 2^53 stays a string to keep it exact, so write numeric comparisons asNumber(ctx.params.x). - Defaults declared in the DADL are filled in, so a policy sees them even when the caller left the parameter out.
- A number or boolean given for a
stringparameter arrives as the exact text the API receives ("42", not42). - Only top-level parameters are checked. Values nested inside an object or array parameter arrive as the caller sent them.
Tools of MCP backends and units are not checked against a declaration: their policies see the caller’s arguments, which are also what the MCP server receives. Nested api.* calls inside a composite go through the pre-execution phase as well.
Examples
Section titled “Examples”Reject dangerous parameters (pre)
Section titled “Reject dangerous parameters (pre)”if (ctx.phase === "pre" && ctx.params.force_delete === true) { throw "force_delete is blocked by policy";}Redact PII from responses (post)
Section titled “Redact PII from responses (post)”if (ctx.phase === "post" && ctx.response && ctx.response.content) { for (var i = 0; i < ctx.response.content.length; i++) { var block = ctx.response.content[i]; if (block && block.type === "text" && block.text) { block.text = block.text.replace( /[\w.-]+@[\w.-]+\.\w+/g, "[REDACTED]" ); } }}Mutations on ctx.response.content propagate back to the live response — downstream evaluators and the executor see the redacted content.
Strip Co-Authored-By from GitHub PRs (pre)
Section titled “Strip Co-Authored-By from GitHub PRs (pre)”Many AI coding agents append Co-Authored-By trailers to commit messages and PR descriptions. A pre-gate policy can strip them before the GitHub API call:
if (ctx.phase === "pre") { var coAuthorPattern = /^[Cc]o-[Aa]uthored-[Bb]y:.*$/gm;
function stripTrailer(text) { if (!text) return text; return text .replace(coAuthorPattern, "") .replace(/\n{3,}/g, "\n\n") .replace(/\n+$/, "\n"); }
if (ctx.tool === "github_create_pull" || ctx.tool === "github_update_pull") { if (ctx.params.body) { ctx.params.body = stripTrailer(ctx.params.body); } } if (ctx.tool === "github_merge_pull" && ctx.params.commit_message) { ctx.params.commit_message = stripTrailer(ctx.params.commit_message); } if (ctx.tool === "github_create_git_commit" && ctx.params.message) { ctx.params.message = stripTrailer(ctx.params.message); }}The AI agent never notices the change, and no Co-Authored-By line reaches your repository.
Read-only enforcement for untrusted callers (pre)
Section titled “Read-only enforcement for untrusted callers (pre)”if (ctx.phase === "pre" && ctx.user.callerClass === "untrusted" && ctx.toolAccess !== "read") { throw "Caller class 'untrusted' may only execute read-tagged tools";}This relies on the DADL access tag (read, write, admin, dangerous) declared per tool — see the DADL spec.
Caller class against access class (pre)
Section titled “Caller class against access class (pre)”The ToolMesh repository ships config/policies/examples/prod-access-by-caller-class.js: a pre-execution policy that lets a call through only when the caller’s class (from caller-classes.yaml) may use the tool’s DADL access class, and denies unknown classes and unclassified tools with a reason that names tool and class. Copy it next to your policies and edit the table at its top. discover_tools and toolmesh.describe() show the access field of a tool, so an agent can see what its class may use before it calls. Like every policy without the directive below, it yields to a kit the caller holds.
Policies and kits
Section titled “Policies and kits”A caller may hold a kit, a bundle of tools that a person granted for a limited time. For a call that a held kit covers, ToolMesh skips every pre-execution policy except those that declare, in the comment lines at the top of the file before the first line of code:
// toolmesh: enforce-with-kit- Without the directive a policy yields to a kit. This is the default and the right choice for rules at tool granularity, such as a read-only posture or a caller class that may not use write tools: an approver has decided for this caller and this kit.
- With the directive a policy is enforced with a kit: it runs whether or not a kit covers the tool. Use it for parameter filters and for conditions that narrow what a scope allows, such as refusing a force-push to
mainor turning a device off. A kit grants the tools, not every argument.
The post-execution phase runs every policy regardless, so masking and field filters apply to kit holders too. The start log names the choice per policy (loaded policy name=readonly_gate.js pre_gate_with_kit=skipped), and a call in which a kit replaced the gate is logged as kit replaces the pre-execution gate; its audit entry carries kit_applied and gate_skipped. Among the shipped examples, default.js, github-branch-protection.js and shelly_write_protection.js carry the directive. Denies in config/authz.yaml decide before any policy runs and win over every kit.
Policies see the kits through ctx.kits (the kits the caller holds, by name) and ctx.kitCovered (true when one of them covers the tool).
CallerClass-Based Filtering
Section titled “CallerClass-Based Filtering”The gate receives the CallerClass, enabling tiered policies:
| CallerClass | Typical Filtering |
|---|---|
trusted | Credentials only |
standard | High-risk PII + credentials |
untrusted | All PII patterns, read-only tools |
Rate Limiting
Section titled “Rate Limiting”Policies can enforce a sliding-window rate limit per user:
if (ctx.phase === "pre" && ctx.rateLimitExceeded(100)) { throw "Rate limit exceeded (100/hour)";}Configuration
Section titled “Configuration”GATE_EVALUATORS=goja # Enable goja evaluator (default)TOOLMESH_POLICIES_DIR=/app/policies # The policies directory; the shipped docker-compose.yml mounts ./config/policies thereToolMesh loads the policies at startup: one line loaded policy per file, and a warning for every tool-name literal in a policy that matches no registered tool.
Enterprise: Compliance-LLM
Section titled “Enterprise: Compliance-LLM”The enterprise extension adds an LLM-based gate evaluator that classifies content against compliance rules. This enables policies like “block responses containing financial advice” without writing regex patterns.