Prove Which Tool Calls Your AgentCore Gateway Blocks

Review AgentCore Gateway attachment, policy modes, caller and tool inputs. Separate denied-action evidence from target effects and business approval.

Primary sources checked 2026-10-17

Establish what a denial must prevent

To rely on an AgentCore Gateway policy, establish that the intended engine is attached in an enforcing mode, that the actual caller and requested action reach the intended policy inputs, and that a forbidden test call does not reach its target. A policy trace alone cannot establish that last fact. The owner also needs an allowed control, since an unavailable target can make every attempted operation fail without demonstrating the intended restriction.

This guide helps an application engineer and security reviewer decide whether one existing MCP-protocol gateway provides a specific tool-call boundary. Its output is an evidence record with separate configuration, policy-decision and target-effect observations. It does not commission a gateway or authorize a production test. All identifiers, requests and expected results below are synthetic. No AWS account, gateway, policy evaluation, Lambda invocation or customer record was accessed for this guide.

The worked scope is one account and one selected Region, a JWT-authorized gateway, standard request-authorization policies and a Lambda target implementing two synthetic tools. The actual Region, account, runtime versions and service availability remain unselected prerequisites. Interceptors, temporal policies, output guardrails, HTTP passthrough, cross-account access, delegated third-party OAuth and multi-agent authorization are excluded. Each needs its own applicability review.

Keep this service distinct from Bedrock Agents Classic. AWS's maintenance-mode guidance restricts CreateAgent and InvokeInlineAgent for accounts without the documented prior usage, while existing eligible workloads continue. Eligibility is per account, not inherited from another account in the same company. This guide concerns AgentCore Gateway, not the Classic InvokeAgent return-control protocol. A reference to Bedrock in a project brief does not identify which of these services the customer can use.

Read back the engine attachment and enforcement mode

Record the gateway actually used by the application, not a similarly named development gateway. Obtain its identifier, endpoint, update time, status, execution role, authorizer, interceptor configurations and policy-engine configuration through an already authorized configuration read. The GetGateway reference exposes these fields. A desired infrastructure declaration and a dated service readback are different evidence items; retain both when checking for drift. This scenario assumes no interceptors. If the readback contains any, hold its acceptance until their request/response behavior and authorization boundary receive a separate review.

The engine ARN identifies the attached collection of policies. Its enforcement mode determines how that collection affects requests. The configuration contract names LOG_ONLY and ENFORCE. The former records evaluations without applying the access decision. The latter applies the policy decision to agent operations. An evaluation that says a call would be denied can therefore coexist with a call passing this policy boundary in LOG_ONLY. Target authentication, function errors and business checks can still stop it later.

There is a second control to read. An individual policy has enforcementMode: ACTIVE or LOG_ONLY, separately from its lifecycle status. Only active-enforcement policies contribute to the returned decision; shadow policies are evaluated separately. The policy-mode guide explains both layers. An enforcing gateway does not turn a shadow policy into a blocking rule. Record every relevant policy's mode and status. The paired scenario below keeps its policies in active enforcement and changes only the gateway attachment's mode.

Inspect who can change this attachment. AWS's enforcement-mode guidance explains that bedrock-agentcore:UpdateGateway can change the mode or remove the engine, with no separate mode-specific action or condition key protecting that field. Treat that permission as part of the boundary's change control. Reviewing Cedar statements while ignoring an operator's ability to detach them leaves a gap.

Configuration evidence has a time boundary. If the gateway changes during an exercise, split the record into revisions rather than attach one favorable readback to every call. The application owner must identify the actual endpoint used by retries and background workers too. A second client that bypasses the gateway cannot inherit the first client's policy evidence.

Policy changes are also eventually consistent. AWS's policy-mode guide says a created, updated or promoted policy reaches the evaluation path after propagation, not as an instantaneous switch. Plan a separate observation window after the authorized change and record what the test actually evaluated. A current control-plane readback alone does not establish that an immediately preceding call used that revision. This is a documented propagation boundary, not a measured delay or a guaranteed waiting period for the selected environment.

Separate gateway admission from the tool's business authority

Inbound authorization controls access to the gateway. AWS documents JWT, IAM and offloaded alternatives with different enforcement behavior. For the selected JWT path, review the configured issuer discovery, audience/client restrictions and required claims with the identity owner. The inbound authorization guide also warns that JWT subject information can enter CloudTrail. Use opaque test identities and do not copy bearer tokens into the evidence worksheet.

A permitted inbound caller still needs permission for the specific tool call. AgentCore's policy scope maps the principal, action and gateway resource separately. For OAuth-authenticated callers, the principal uses the JWT subject; tool actions use their gateway-qualified names. A policy for one exact action should be reviewed with its specific gateway ARN. A friendly tool name in a prompt is insufficient to identify that action.

