One MCP image, two Bedrock AgentCore Runtimes — SigV4 for other AWS accounts, Entra ID for users

One MCP server image as two Bedrock AgentCore Runtimes: IAM SigV4 with a resource policy for cross-account callers, and an Entra ID JWT Runtime for users.

The Amazon Bedrock AgentCore icon, a white line-drawn half brain of hexagonal outlines beside a large and a small four-pointed sparkle, on a teal rounded square, beside the words Amazon Bedrock AgentCore in dark navy on two lines on a white card
On this page

Introduction

I run an MCP server on Amazon Bedrock AgentCore Runtime, and the first agent to use it lives in a different AWS account. When that agent’s ECS task tried to connect, it could reach neither the Amazon Cognito domain that issued its token nor the AgentCore endpoint. An egress filter that blocks by destination was the likely cause.

Adding two hosts to that filter would have unblocked one caller. It would not have changed the shape of the problem: Cognito’s token endpoint is a public web domain with no PrivateLink, so every token request leaves the caller’s VPC.

I switched the Runtime to IAM SigV4, and ran the same image a second time behind Entra ID. Other AWS accounts now call a single AWS hostname that a VPC endpoint can keep off the internet, and the tools that need to know which person is asking run only on the Entra ID Runtime.

One image, two Runtimes

One container image runs as two AgentCore Runtimes, and each Runtime accepts exactly one kind of caller. The IAM Runtime takes requests signed with AWS Signature Version 4 (SigV4) from roles in other AWS accounts. The Entra ID Runtime takes a Microsoft Entra ID access token from a user’s MCP client.

One container image deployed as two AgentCore RuntimesA single MCP server container image at the top is deployed twice. The IAM Runtime on the left runs with AUTH_MODE set to iam and registers the shared tools; it is called by an agent in another AWS account with a SigV4-signed request allowed by a resource policy. The Entra ID Runtime on the right runs with AUTH_MODE set to entra and registers the shared tools plus the user tools; it is called by a user's MCP client with an Entra ID access token.MCP server container imageone CI pipeline, one image tagdeployed twiceIAM RuntimeAUTH_MODE=iamshared toolsEntra ID RuntimeAUTH_MODE=entrashared toolsuser toolsSigV4 + resource policyAgent in another AWS accountEntra ID access tokenUser's MCP client
Both Runtimes pull the same image. The AUTH_MODE environment variable decides which tools each one registers, so the user-specific tools exist only on the Entra ID Runtime.

Both Runtimes come from one CI pipeline, one image tag and one Terraform module. An environment variable, AUTH_MODE, is the only difference inside the container. The IAM Runtime sets iam and registers the shared tools. The Entra ID Runtime sets entra and also registers tools that act on behalf of the signed-in user, such as reading their profile.

Cognito’s token endpoint stays on the public internet

AgentCore Runtime takes one of two kinds of inbound authentication: a JWT checked by its custom JWT authorizer, or IAM SigV4. Setting authorizer_configuration on the Runtime selects JWT. Leaving it out selects SigV4, which is the default.

With JWT and Cognito, a caller makes two trips. It fetches a token with the client_credentials grant from the Cognito hosted domain, <your-domain>.auth.<region>.amazoncognito.com, then calls AgentCore with that token.

Caller traffic with a Cognito JWTAn agent inside the caller's AWS account sends two requests out through an egress filter to the public internet. The first goes to the Cognito hosted domain to get a token. The second calls the AgentCore Runtime endpoint with that JWT.Caller's AWS accountAgent (ECS task)egress filterPublic internetCognito hosted domain*.auth.<region>.amazoncognito.com1. get tokenAgentCore Runtimebedrock-agentcore.<region>.amazonaws.com2. call with JWT
With a Cognito JWT, the caller needs two destinations, and the token request goes to a public web domain.

The hosted domain is a web service rather than an AWS API endpoint, so no VPC endpoint covers it. Cognito does have a VPC endpoint, but it does not cover the hosted domain that issues Cognito tokens.

