Artificial Intelligence

Apply fine-grained access control with Bedrock AgentCore Gateway interceptors

As enterprises rapidly adopt AI agents to automate workflows and enhance productivity, they face a critical scaling challenge: managing secure access to thousands of tools across their organization. Modern AI deployments no longer involve a handful of agents calling a few APIs—instead, enterprises are building unified AI platforms where hundreds of agents, consumer AI applications, and automated workflows need to access thousands of Model Context Protocol (MCP) tools spanning different teams, organizations, and business units.

This increase in scale creates a fundamental security and governance problem: How do you make sure each calling principal—whether it’s an AI agent, user, or application—only accesses the tools they’re authorized to use? How do you dynamically filter tool availability based on user identity, agent context, the channel through which access is requested, and constantly evolving permissions? How do you protect sensitive data as it flows through multi-hop workflows from agents to tools to downstream APIs? And how do you accomplish all of this without sacrificing performance, creating operational bottlenecks, or forcing teams to deploy separate MCP server instances for every tenant or use case?

To address these challenges, we are launching a new feature: gateway interceptors for Amazon Bedrock AgentCore Gateway. This powerful new capability provides fine-grained security, dynamic access control, and flexible schema management.

Fine-grained access control for tool access

Enterprise customers are deploying thousands of MCP tools served through a unified AgentCore Gateway. These customers use this single MCP gateway to access tools from different teams, organizations, consumer AI applications, and AI agents, each with their corresponding access permissions assigned to the calling principal. The challenge is securing MCP tool access based on the calling principal’s access permissions and contextually responding to ListTools, InvokeTool, and Search calls to AgentCore Gateway.

Tool filtering must be based on multiple dynamic factors, including agent identity, user identity, and execution context, where permissions might change dynamically based on user context, the channel through which the user is accessing the agents, workspace access levels, and other contextual attributes. This requires security-conscious filtering where permission changes immediately affect tool availability without caching stale permission states.

The following diagram provides an example of user based tool filtering and sets the context for how the gateway evaluates identity and context before returning the allowed tools.

Schema translation and data protection between MCP and downstream APIs

Customers face complex challenges in managing the contract between AI agents and downstream APIs while maintaining security and flexibility. Organizations must dynamically map MCP request schemas to corresponding downstream API schemas, enabling critical data protection capabilities such as redacting or removing sensitive data like personally identifiable information (PII) or sensitive personal information (SPI) that users might send as part of prompts to agents. This prevents sensitive data leakage to downstream APIs when such information isn’t needed for the API call.

Additionally, customers require schema translation capabilities to handle API contract changes while keeping the MCP schema intact and decoupled from downstream implementations. This decoupling allows smoother API evolution and versioning without breaking the AI agent and tool contracts, so backend teams can modify their API implementations, change field names, restructure payloads, or update authentication requirements without forcing changes to the agent layer or requiring retraining of AI models that have learned specific tool schemas.

Tenant isolation for multi-tenant SaaS

Organizations offering agents as a service or tools as a service face complex multi-tenancy requirements. Customers must deploy their MCP servers for all their users while maintaining proper tenant isolation, requiring both tenant ID and user ID to be passed and validated. Multi-tenant MCP server architectures require different customers and workspaces to remain completely isolated, with tool access strictly controlled based on tenant boundaries. The challenge extends to determining whether separate gateways are needed per tenant or if a single gateway can safely handle multi-tenant scenarios with proper isolation guarantees.

Dynamic tool filtering

Customers need real-time, context-aware tool filtering that adapts to changing permissions and user contexts. Organizations require unified MCP servers that can filter tools in two stages: first by agent permissions and workspace context, then by semantic search—with critical requirements that no caching occurs for dynamically filtered tool lists because permissions might change at any time.

Custom header propagation and identity context management

AI agents are fundamentally different from traditional microservices in that they are autonomous and non-deterministic in their behavior. Unlike traditional microservice-to-microservice authorization approaches that typically rely on service-to-service trust and authorization techniques, AI agents need to execute workflows on behalf of end-users and access downstream tools, APIs, and resources based on user execution context. However, sending the original authorization tokens to downstream services creates significant security vulnerabilities, such as stolen credentials, privilege escalation, and the confused deputy problem, where a more privileged service is tricked into performing actions on behalf of a less privileged attacker.

