Docs for external MCP guardrails by artberger · Pull Request #618 · agentgateway/website

artberger · 2026-06-15T21:14:28Z

Closes #609

Signed-off-by: Art Berger <art.berger@solo.io>

cloudflare-workers-and-pages · 2026-06-15T21:16:38Z

Deploying agentproxy with Cloudflare Pages

Latest commit:	`2a82be6`
Status:	✅ Deploy successful!
Preview URL:	https://e96bd986.agentproxy.pages.dev
Branch Preview URL:	https://adb-extmcp.agentproxy.pages.dev

View logs

Nadine2016 · 2026-06-16T15:39:51Z

@@ -0,0 +1,88 @@
+Use MCP guardrails (also called ExtMCP) to apply external authorization and external processing to Model Context Protocol (MCP) requests. An external gRPC policy server inspects, allows, mutates, or denies individual MCP method calls, such as `tools/call` and `tools/list`, using MCP request context instead of generic HTTP metadata.


Suggested change

Use MCP guardrails (also called ExtMCP) to apply external authorization and external processing to Model Context Protocol (MCP) requests. An external gRPC policy server inspects, allows, mutates, or denies individual MCP method calls, such as `tools/call` and `tools/list`, using MCP request context instead of generic HTTP metadata.

Use MCP guardrails (also called ExtMCP) to apply external authorization and external processing to Model Context Protocol (MCP) requests. An external gRPC policy server inspects, allows, mutates, or denies individual MCP method calls, such as `tools/call` and `tools/list`, by using the MCP request context instead of generic HTTP metadata.

Nadine2016 · 2026-06-16T15:42:41Z

+
+{{< reuse "agw-docs/snippets/agentgateway-capital.md" >}} already supports [external authorization]({{< link-hextra path="/security/extauth/basic" >}}) and [external processing (ExtProc)]({{< link-hextra path="/traffic-management/extproc" >}}) for HTTP traffic. Both call out to an external gRPC server so that you can centralize authorization and request or response mutation outside the proxy. However, these integrations operate on raw HTTP. To make a decision about an MCP tool call, the external server must reassemble the HTTP body, parse the JSON-RPC envelope, and handle MCP framing itself.
+
+MCP guardrails solve this by calling out at the MCP method layer instead of the HTTP layer. The ExtMCP protocol is modeled on Envoy's ext_authz, but the external server receives a structured, MCP-native payload: the JSON-RPC method name, the target backend, the request or response parameters, and selected request headers. The server can then make a decision based on the actual tool, prompt, or resource being accessed, without re-implementing MCP semantics.


Suggested change

MCP guardrails solve this by calling out at the MCP method layer instead of the HTTP layer. The ExtMCP protocol is modeled on Envoy's ext_authz, but the external server receives a structured, MCP-native payload: the JSON-RPC method name, the target backend, the request or response parameters, and selected request headers. The server can then make a decision based on the actual tool, prompt, or resource being accessed, without re-implementing MCP semantics.

MCP guardrails solve this challenge by calling out at the MCP method layer instead of the HTTP layer. The ExtMCP protocol is modeled on Envoy's `ext_authz` filter, but the external server receives a structured, MCP-native payload, including the JSON-RPC method name, the target backend, the request or response parameters, and selected request headers. The server can then make a decision based on the actual tool, prompt, or resource that is being accessed, without re-implementing MCP semantics.

Nadine2016 · 2026-06-16T15:46:19Z

+* Rewrite request parameters or response results to redact sensitive data or inject context.
+* Centralize MCP authorization logic in an external service that you already operate.
+
+### Sequence diagram


Suggested change

### Sequence diagram

### How it works

Nadine2016 · 2026-06-16T16:41:17Z

+    participant Client as MCP client
+    participant AGW as agentgateway
+    participant Ext as ExtMCP server
+    participant MCP as MCP target


Suggested change

participant MCP as MCP target

participant MCP as MCP backend

Nadine2016 · 2026-06-16T16:44:41Z

+        AGW->>MCP: Forward (possibly mutated) request
+        MCP-->>AGW: Result
+        AGW->>Ext: CheckResponse (result)
+        Ext-->>AGW: Pass or Mutated result


Suggested change

Ext-->>AGW: Pass or Mutated result

Ext-->>AGW: Pass or return mutated response

Nadine2016 · 2026-06-16T16:44:52Z

+    Client->>AGW: tools/call (JSON-RPC)
+    AGW->>Ext: CheckRequest (method, tool, params, headers)
+    alt Allowed or mutated
+        Ext-->>AGW: Pass or Mutated params


Suggested change

Ext-->>AGW: Pass or Mutated params

Ext-->>AGW: Pass request or return mutated params

Nadine2016 · 2026-06-16T16:46:21Z

+        AGW->>Ext: CheckResponse (result)
+        Ext-->>AGW: Pass or Mutated result
+        AGW-->>Client: Result
+    else Denied


wondering if there is another alternative route where the authorization error comes up after it checks the response

Nadine2016 · 2026-06-16T16:50:51Z