Cognito’s PrivateLink page states that client credentials grants are not supported through PrivateLink and that user pool domains are reachable only through public-internet paths. A caller using JWT therefore always needs a route to the public internet.

SigV4 removes the token request. The caller signs each request with its own IAM credentials, and the only destination left is bedrock-agentcore.<region>.amazonaws.com. AgentCore offers an interface VPC endpoint for that host, com.amazonaws.<region>.bedrock-agentcore, so the caller’s account can keep the traffic inside its VPC.

Caller traffic with SigV4An agent inside the caller's AWS account sends one SigV4-signed request through a VPC endpoint in its own account to the AgentCore Runtime, over the AWS network through PrivateLink. No token request is made.Caller's AWS accountAgent (ECS task)VPC endpointAWS network (PrivateLink)AgentCore Runtimebedrock-agentcore.<region>.amazonaws.comSigV4-signed call
With SigV4, the caller has one destination, and an interface VPC endpoint in its own account can carry it.

I removed authorizer_configuration from the Runtime, which switched it from JWT to SigV4.

A resource policy on the Runtime and on its endpoint

A role in another account can call the Runtime only when a resource-based policy on the Runtime lists it. The caller’s own IAM policy is not enough across accounts.

AgentCore evaluates InvokeAgentRuntime against two resources: the Runtime itself, and its DEFAULT endpoint. Each one needs its own policy. With a policy on the Runtime alone, the call fails with a 403 that says nothing about which of the two refused it.

CreateAgentRuntime creates the DEFAULT endpoint itself, so my Terraform never declares it. Its ARN is the Runtime ARN followed by /runtime-endpoint/DEFAULT. I build both ARNs and attach one policy to each:

modules/agentcore_runtime/main.tf (abridged)
locals {
agentcore_policy_targets = (
var.exists_ecr_images && var.authorizer == null && length(var.invoker_principal_arns) > 0
) ? {
runtime = aws_bedrockagentcore_agent_runtime.this[0].agent_runtime_arn
endpoint = "${aws_bedrockagentcore_agent_runtime.this[0].agent_runtime_arn}/runtime-endpoint/DEFAULT"
} : {}
}
data "aws_iam_policy_document" "agentcore_invoke" {
for_each = local.agentcore_policy_targets
statement {
sid = "AllowCrossAccountInvoke"
effect = "Allow"
principals {
type = "AWS"
identifiers = var.invoker_principal_arns
}
actions = ["bedrock-agentcore:InvokeAgentRuntime"]
resources = [each.value]
}
}
resource "aws_bedrockagentcore_resource_policy" "invoke" {
for_each = local.agentcore_policy_targets
resource_arn = each.value
policy = data.aws_iam_policy_document.agentcore_invoke[each.key].json
}

for_each creates one copy of a block per entry in a map. The map here has two entries, runtime and endpoint, and the data source runs under the same for_each as the resource, so the policy attached to the Runtime names the Runtime ARN, and the policy attached to the DEFAULT endpoint names the endpoint ARN.

In a policy attached to a role, * means every resource. A resource policy is stored on the resource itself, through PutBucketPolicy for S3 or PutResourcePolicy for AgentCore, so S3 reads * as the bucket that holds the policy.

AgentCore stores the policy the same way but still needs the ARN of the resource holding the policy written out. The policy stored on the DEFAULT endpoint, as Terraform renders it:

Resource policy on the DEFAULT endpoint (excerpt)
{
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::444455556666:role/caller-agent" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/mcp_server-AbCdEf1234/runtime-endpoint/DEFAULT"
}

The callers allowed to invoke the Runtime are listed in the module’s invoker_principal_arns variable, which becomes the policy’s Principal. The variable takes role or user ARNs only. A variable validation rejects an account root such as arn:aws:iam::111122223333:root, which would open the Runtime to every principal in the root’s account.

Three places a cross-account call must pass