Impersonation vs. act-on-behalf approaches

Customers face a fundamental security decision in how identity context propagates through multi-hop workflows (agent to agent to tool to API): using an impersonation approach or an act-on-behalf approach.

With an impersonation approach, the original user’s JWT token is passed unchanged through each hop in the call chain. Although simpler to implement, this approach creates significant security risks. We do not recommend this approach due to the following risks:

  • Downstream services receive tokens with broader privileges than necessary
  • Increased risk of privilege escalation if any component is compromised
  • Token scope can’t be limited to specific downstream targets
  • Vulnerable to confused deputy attacks, where compromised services can abuse overly privileged tokens

In an act-on-behalf approach, each hop in the workflow receives a separate, scoped token specifically issued for that downstream target, and JWT is used for propagating the execution context throughout. This approach is the recommended approach because it provides the following benefits:

  • Principle of least privilege – Each service receives only the permissions it needs to access specific downstream APIs
  • Reduced blast radius – Compromised tokens have limited scope and can’t be reused elsewhere
  • Better auditability – A clear chain of custody shows which service acted on behalf of the user using AgentCore Observability
  • Token scope limitation – Each downstream target receives tokens or credentials scoped specifically for its APIs
  • Security boundaries – Proper isolation is enforced between different services in the call chain
  • Confused Deputy prevention – Limited-scope tokens and credentials prevent services from being tricked into performing unauthorized actions

The act-on-behalf model requires the gateway to extract execution context from incoming requests, generate new scoped authorization tokens for each downstream target, and inject appropriate headers while maintaining the user’s identity context for auditing and authorization decisions—all without exposing overly privileged credentials to downstream services. This secure approach makes sure AI agents can execute workflows on behalf of users while maintaining strict security boundaries at every hop in the call chain.

The following diagram compares the workflows of impersonation vs. act-on-behalf approaches.

In the impersonation approach (top), when User A connects to the agent, the agent passes User A’s complete identity token with full scopes ("order: read, promotions:write") unchanged to both the Order tool and Promotions tool, meaning each tool receives more permissions than it needs. In contrast, the act-on-behalf approach (bottom) shows the agent creating separate, scoped tokens for each tool—the Order tool receives only the "order: read" scope, the Promotions tool receives only the "promotions:write" scope, and each token includes an "Act: Agent" field, which establishes a clear chain of responsibility showing the agent is acting on behalf of User A. This demonstrates how delegation implements the principle of least privilege by limiting each downstream service to only the specific permissions it needs, reducing security risks and preventing potential token misuse.

AgentCore Gateway: Secure MCP integration for AI agents

AgentCore Gateway transforms your existing APIs and AWS Lambda functions into agent-compatible tools, connects to existing MCP servers, and provides seamless integration with essential third-party business tools and services (such as Jira, Asana, and Zendesk). This unified access point enables secure integration across your enterprise systems. With AgentCore Identity, agents can securely access and operate across these tools with proper authentication and authorization using OAuth standards.

With the launch of gateway interceptors, AgentCore Gateway helps organizations implement fine-grained access control and credential management through custom Lambda functions at two critical points:

  • Gateway request interceptor – The request interceptor Lambda function processes incoming requests before they reach their target tools, enabling fine-grained access controlling based on user credentials, session context, and organizational policies, audit trail creation, schema translation, and more.
  • Gateway response interceptor – The response interceptor Lambda function processes outgoing responses before they return to the calling agent, allowing for audit trail creation, tools filtering, schema translation, and fine-grained access controlling the search and list tools.

The following diagram illustrates the request-response flow through gateway interceptors.

Let’s examine the specific payload structures that custom interceptors receive and must return at each stage of the request-response cycle. The gateway request interceptor receives an event with the following structure:

{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "gatewayRequest": {
        "headers": { "Authorization": "Bearer eyJhbG...", ... },
        "body": { "jsonrpc": "2.0", "method": "tools/list", ... }
    },
    "requestContext": { ... }
  }
}

Your gateway request interceptor Lambda function must return a response with the transformedGatewayRequest field:

{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayRequest": {  // <-- This field must be added by your code
        "headers": { ... },
        "body": { ... }
    }
  }
}