+
+### Phases
+
+The `methods` map controls when each method runs through a processor. Set a phase for each method that you want to send to the server.


the sections before the steps start are heard to understand as it talks about settings that you don't know where they are coming from. I think it would be good to have a sample agw policy and tell people that this is where you set it. then you dive into individual settings

also wondering if all of those concepts should live on a separate page. the page is pretty long

might also be good to explain the methods block and that this refers to the API calls in the MCP spec

looking at the policy, maybe you change the IA and start from the processor perspective. say that the processor defines the actions to take for a particular request/ response. and then you explain that each processor must be enforced by an ExtMCP server. that you can have multiple ExtMCP and each does a specific manipulation. and then for each processor, you say that you need to define the phase when this manipulation is supposed to happen, the method and the actual action.

can we also add a link to the ExtMCP spec so that people know what to do to make their server compliant

Nadine2016 · 2026-06-16T16:58:51Z

+    appProtocol: agentgateway.dev/mcp
+EOF
+```
+


maybe add verification steps?

Nadine2016 · 2026-06-16T17:08:04Z

+          methods:
+            tools/call: Request
+            tools/list: Response
+EOF


can we add a description for this block

methods: tools/call: Request tools/list: Response

it is a little hard to understand for me what this is actually doing

added a table after the config

Nadine2016 · 2026-06-16T17:10:34Z

+    - backendRefs:
+      - name: ext-mcp
+        port: 4445
+---


it is a little hard to understand where this hostname is coming from and where this is used. also do you always create an httproute or only to apply the policy? because the policy does not seem to reference the httproute

Nadine2016 · 2026-06-16T17:11:24Z

+
+### Step 6: Optional: Set a timeout for the policy server {#timeout}
+
+The guardrails callout has no deadline by default. If the policy server is slow or cold, the request can hang instead of letting `failureMode` engage. To bound the call, set a request timeout on the policy server with a `backend.http.requestTimeout` policy.


what happens if the timeout is happening. will the call just fail? (aka what does the MCP client see?)

Signed-off-by: Art Berger <art.berger@solo.io>

artberger added 2 commits June 15, 2026 16:54

testing review

8edb82a

Signed-off-by: Art Berger <art.berger@solo.io>

tests

055ff50

Signed-off-by: Art Berger <art.berger@solo.io>

artberger self-assigned this Jun 15, 2026

artberger marked this pull request as ready for review June 15, 2026 21:42

Merge branch 'main' into adb-extmcp

64c7d89

Nadine2016 reviewed Jun 16, 2026

View reviewed changes

artberger and others added 3 commits June 16, 2026 18:51

peer rev

f77e63f

Signed-off-by: Art Berger <art.berger@solo.io>

byo extmcp server

dfc6ca5

Signed-off-by: Art Berger <art.berger@solo.io>

Merge branch 'main' into adb-extmcp

2a82be6

		@@ -0,0 +1,88 @@
		Use MCP guardrails (also called ExtMCP) to apply external authorization and external processing to Model Context Protocol (MCP) requests. An external gRPC policy server inspects, allows, mutates, or denies individual MCP method calls, such as `tools/call` and `tools/list`, using MCP request context instead of generic HTTP metadata.


		{{< reuse "agw-docs/snippets/agentgateway-capital.md" >}} already supports [external authorization]({{< link-hextra path="/security/extauth/basic" >}}) and [external processing (ExtProc)]({{< link-hextra path="/traffic-management/extproc" >}}) for HTTP traffic. Both call out to an external gRPC server so that you can centralize authorization and request or response mutation outside the proxy. However, these integrations operate on raw HTTP. To make a decision about an MCP tool call, the external server must reassemble the HTTP body, parse the JSON-RPC envelope, and handle MCP framing itself.

		MCP guardrails solve this by calling out at the MCP method layer instead of the HTTP layer. The ExtMCP protocol is modeled on Envoy's ext_authz, but the external server receives a structured, MCP-native payload: the JSON-RPC method name, the target backend, the request or response parameters, and selected request headers. The server can then make a decision based on the actual tool, prompt, or resource being accessed, without re-implementing MCP semantics.

	Ext-->>AGW: Pass or Mutated result
	Ext-->>AGW: Pass or return mutated response

	Ext-->>AGW: Pass or Mutated params
	Ext-->>AGW: Pass request or return mutated params


		### Phases

		The `methods` map controls when each method runs through a processor. Set a phase for each method that you want to send to the server.


		### Step 6: Optional: Set a timeout for the policy server {#timeout}

		The guardrails callout has no deadline by default. If the policy server is slow or cold, the request can hang instead of letting `failureMode` engage. To bound the call, set a request timeout on the policy server with a `backend.http.requestTimeout` policy.

Conversation

artberger commented Jun 15, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying agentproxy with Cloudflare Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nadine2016 Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nadine2016 Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cloudflare-workers-and-pages Bot commented Jun 15, 2026 •

edited

Loading

Nadine2016 Jun 16, 2026 •

edited

Loading

Nadine2016 Jun 16, 2026 •

edited

Loading