For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Control MCP server access, authorize individual tools, and inspect request and response content.

Agentgateway provides three ways to filter Model Context Protocol (MCP) traffic through a virtual MCP server. Use them separately or together:

• Filter a request with guardrail processors (mcpGuardrails). Inspect tool arguments and results to reject disallowed calls or mask sensitive data. Use a remote processor to call an external policy service.
• Filter a target with a target condition. Exclude an upstream MCP server before agentgateway contacts it.
• Filter tools and other resources with MCP authorization (mcpAuthorization). Hide individual tools, prompts, and resources from list responses, and reject calls to them. Rules evaluate each item separately, so you can allow some tools and hide the rest.

All three support Common Expression Language (CEL) expressions that read request attributes, such as headers and JWT claims. Their scope and timing differ.

Compare the options

Use this table to compare what each option filters, when it runs, and whether agentgateway contacts upstream servers.

Example: Keep a client away from an MCP server

The following authorization rule hides the admin-tools target’s tools from clients without the admin role. Agentgateway still initializes the target and sends it tools/list requests for those clients.

mcpAuthorization:
  rules:
  - 'mcp.tool.target != "admin-tools" || (has(jwt.roles) && "admin" in jwt.roles)'

To exclude admin-tools before agentgateway contacts it, move the role check to the target’s condition:

targets:
- name: public-tools
  mcp:
    host: http://public-tools:8080/mcp
- name: admin-tools
  mcp:
    host: http://admin-tools:8080/mcp
  condition: 'has(jwt.roles) && "admin" in jwt.roles'

Both examples require an authenticated request with claims in the jwt variable. Do not base access decisions on a header that the client controls.

How the options work together

When a client sends a request to a virtual MCP server, agentgateway applies the options in the following order.

1. Authentication: If you configure MCP authentication or JWT authentication, agentgateway validates the client’s token first. The resulting claims are available to all three options as jwt.
2. Target conditions: Agentgateway includes only targets whose condition returns true. Evaluation errors exclude the target. Conditions run once at initialization for stateful sessions (the default), or on every request in stateless mode.
3. Request-phase guardrail processors: Agentgateway runs the processors for the request’s method in order. The first processor that rejects the request stops the chain, and agentgateway does not contact any target. For a fanout method such as tools/list, the processors run once for the whole request.
4. Authorization of calls: For a call to a single tool, prompt, or resource, such as tools/call, MCP authorization checks the item. If the item is not allowed, agentgateway rejects the call.
5. Upstream request: Agentgateway forwards the request to the selected target, or fans it out to every selected target.
6. Authorization of lists: For methods such as tools/list, MCP authorization removes denied items from each target’s response. Agentgateway then merges the responses and adds target-name prefixes.
7. Response-phase guardrail processors: Agentgateway runs the processors on the response. For a fanout method, the processors run once, on the merged response.

Next steps

• Reject or mask requests and responses with CEL guardrails or remote guardrails.
• Include targets conditionally in a virtual MCP server.
• Hide tools from clients with MCP authorization.