After the target service responds, the gateway response interceptor is invoked with an event containing the original request and the response:

{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "gatewayRequest": { ... },
    "requestContext": { ... },
    "gatewayResponse": {  // <-- This field contains the target's response
        "statusCode": 200,
        "headers": { ... },
        "body": { 
            "jsonrpc": "2.0",
            "result": { "tools": [ ... ] }
        }
    }
  }
}

Your gateway response interceptor Lambda function must return a response with the transformedGatewayResponse field:

{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayResponse": {  // <-- This field must be added by your code
        "statusCode": 200,
        "headers": { ... },
        "body": { ... }
    }
  }
}

Understanding this request-response structure is essential for implementing the custom interceptor logic we explore later in this post. Gateway interceptors provide critical capabilities for securing and managing agentic AI workflows:

  • Header management – Pass authentication tokens, correlation IDs, and metadata through custom headers
  • Request transformation – Modify request payloads, add context, or enrich data before it reaches target services
  • Security enhancement – Implement custom authentication, authorization, and data sanitization logic
  • Fine-grained access control – Secure MCP tool access based on the calling principal’s access permissions and contextually responding to ListTools, InvokeTool, and Search calls to AgentCore Gateway
  • Tenant isolation for multi-tenant MCP tools – Implement tenant isolation and access controls based on calling user, agent, and tenant identities in a multi-tenant environment
  • Observability – Add logging, metrics, and tracing information to monitor agentic workflows

Gateway interceptors work with AgentCore Gateway target types: including Lambda functions, OpenAPI endpoints, and MCP servers.

Use cases with gateway interceptors

Gateway interceptors enable flexible security and access control patterns for agentic AI systems. This post showcases three approaches: implementing fine-grained access control for invoking tools, dynamic tools filtering based on user permissions, and identity propagation across distributed systems.

Implementing fine-grained access control for invoking tools

AgentCore Gateway exposes multiple backend tools through a unified MCP endpoint. Users with different roles require different tool permissions. You can implement fine-grained access control using JWT scopes combined with gateway interceptors to make sure users can only invoke authorized tools and discover tools that belong to their role or workspace. Fine-grained access control uses JWT scope values issued by Amazon Cognito (or another OAuth 2 provider). You can also implement this using a YAML file or a database with mapped permissions. We follow a simple naming convention: users receive either full access to an MCP target (for example, mcp-target-123) or tool-level access (for example, mcp-target-123:getOrder). These scopes map directly to tool permissions in the scope claim as part of the incoming OAuth token, making the authorization model predictable and straightforward to audit.

The following diagram illustrates this workflow.

The request interceptor enforces permissions at execution time through the following steps:

  1. Extract and decode the JWT to retrieve the scope claim.
  2. Identify which tool is being invoked (using tools/call).
  3. Block the request if the user lacks either full target access or tool-specific permission based on the configuration file or access policy data store.
  4. Return a structured MCP error for unauthorized invocations, preventing the backend tool handler from executing.

The core authorization function is intentionally minimal:

def check_tool_authorization(scopes, tool, target):
    if target in scopes:
        return True
return f"{target}:{tool}" in scopes

This pattern enables predictable enforcement for both invocation and discovery paths (discussed further in the next section). You can extend the model with additional claims (for example, tenantId and workspaceId) for multi-tenant architectures.

For operational security, keep interceptors deterministic, avoid complex branching logic, and rely exclusively on token claims rather than large language model (LLM) instructions. By enforcing authorization at the gateway boundary—before the LLM sees or executes any tool—you achieve strong isolation across roles, tenants, and domains without modifying tool implementations or MCP targets.

Dynamic tools filtering

Agents discover available tools through two primary methods: semantic search capabilities that allow natural language queries (like “find tools related to order management”) and standard (tools/list) operations that provide a complete inventory of available tools. This discovery mechanism is fundamental to agent functionality, but it also presents significant security considerations. Without proper filtering controls, MCP servers would return a comprehensive list of all available tools, regardless of the requesting agent’s or user’s authorization level. This unrestricted tool discovery creates potential security vulnerabilities by exposing sensitive capabilities to unauthorized users or agents.