A cross-account call succeeds only when the IAM policy and the resource policy both allow the call and no restriction blocks the call. A miss in any of the three places returns the same 403.

Three places a cross-account call must passA request from the caller role passes three checks in order. In the caller's AWS account: first the role's IAM policy, which must allow InvokeAgentRuntime on the Runtime ARN and on its runtime-endpoint path, then the permissions boundary and the VPC endpoint policy. In the server's AWS account: the resource policy on the Runtime and on its DEFAULT endpoint. Only when all three pass does the request reach the AgentCore Runtime. If any one is missing, the call fails with a 403.Caller's AWS accountServer's AWS accountCallerrole1IAM policyon the Runtime ARNand /runtime-endpoint/*2Restrictionspermissions boundaryVPC endpoint policy3Resource policyon the Runtimeand DEFAULT endpointAgentCoreRuntimeAll three pass → the request reaches the MCP serverAny one fails → 403
The IAM policy and the restrictions live in the caller’s account, and the resource policy lives in the account that runs the MCP server, the server account below.
  1. The caller’s IAM policy allows bedrock-agentcore:InvokeAgentRuntime on the Runtime ARN and on <runtime-arn>/runtime-endpoint/*. Like the resource policy, the IAM policy must list both the Runtime and the endpoint, so a policy naming only the Runtime is refused.
  2. The caller’s permissions boundary and VPC endpoint policy must not block the call. A boundary is a ceiling, so an action the boundary omits stays denied whatever the role’s own policy says. A VPC endpoint policy can restrict which principals pass through the endpoint, so a policy that leaves out the caller’s role blocks the call at the endpoint.
  3. The server account’s resource policy lists the caller’s role, on the Runtime and on the DEFAULT endpoint.

The caller’s IAM policy (item 1), attached to the caller’s role:

iam.tf (caller account)
data "aws_iam_policy_document" "mcp_server_invoke" {
statement {
effect = "Allow"
actions = ["bedrock-agentcore:InvokeAgentRuntime"]
resources = [
var.mcp_server_runtime_arn,
"${var.mcp_server_runtime_arn}/runtime-endpoint/*",
]
}
}

A miss in any of the three places returns 403, so the order of rollout across the two accounts matters. Apply the server account’s resource policy first, then point the caller at the Runtime. In the other order, every call returns 403 until the server account’s change is applied.

Why pass only Content-Type to the signer?

The caller signs with the service name bedrock-agentcore, and passes only the Content-Type header to botocore. botocore signs Content-Type together with host and the X-Amz-* headers botocore adds itself. AgentCore’s APIs are signed under two service names:

  1. bedrock-agentcore-control: APIs that create and manage Runtimes, such as CreateAgentRuntime.
  2. bedrock-agentcore: InvokeAgentRuntime, which calls a Runtime. This is the service name the caller in this article uses.

The caller passes only Content-Type because httpx or a proxy can rewrite other headers after signing. Handing botocore every httpx header puts accept-encoding and similar headers into the signature, so a rewrite breaks the signature, and the resulting 403 reads exactly like a missing permission.

The MCP Python SDK sends requests through httpx, a Python HTTP client, so the signer is an httpx.Auth, the authentication step httpx runs on every request before sending it. The signer copies the request into an AWSRequest from botocore, the library under the AWS SDK for Python, signs it, and writes back only the headers botocore added:

signing.py (abridged)
class _SigV4Auth(httpx.Auth):
# botocore hashes the body, so httpx must buffer it before auth_flow runs.
requires_request_body = True
def auth_flow(self, request):
aws_request = AWSRequest(
method=request.method,
url=str(request.url),
data=request.content,
headers={
"Content-Type": request.headers.get("content-type", "application/json"),
},
)
frozen = credentials.get_frozen_credentials()
SigV4Auth(frozen, "bedrock-agentcore", region).add_auth(aws_request)
request.headers.update(signed_headers(dict(aws_request.headers)))
yield request
  1. Buffer the body: requires_request_body = True makes httpx read the body into memory before auth_flow runs. botocore hashes the body, so it needs the whole body first.
  2. Copy only Content-Type: the AWSRequest gets only Content-Type and the body, so no other httpx header enters the signature.
  3. Take consistent credentials: a task role’s temporary credentials refresh periodically. get_frozen_credentials() takes one consistent snapshot per request, so the access key and session token cannot come from two sides of a refresh, and the signature never fails on a mismatched pair.
  4. Sign as bedrock-agentcore: SigV4Auth signs with the service name bedrock-agentcore and adds the Authorization and X-Amz-* headers to the AWSRequest.
  5. Write back only the signing headers: signed_headers() keeps Authorization and the X-Amz-* headers, drops the rest, and the result goes back onto the httpx request.
What the SigV4 signer copies between httpx and botocoreAn httpx request carries Content-Type, Accept-Encoding and User-Agent headers. Step 1 copies only Content-Type and the body into a botocore AWSRequest. Step 2: botocore signs it with SigV4 and adds Authorization and X-Amz-* headers. Step 3 writes only Authorization and X-Amz-* back to the httpx request. Step 4: a proxy rewrites Accept-Encoding after signing, and the signature still matches because Accept-Encoding was never signed.httpx requestContent-TypesignedAccept-Encodingnot signedUser-Agentnot signedAuthorizationwritten backX-Amz-*written backbotocore AWSRequestContent-Typebody (hashed)AuthorizationX-Amz-*② botocore signs with SigV4① Content-Type + body③ Authorization + X-Amz-*④ A proxy rewrites Accept-Encoding after signing→ the signature still matches, because Accept-Encoding was never signed
The signer sends only Content-Type and the body to botocore and copies back only the headers botocore added, so a proxy rewriting Accept-Encoding after signing leaves the signature intact.

A second Runtime for Entra ID users

SigV4 identifies an IAM role, never a person, so every request on the IAM Runtime looks like it came from the same caller. Tools that act for a specific user need that user’s identity, and an Entra ID access token carries it. Each Runtime takes only one kind of inbound authentication, so the user-facing tools needed a second Runtime.

I added the second Runtime, with the same image, as a second call to the same Terraform module. The module takes an optional authorizer object, and only the Entra ID call passes authorizer:

environments/dev/main.tf (abridged)
module "compute" {
source = "../../modules/agentcore_runtime"
runtime_name = local.runtime_name
image_tag = var.image_tag
invoker_principal_arns = local.invoker_principal_arns
environment_variables = local.runtime_environment_variables # AUTH_MODE = "iam"
}
module "compute_entra" {
source = "../../modules/agentcore_runtime"
runtime_name = local.entra_runtime_name
image_tag = var.image_tag
authorizer = {
discovery_url = "https://login.microsoftonline.com/${local.entra_tenant_id}/v2.0/.well-known/openid-configuration"
allowed_audience = local.entra_audience
allowed_scopes = ["invoke"]
}
environment_variables = local.entra_environment_variables # AUTH_MODE = "entra"
}

Inside the module, passing authorizer:

  • fills authorizer_configuration
  • forwards the Authorization header to the container with request_header_allowlist, so the container can read the user’s claims
  • turns off the resource policy, because a JWT Runtime cannot be called with SigV4 at all

I kept the existing module "compute" address, the name Terraform tracks these resources under in its state, and runtime_name unchanged. A new runtime_name replaces the Runtime, and the replacement gets a new ARN. The caller’s IAM policy and the server account’s resource policy both name the old ARN, so both would need rewriting before calls succeed again.

ApproachWhat it looks likeWhat gets duplicated
Separate environment directoryAnother directory under environments/, such as environments/dev-entra/, with its own Terraform configurationSecrets, ECR wiring, CI job
Separate application directoryA second copy of the MCP server code, built into its own imageThe shared tool code, and the two copies drift
Two module blocks (chosen)Two module blocks in the same environments/dev/main.tf, both with source pointing at the same moduleNothing

I went with the two module blocks. The two Runtimes also share one security group, since both sit in the same VPC with the same rules.

AUTH_MODE registers the user tools on the Entra ID Runtime only

Every tool a server registers appears in its response to tools/list, the MCP request a client sends to fetch the tool list, and the model can pick any tool on the list. A tool the server never registers cannot be picked, so the IAM Runtime does not register the user tools at all:

server.py
# anything unset or unrecognised is treated as "iam" so a missing/typo'd value
# fails closed to the Runtime that has no user-specific tools, not the other
# way around.
AUTH_MODE = os.getenv("AUTH_MODE", "iam")
if AUTH_MODE == "entra":
tools_user.register(mcp)

A missing or misspelled AUTH_MODE leaves the container running as the IAM Runtime, with no user tools. The server’s diagnostic tool also reports auth_mode. Both Runtimes run the same image, so when the user tools are missing, auth_mode is what tells whoever is debugging whether the call went to the wrong Runtime or AUTH_MODE was set wrong.

What the container checks after AgentCore’s JWT authorizer

AgentCore’s authorizer verifies the token’s signature, expiry, audience and scopes before the request reaches the container. The token’s scp claim lists the scopes it was granted, such as invoke User.Read. When scp has no invoke, allowed_scopes = ["invoke"] makes the authorizer reject the request.

AgentCore also uses allowed_scopes to fill two places:

  1. scopes_supported in the Runtime’s OAuth protected resource metadata, the document an MCP client reads to learn where to get a token
  2. The scope in the 401’s WWW-Authenticate header

An MCP client learns what scope to ask for from scopes_supported and WWW-Authenticate.

An Entra ID v2 token carries the bare scope name in scp, so allowed_scopes takes invoke, not api://<client-id>/…/invoke.

The authorizer does not compare the values of tid and iss, nor check that scp is present, so the container checks all three on every user-specific call. The token is already verified, so the container only base64url-decodes the payload:

auth.py (abridged)
if not expected_tenant or str(tid).lower() != expected_tenant.lower():
raise AuthError("tenant mismatch")
expected_issuer = f"https://login.microsoftonline.com/{expected_tenant}/v2.0"
if str(payload.get("iss", "")).lower() != expected_issuer.lower():
raise AuthError("issuer mismatch")
if not payload.get("scp"):
raise AuthError("token has no scp claim: app-only (client_credentials) tokens cannot use user-specific tools")
  1. Tenant: tid must match the expected tenant ID, and a missing expected tenant rejects every token. The error names no tenant ID, so the message cannot help anyone guess one.
  2. Issuer: iss must be https://login.microsoftonline.com/<tenant-id>/v2.0, the v2 issuer of the expected tenant.
  3. scp present: an app-only token from the client_credentials grant has no scp. The check closes a route around the user, so a CI identity cannot call a tool that reads a person’s data.

Summary

I moved the MCP server from Cognito JWT to IAM SigV4 so that a caller in another AWS account calls one AWS hostname, through a VPC endpoint in its own account. Then I added an Entra ID Runtime from the same image, because SigV4 names a role and the user-specific tools need to know which user is calling.

  • Leave authorizer_configuration off to get SigV4. AgentCore takes SigV4 or JWT per Runtime, never both.
  • Attach a resource policy to the Runtime and to <runtime-arn>/runtime-endpoint/DEFAULT, each naming the exact ARN of the resource it is attached to.
  • Grant the caller InvokeAgentRuntime on the Runtime and on /runtime-endpoint/*, and check the caller’s permissions boundary and VPC endpoint policy, because a miss in any of the three places returns 403.
  • Sign with bedrock-agentcore, and pass only Content-Type to botocore.
  • Register user-specific tools only on the Entra ID Runtime, and default AUTH_MODE to iam, which registers none of them.
  • In the container, compare the values of tid and iss and check that scp is present, since AgentCore’s authorizer checks only signature, expiry, audience and scopes.

References

Share this article