The destination has another responsibility. Suppose a tool appends an internal case note through a service identity. Gateway admission does not establish that the selected case belongs to the initiating user's organization or that a commercial change has current approval. The record-owning service must enforce those requirements at the write boundary, using a reviewed caller-to-record authorization path. If the selected integration cannot carry or establish that trusted context, leave the record-specific write unavailable.

Routine permitted work can run without a person approving each harmless step. In the synthetic design, an accepted internal note may be appended automatically. Issuing a credit remains a separate operation outside that role's authority. An approval screen is useful only when the attempted effect is bound to its actual authorization and checked by the component that can commit it.

Check which inputs the policy can evaluate

The authorization-flow documentation describes an OAuth principal built from the token and a tool action/resource/context built from the MCP request. The ordinary tool parameters appear in context.input. A user-supplied tenantId in those arguments is therefore a claim made by the request, not an independently retrieved fact about the destination record.

For example, requiring the request's tenant label to match a trusted caller claim can reject one class of mismatch. It cannot prove that a case ID placed beside that label belongs to the same tenant. A malicious or defective caller can supply its permitted tenant and another tenant's case ID. The destination must resolve that case through an authoritative relationship and reject the inconsistent operation. Preserve both checks in the test plan instead of declaring tenant isolation from a matching string.

Policy authoring also depends on the generated schema. AWS's schema constraints derive the request types from the MCP tool manifest. OAuth claims use principal tags; IAM principals have a different representation. JSON arrays map to sets without order, and JSON numbers map to Cedar decimal representation rather than preserving arbitrary floating-point meaning. JSON null uses a generated entity representation rather than a direct Cedar null type. Review null separately from an absent or optional field; do not assume all three produce the same condition. Keep sequence-dependent rules and exact domain arithmetic out of an unexamined type conversion.

The selected guide excludes the special output and temporal features. Do not infer a general ability to query the CRM, inspect arbitrary application state or read an invented context.approval field during a standard request decision. Pin the tool manifest and review how required, optional, missing and malformed fields are handled. The implementation limitations include decimal precision and a combined generated Cedar schema limit below 400 KB. A short policy statement does not establish that its generated schema fits. If a necessary rule cannot be expressed faithfully, enforce it through a suitable owned service or narrow the enabled operation.

Review the runtime role separately from the policy editor

The identity that edits a policy and the identity that evaluates it during a gateway request perform different work. AWS's policy permissions guide distinguishes the gateway execution role from the resource-management role. For ordinary policy integration it identifies AuthorizeAction, PartiallyAuthorizeActions and GetPolicyEngine under the bedrock-agentcore prefix. The runtime role also needs the target-specific authority required by its actual route.

Do not treat a returned policy ID as completed creation. CreatePolicy returns HTTP 202, with status that can still change. Use GetPolicy to inspect status, reasons, definition and enforcement mode. Require lifecycle status ACTIVE for a ready policy, then separately check enforcementMode. Neither field establishes a passed enforcement test.

Management and execution failures have different fixes. AWS documents CreatePolicy returning an ID before CREATE_FAILED when the management role lacks bedrock-agentcore:InvokeGateway on the selected gateway. This validates the policy's actions; adding evaluator rights to the execution role does not repair that management path. Conversely, missing runtime evaluation permissions can prevent gateway policy integration even when a document was created. Retain the native failure and its owning role instead of counting either failure as a matched business denial.

The permissions guide also describes CLI-created execution roles that include target/outbound access but omit the three policy-evaluation actions. For an existing CLI-provisioned gateway, inspect the actual CLI version, role and later changes before assuming that documented creation path still describes its deployed permissions. Any missing runtime grants need an owned, scoped change. No CLI installation or generated role was tested here.

Review policy-management scope too. ManageResourceScopedPolicy and ManageAdminPolicy are permission-only gates for specific-resource and wildcard policy authoring respectively, not callable APIs. Their presence belongs in the manager's authority record. Do not grant both merely because an example includes them; establish the scope the actual administrator is supposed to manage.

The selected Lambda target needs its own invocation permission. AWS's gateway permission guidance separates target access from other gateway permissions. The function then operates under its own execution identity when accessing downstream resources. Do not describe the gateway's service role as the caller's personal CRM identity. The target's authorization and audit design must account for the actual relationship.

Missing permissions should lead to a bounded correction, not an administrator wildcard. Retain a configuration reference identifying which exact evaluation or target action is missing. Have its owner review the smallest applicable change, then repeat the allowed control and forbidden case. No permission change is executed or authorized by the example below.

Work one synthetic note operation and its forbidden alternative