When a target returns a list of tools in response to semantic search or MCP tools/list requests, the gateway response interceptor can be used to enforce fine-grained access control. The interceptor processes the response before it reaches the requesting agent, so users can only discover tools they’re authorized to access. The workflow consists of the following steps:

  1. The target validates the incoming JWT token and returns either the complete tool list or a filtered set based on semantic search, irrespective of fine-grained access control.
  2. The configured response interceptor is invoked by AgentCore Gateway. The response interceptor extracts and decodes the JWT from the payload, retrieving the scope claims that define the user’s permissions.
  3. For each tool in the list, the interceptor evaluates the user’s authorization based on the JWT scopes.
  4. Tools that the user isn’t authorized to access are removed from the list.
  5. The response interceptor returns a transformed response containing only the authorized tools.

The following diagrams illustrate this workflow for both tools.

The following is a code snippet of the response interceptor Lambda handler that performs JWT token extraction, tool list retrieval, and permission-based filtering before returning the transformed response with authorized tools:

def lambda_handler(event, context):
    # Extract gateway response and authorization header
    gateway_response = event['mcp']['gatewayResponse']
    auth_header = gateway_response['headers'].get('Authorization', '')
    token = auth_header.replace('Bearer ', '')

    # Extract scopes from JWT token
    claims = decode_jwt_payload(token)
    scopes = claims.get('scope', '').split()
    
    # Get tools from gateway response (for list tools)
    tools = gateway_response['body']['result'].get('tools', [])
    # from structuredContent(in case of semantic search)
    if not tools:
        tools = gateway_response['body']['result'].get('structuredContent', {}).get('tools', [])
    
    # Filter tools based on scopes
    filtered_tools = filter_tools_by_scope(tools, scopes)
    
    # Return transformed response with filtered tools
    return {
        "interceptorOutputVersion": "1.0",
        "mcp": {
            "transformedGatewayResponse": {
                "statusCode": 200,
                "headers": {"Authorization": auth_header},
                "body": {
                    "result": {"tools": filtered_tools}
                }
            }
        }
    }

The filter_tools_by_scope function implements an authorization check for each tool against the user’s allowed scopes:

def filter_tools_by_scope(tools, allowed_scopes):
    """Filter tools based on user's allowed scopes"""
    filtered_tools = []
    for tool in tools:
        target, action = tool['name'].split('___')
        # Check if user has full target access or specific tool access
        if target in allowed_scopes or f"{target}:{action}" in allowed_scopes:
            filtered_tools.append(tool)
            
    return filtered_tools

The complete implementation can be found in the GitHub repo.

Custom headers propagation

As AI agents interact with multiple downstream services, maintaining user identity across service boundaries becomes critical for security, compliance, and audit trails. When agents invoke tools through AgentCore Gateway, the original user’s identity must flow from the agent to the gateway, and from the gateway to target services. Without proper identity propagation, downstream services can’t enforce user-specific authorization policies, maintain accurate audit logs, or implement tenant isolation. This challenge intensifies in multi-tenant environments where different users share the same agent infrastructure but require strict data separation.

Gateway request interceptors extract identity information from incoming request headers and context, transform it into the format expected by downstream services, and enrich requests before they reach target services by following these steps:

  1. The gateway request interceptor extracts authorization headers from incoming requests and transforms them for downstream services.
  2. AgentCore Gateway orchestrates the request flow and manages interceptor execution.
  3. The target invocation receives enriched requests with properly formatted identity information.

The gateway request interceptor helps organizations gain end-to-end visibility into user actions, enforce consistent authorization policies across service boundaries, and maintain compliance with data sovereignty requirements.

The workflow consists of the following steps:

  1. The MCP client calls AgentCore Gateway.
  2. AgentCore Gateway authenticates the inbound request.
  3. AgentCore Gateway invokes the custom interceptor.
  4. The gateway request interceptor transforms the incoming request payload by adding an authorization token as a parameter to send to the downstream Lambda target. (We don’t recommend sending the incoming JWT as-is to downstream APIs because it’s insecure due to the risk of privilege escalation and stolen credentials. However, there might be exceptions where the agent needs to call the MCP server with an access token for downstream APIs.) Alternatively, you can remove the inbound JWT coming from the request and add a new JWT with a least-privileged scoped-down token for calling relevant downstream APIs.
  5. AgentCore Gateway calls the target with the transformed request. The target has the authorization token passed by the interceptor Lambda function.
  6. AgentCore Gateway returns the response from the target.

