Skip to main content

Gateway middleware

Run your own JavaScript on tool traffic. Middleware is a customer-authored function that MintMCP executes in a sandboxed JavaScript runtime on every matching tool call, so you can apply real logic (an external lookup, a vendor classifier, an argument rewrite) where a declarative Agent Monitor rule isn't expressive enough.

Middleware attaches to two surfaces:

  • Virtual MCP (VMCP) tool calls: runs before the call reaches the upstream connector, and optionally after the connector returns. Attach to a Virtual MCP or to a specific connector within one.
  • Agent Monitor hook events: runs on coding-agent hook events (prompt, preTool, postTool) from Claude Code and Cursor.

A single middleware definition can attach to either surface or both. Middleware is available on the Enterprise plan.

When to use middleware​

Rules and middleware coexist: both apply to the same traffic, and either can block. Prefer a rule for simple cases because middleware is heavier.

Use a rule whenUse middleware when
The decision is pattern-based on tool name, argument values, or prompt content.You need to transform arguments or results (redact, rewrite, clip, synthesize).
The action is one of: allow, block, notify, flag.The decision needs real logic: look up an allowlist, parse structured input, call an external classifier.
You need resource-level access control beyond static regex.
You want to mask a result rather than block the call, so the agent sees a sanitized version and keeps working.
You want to route tool calls through an external detection or classification service.

For resource-level access control (a blocklist of databases or tables that is long, changes frequently, or lives in an external system), middleware can fetch the current list at call time and structurally inspect tool arguments, instead of pattern-matching the whole argument blob with a regex.

PII and DLP detection​

PII and DLP detection runs through middleware, which connects tool traffic to the classifier your organization already trusts (AWS Bedrock Guardrails, Google Cloud Model Armor, OpenAI moderation, or Teleskope) and keeps policy ownership in the tool your security or compliance team already runs. Block and mask variants ship as starter templates: block variants reject the call outright, while mask variants substitute the classifier's redacted output so the call continues with sanitized content.

The integration is an HTTP call from the sandbox, so any DLP, classification, or moderation service with an API-accessible endpoint works, including an internal classifier your team already runs. The named vendors ship as templates; anything else is a few lines of JavaScript on the same pattern.

How middleware runs​

Each middleware runs in one of two phases and returns a decision:

  • Pre-phase runs before the upstream call. It can allow the call, block it with a reason the agent sees, or mask the arguments so the upstream receives a rewritten version.
  • Post-phase runs after the upstream call returns. It can allow the result through, block it, or mask it so the agent sees a sanitized version.

The middleware body is plain JavaScript with the tool call's context in scope. A masking middleware is a few lines:

const args = { ...ctx.arguments };
if (typeof args.email === "string") {
  args.email = "[REDACTED]";
}
return { action: "mask", maskedArguments: args };

The sandbox provides fetch to hostnames you allowlist, built-in helpers for calling OpenAI and AWS-signed APIs, and named secrets attached to the definition, so middleware can consult external services without holding credentials in code. Originals are preserved in the audit log even when a call is masked, and secret values are scrubbed from logs automatically.

If a middleware throws or times out, the call fails according to the definition's configured failure behavior: fail-closed blocks the tool invocation, fail-open passes it through unchanged. For policy-critical checks, fail closed, because an outage in your lookup service shouldn't let unchecked calls through.

On Agent Monitor hook events, the agent's own hook protocol carries the decision back, so mask support varies by agent and hook version. See the block and mask support matrix. Prompts can't be rewritten mid-flight (a mask on the prompt event blocks instead), and post-tool blocking isn't possible because the tool has already run.

Starter templates​

The admin UI ships templates you can pick from when creating a new middleware: use the Template dropdown in the edit sheet. Each template prefills the recommended phase and allowed-domains list, so you adjust the IDs, prompts, or thresholds and attach it to your VMCP.

NamePhaseWhat it does
SharePoint drive allowlistPreRestricts SharePoint MCP tools to a set of drive IDs. Calls whose drive_id isn't allowlisted are blocked; list_drives stays open so users can discover IDs.
OpenAI jailbreak detectionPre/PostSends tool arguments and responses to an OpenAI model screening for prompt injection and adversarial inputs. Blocks high-confidence flags and surfaces the model's reason.
OpenAI content moderationPreRuns tool arguments through OpenAI's moderation API and blocks calls that hit any policy category. Matched categories are returned as the block reason.
AWS Bedrock guardrails (block)Pre/PostSends arguments and responses to an AWS Bedrock Guardrail and blocks flagged calls, so you reuse existing Bedrock content policies on MCP traffic.
AWS Bedrock guardrails (mask)Pre/PostSame guardrail call, but replaces flagged content with the guardrail's redacted output instead of blocking, which is useful for PII masking that lets the call continue.
Google Cloud Model Armor (block)Pre/PostScreens tool calls through Model Armor for PII redaction, prompt injection detection, and content safety. Authenticates with a GCP service account JSON key.
Google Cloud Model Armor (mask)Pre/PostRuns arguments and results through a Model Armor template with SDP Advanced plus a linked DLP inspect template, locally masking matched value spans instead of blocking. Mask-only: PI/jailbreak, malicious URL, and RAI filter matches are ignored.
Google Drive folder allowlist (parent only)PreRestricts Drive tools (create_folder, copy_file, search_files) to parent folder IDs. Only direct parents match (not transitive), and get_file stays unguarded because a file_id alone can't be tied to a folder without a Drive API lookup.
Slack channel allowlistPreRestricts Slack MCP tools to a set of channel IDs. Search and list tools stay open.
Teleskope PII/PCI redactionPre/PostSends arguments and results through Teleskope's /v1/scrub API and substitutes the redacted payload when any in-scope PII, PCI, or banking class fires. Out-of-scope detections pass through unchanged.

Create, test, and attach middleware​

  1. Open Guardrails → Middleware and click New middleware.
  2. Pick a template or write the body, and set the phase.
  3. Declare the allowed domains your middleware calls and attach any secrets it reads. Middleware secrets live on the definition and are separate from secret providers.
  4. Set attachments: Virtual MCPs (or specific connectors within them), Agent Monitor hook rules (which pin a definition and version, select hook events, and run in enforce or dryrun mode), or both.
  5. Test with the built-in harness: supply sample arguments (and a sample result for post-phase) and check what your middleware returns, with logs.
  6. Save. Each save produces a new version, attachments pin to a version, and you can roll back or disable a definition without deleting it.

dryrun mode evaluates the middleware and logs the decision without enforcing, so you can stage a new policy against real traffic before flipping to enforce. Every execution's logs and decision land in the audit trail for the tool call.

The Admin MCP covers the full loop: author and version the definition with create_gateway_middleware, then activate it with a rule that references it (create_rule). An agent can draft the JavaScript body, test it, and attach it to the right VMCP or hook event without leaving the chat.