Assume gateway alias G1 exposes target CaseOps, with tools append_internal_note and approve_credit. The published MCP action names in the synthetic manifest are CaseOps___append_internal_note and CaseOps___approve_credit. These names are fixture assumptions, not discovered AWS objects. AWS's Lambda-target guide describes the tool schema, input mapping and request context supplied to a function; a real exercise must capture the target's actual contract.

The fixture business rule allows the opaque principal triage-worker-a to append an internal note for tenant A. Both tenantId and caseId are required strings. All policies used for this comparison are stipulated to have lifecycle status ACTIVE and enforcementMode: ACTIVE. The chosen note text is fixed synthetic content. The target owns the case membership check and must accept only the permitted case A17. Case B17 belongs to another synthetic tenant. The worker must never approve a credit through this gateway. There is no real credit system connected: the forbidden tool records an attempted invocation in a disposable test ledger only.

Before execution, an independent observer writes the expected results and proves the test ledger can record the allowed control. The supplied scenario has no observed results. Do not fill the observation column from the intended policy. Native request IDs, target receipts, configuration snapshots and tested denial reasons are all NOT OBSERVED until a separately authorized exercise produces them.

Allowed control

With the intended JWT identity, accepted argument shape, enforcing attachment and required runtime permissions, the proposed expectation is that A17's internal note passes gateway policy and the target's case check. The observer should inspect the function's invocation record and the one resulting synthetic note. A normal MCP result without a corresponding accepted note leaves business completion unknown. An unrelated Lambda error cannot be used to claim that the allowed operation worked.

Forbidden action in enforcing mode

Request approve_credit directly, even if the tool is absent from the model's displayed list. The expected result is a policy denial before the target records that operation. Retain the request identity, native error and independent target observation. Under Cedar authorization semantics, a matching permit is required and a matching forbid takes precedence. Inspect all applicable policies rather than assume one narrow permit excludes a broader permit added elsewhere.

The same forbidden action in non-enforcing mode

In a separate disposable configuration, keep the same policy and change only the stipulated mode to LOG_ONLY. The test's expected distinction is a recorded would-deny decision without blocking by this policy engine. The inert target can therefore record an attempted forbidden invocation if the other prerequisites allow it. This is a deliberately unsafe control, never a proposed production mode switch. It should cause the observer to reject a claim that the policy is enforcing.

Missing runtime evaluation authority

A separate configuration omits a required policy-evaluation permission while retaining the intended policy document. This includes the documented CLI role-creation case, subject to actual role readback; it is not proof that every CLI version or later-edited role has the gap. The expected administrative disposition is HOLD: establish the error and missing authority, then repair under change control. Do not count an error as evidence for the business restriction. Record the native failure and whether the target was invoked; do not invent the exact response envelope or generalize one documented integration symptom to every outage.

Correct tenant label with the wrong case

Keep the valid tenant-A identity and tenantId: A, but replace A17 with B17. A parameter-only policy might permit this shape, while the target must reject the case relationship without writing a note. If rejection occurs there, label it target authorization rather than gateway enforcement. If the target cannot establish caller-to-case authority, hold the whole write path even when the gateway's simpler action restriction works.

Illustrative expectations, not observed calls. Every operative policy is assumed to have lifecycle status ACTIVE and enforcementMode ACTIVE. Only the gateway attachment mode changes. A policy decision is not a target or business-effect receipt; missing evaluator authority requires investigation.

Same caller, policy set and active-enforcement assumptions; different gateway modes. These are proposed expectations, not collected AWS evidence. Other target prerequisites and destination record authority remain independent.

Keep policy response, tool visibility and effect evidence distinct

AWS's gateway-with-policy guide explains that tool listing is a partial authorization question: a tool can appear when some input circumstances would permit it. A later call with actual parameters is evaluated separately. The same guide limits the described policy evaluation to MCP tools, not the listed prompt/resource methods, and shows tool denials inside an MCP result with isError: true. Inspect the actual envelope instead of making HTTP success the acceptance rule.

For each proposed case, record the gateway request and downstream attempt separately. Lambda context can supply gateway, target and request identifiers, but those technical identifiers are not permanent business idempotency keys. A request retried after a lost response can have a different transport identity while representing the same intended note. The application must preserve its business operation identity and reconcile uncertain effects before retrying a write.

An empty target log is not sufficient proof of no invocation. Establish that the collection covers the target revision and observation interval, and retain an allowed control that reaches the same collector. If log access is denied or delivery is delayed, record the observation as incomplete. A destination ledger can establish a committed note while an invocation record explains that the handler ran; neither should be substituted for the other.

Keep evidence references rather than raw tokens, complete claim payloads or customer note text in the worksheet. Name the collector and retention owner. Any new tracing, paid query, fault injection or target invocation requires its own scoped authorization. This guide supplies the questions and expected distinctions; it does not grant those actions.

Copy an enforcement record with explicit unknowns