The following diagram illustrates this workflow.

The following is a code snippet of the interceptor Lambda handler that performs custom header propagation:

import json
import uuid

def lambda_handler(event, context):
    # Extract the gateway request from the correct structure
    mcp_data = event.get('mcp', {})
    gateway_request = mcp_data.get('gatewayRequest', {})
    headers = gateway_request.get('headers', {})
    body = gateway_request.get('body', {})
    extended_body = body
    
    # Pass through the Authorization header
    auth_header = headers.get('authorization', '') or headers.get('Authorization', '')
    if "arguments" in extended_body["params"]:
        extended_body["params"]["arguments"]["authorization"] = auth_header
    # Return transformed request with Authorization header preserved
    response = {
        "interceptorOutputVersion": "1.0",
        "mcp": {
            "transformedGatewayRequest": {
                "headers": {
                    "Accept": "application/json",
                    "Authorization": auth_header,
                    "Content-Type": "application/json"
                },
                "body": extended_body
            }
        }
    }
    return response

No auth and OAuth based authorization

Many enterprises need flexible authorization models that balance discoverability with security. Consider a scenario where you want to allow AI agents and applications to discover and search available MCP tools without requiring authorization, enabling seamless tool exploration and semantic search across your tool catalog. However, when it comes to actually invoking these tools, you need strict OAuth-based authorization to make sure only authorized agents and users can execute tool calls. You might even need per-tool authorization policies, where some tools require authentication while others remain publicly accessible, or where different tools require different permission levels based on the calling principal’s identity and context.

AgentCore Gateway now supports this flexibility through the introduction of a “No Auth” authorization type at the gateway level for all inbound calls. When configured, this makes all targets and tools accessible without authentication for discovery purposes. To enforce OAuth authorization at the method level (ListTools vs. CallTools) or implement per-tool authorization policies, you can use gateway interceptors to examine the inbound JWT, validate it against the requirements according to RFC 6749 using your authorization server’s discovery URL, and programmatically allow or deny access to specific methods or tool calls. This approach gives you fine-grained control: open discovery for ListTools and SearchTools requests while enforcing strict OAuth validation for CallTools requests, or even implementing custom authorization logic that varies by tool, user role, execution context, or other business logic your organization requires—all while keeping your MCP calls secure and compliant with your security policies.

The following diagram illustrates this workflow.

The process begins with a ListTools call with No Auth to the AgentCore Gateway, which is configured with general no-auth for all inbound calls. With this configuration, users can discover available tools without authorization. However, when the user subsequently makes a CallTool request to invoke a specific tool, authorization is required. AgentCore Gateway invokes the custom request interceptor Lambda function, which validates the JWT token from the authorization header and checks the user’s scopes and permissions against the specific tool being invoked. If authorized, the interceptor transforms and enriches the request with the necessary authorization context, and AgentCore Gateway forwards the transformed request to the target service. The target processes the request and returns a response, which AgentCore Gateway then returns to the client, enforcing strict OAuth-based authorization for actual tool execution while maintaining open discovery for tool listing.

To create a gateway configured with No Auth for inbound calls, use authorizerType as NONE, as shown in the following CreateGateway API:

{
  "name": "no-auth-gateway",
  "protocolType": "MCP",
  "protocolConfiguration": {
    "mcp": {
      "supportedVersions": ["2025-03-26"]
    }
  },
  "authorizerType": "NONE",
  "roleArn": <role_arn>
}

Observability

Comprehensive observability provided by AgentCore Observability is critical for monitoring, debugging, and auditing AI agent workflows that interact with multiple tools and services through AgentCore Gateway. Gateway interceptors enforce authorization, transform requests, and filter data before downstream services execute, making the observability layer a critical security boundary. This offers the following key benefits:

  • Security decision visibility – Interceptors generate authoritative logs for authorization outcomes, including allow/deny decisions and the evaluated JWT scopes. This provides a clear audit trail for reviewing rejected requests, validating policy behavior, and analyzing how authorization rules are enforced across tool invocations.
  • Request and response traceability – Interceptors capture how MCP requests and responses are modified, such as header enrichment, schema translation, and sensitive data redaction. This delivers full traceability of payload changes and supports secure, compliant data handling across agent workflows.
  • Downstream tool observability – Interceptors log downstream tool behavior, including status codes, latency, and error responses. This creates consistent visibility across targets, helping teams troubleshoot failures, identify reliability issues, and understand end-to-end execution characteristics.