Use the following readable fields for one gateway revision and one intended operation. Keep the same record identity across the expected case, native observation and target inspection. Separate records are needed when the engine attachment or target implementation changes during the exercise.

Decision and accountable owner

State the caller, permitted effect, forbidden effect, environment and owner. Record the separately approved test scope.

Gateway configuration

Identify endpoint, account/Region, configuration readback time, status, authorizer, interceptor configurations, engine ARN, attachment mode and execution-role reference.

Policy and tool contract

Reference the complete applicable policy set, each policy's lifecycle status and enforcement mode, exact action/resource, policy hashes, manifest revision, required field types and excluded features.

Trusted identity and supplied inputs

Record redacted principal evidence and independently trusted attributes separately from tool arguments and caller-supplied labels.

Runtime and target authority

Reference evaluator permissions, target invocation scope, function identity and the target's caller-to-record authorization method.

Predeclared expectation

Name the allowed control or adverse case, expected enforcement point, permitted result and forbidden effect before observing the implementation.

Separate tool-listing observation

Record the listing request and visibility, or NOT OBSERVED. Do not substitute listing visibility or absence for a direct tool-call decision.

Observed gateway result

Retain request correlation, actual response category and policy evidence, or NOT OBSERVED. Distinguish a rule denial from evaluation failure.

Observed target and business result

Reference invocation collection coverage and independent committed-effect inspection, or UNKNOWN. Do not infer either from the gateway response alone.

Disposition and reopening condition

Accept the specific demonstrated restriction, reject a mismatch or hold missing evidence. Name the next owner, stop control and changes that invalidate the record.

For the worked forbidden-action case, the filled expectation is G1, the synthetic triage-worker-a identity, CaseOps___approve_credit, the intended engine revision and ENFORCE. The expected enforcement point is gateway policy, and the forbidden effect is any target credit-tool invocation. Every actual observation remains NOT OBSERVED. The result is a proposed test record, not acceptance of the synthetic configuration. A future observer must replace those fields with collected references or retain HOLD.

Choose an enforcing boundary the team can operate

An attached gateway policy can centralize a supported action-and-parameter restriction when the manifest, identity mapping and operational ownership are clear. The cost is another configuration and evaluation dependency, plus responsibility for its change control. Keep record-specific checks at the destination where they depend on authoritative business state. The gateway resource in Cedar identifies the gateway, not automatically the case record being changed.

A target-owned restriction may be preferable when the destination already controls every supported entry point and the required rule needs transactional state. The gateway can still narrow exposed tools. In that arrangement, report the target as the enforcement owner rather than claim the policy engine establishes the whole rule. Review direct target callers too: a request that never traverses the gateway cannot be restricted by this gateway policy.

Read-only preparation is another reasonable choice while authority is unresolved. The worker can draft an internal note without committing it, provided its reads are separately authorized. Do not retain a write credential merely to make a demonstration appear complete. LOG_ONLY is useful for testing policy impact with isolated effects, but it is unsuitable as the sole control for a restriction that must already prevent those effects.

The choice changes when tool schemas cannot represent a needed rule, trusted identity cannot reach the owning service, or the operator cannot inspect uncertain outcomes. Those are scope and implementation constraints, not reasons to broaden policy patterns until the happy path succeeds.

Stop, reconcile and reopen under a corrected revision

Stop the exercise if a forbidden synthetic call reaches a non-inert destination, the caller or gateway differs from the approved scope, a token appears in evidence, or the observer loses the ability to inspect effects. Hold new application dispatches through the approved stop control. Blocking future requests does not undo a note or credit already accepted, and stopping the model does not establish that an in-flight target request ended.

Preserve the affected configuration revision and operation references. Classify the gap as attachment/mode, policy scope, input trust, runtime authority, target authorization or observation coverage. This classification determines the next owner. A missing runtime permission belongs with the gateway/IAM operator; a case-ID substitution reaching another tenant belongs with the record-owning service as well as the integration owner.

Recover through a reviewed configuration whose assumptions still apply, then rerun the allowed control and the adverse case that exposed the gap. Do not restore service by removing the policy engine, switching to LOG_ONLY, accepting every principal or automatically calling the target directly. A genuinely needed emergency route needs its own owner, restrictions and visible evidence; it cannot silently inherit this record's acceptance.

Reconcile earlier attempts before repeating writes. If the destination cannot determine whether the original note committed, keep that operation unknown and escalate through its supported recovery process. The agent-cancellation article covers the separate handling of dispatched effects, while the MCP server review supplies broader operator and connector checks.

Before your next review, choose one gateway and complete the configuration and expectation fields before requesting any test invocation. Have another reviewer challenge the expected denial with a non-enforcing control and a mismatched record. Sign off only the restriction the collected gateway and target evidence can establish, with the unresolved fields and their owners retained.