These logs also capture identity and context attributes, helping teams validate authorization behavior and isolate issues in environments where multiple user groups or tenants share the same gateway. Gateway interceptors automatically integrate with AgentCore Observability, providing the following features:

  • Real-time monitoring of authorization decisions
  • Performance bottleneck identification through duration and invocation metrics
  • End-to-end traceability across multi-hop agentic workflows
  • Identity and context attributes for validating authorization behavior in multi-tenant environments

The following screenshot shows sample metrics from Amazon CloudWatch log groups for a gateway interceptor.

The metrics demonstrate healthy gateway interceptor performance with a 100% success rate, minimal latency (4.47 milliseconds average), and no throttling issues, indicating the system is operating within optimal parameters.

The following screenshot shows sample logs from CloudWatch for a gateway interceptor.

AgentCore Observability integration helps you monitor authorization decisions in real time, identify performance bottlenecks, and maintain end-to-end traceability across multi-hop agentic workflows.

Conclusion

AgentCore Gateway with gateway interceptors addresses the fundamental security and access control challenges organizations face when deploying agentic AI systems at scale. The three patterns demonstrated—fine-grained access control for tool invocation, dynamic tool filtering, and identity propagation—provide foundational building blocks for secure agentic architectures that bridge authentication gaps, maintain credential isolation, and enforce custom security policies. By providing programmable interception points for both requests and responses, organizations can implement fine-grained access control without modifying underlying tool implementations or MCP server architectures. As organizations scale to hundreds of agents and thousands of tools, gateway interceptors provide the flexibility and control needed to maintain security, compliance, and operational visibility across complex agentic AI deployments while aligning with enterprise integration patterns and security best practices. AgentCore Gateway with gateway interceptors provides a flexible foundation for implementing enterprise-grade security controls across agentic AI architectures. To learn more about how to apply gateway interceptors to solve common enterprise challenges, refer to the following code samples:

For complete documentation on gateway interceptor configuration and deployment, refer to Fine-grained access control for Amazon Bedrock AgentCore Gateway.

About the Authors

Dhawal Patel is a Principal Generative AI Tech lead at AWS. He has worked with organizations ranging from large enterprises to mid-sized startups on problems related to agentic AI, deep learning, and distributed computing.

Ganesh Thiyagarajan is a Senior Solutions Architect at AWS with over 20 years of experience in software architecture, IT consulting, and solution delivery. He helps ISVs transform and modernize their applications on AWS. He is also part of the AI/ML Technical field community, helping customers build and scale generative AI solutions.

Avinash Kolluri is a Sr Solutions Architect at AWS. He works with Amazon and its subsidiaries to design and implement cloud solutions that accelerate innovation and operational excellence. With deep expertise in AI/ML infrastructure and distributed systems, he specializes in helping customers use AWS services for building foundational models, workflow automation, and generative AI solutions.

Bhuvan Annamreddi is a Solutions Architect at AWS. He works with ISV customers to design and implement advanced cloud architectures and helps them enhance their products by using AWS services. He is passionate about helping customers build scalable, secure, and innovative systems, with a strong interest in generative AI and serverless architecture as enablers for delivering meaningful business value.

Mohammad Tahsin is a Generative AI Specialist Solutions Architect at AWS, where he works with customers to design, optimize, and deploy modern AI/ML solutions. He’s passionate about continuous learning and staying on the frontier of new capabilities in the field. In his free time, he enjoys gaming, digital art, and cooking.

Ozan Deniz works as a Software Development Engineer in AWS. He and his team focus on enhancing the seller capabilities by generative AI. When not at work, he enjoys exploring the outdoors.

Kevin Tsao is a Software Development Engineer within the AgentCore Gateway team. He has been at Amazon for 6 years and has been working in the conversational AI and agentic AI space since the beginning of his tenure, contributing to services such as Bedrock Agents and Amazon Lex.