Govern AgentCore Agents calling MCP servers

You run agents on AWS Bedrock AgentCore and MCP servers on AgentCore too. This guide puts the TrueFoundry gateway between them, so you control which agent may use which tool — and choose whether the end user’s identity reaches the tool at all.

What you are setting up

Your agent runs on an AgentCore Runtime. Your MCP server runs on another one, reachable only through the AgentCore invocation endpoint rather than the open internet. The TrueFoundry gateway sits between them: it authenticates the agent, decides whether that agent may use this tool, and supplies the credential the MCP runtime requires.

Component	Where it runs	Its job in this setup
Your agent	AgentCore Runtime	Calls tools. Exchanges the signed-in user’s token for one that names the agent.
TrueFoundry gateway	TrueFoundry	Resolves the agent, enforces access policy, and authenticates upstream to the MCP runtime.
Your MCP server	AgentCore Runtime	Serves tools. What it can attribute a call to depends on which mode you pick.
Okta	Your tenant	Issues the tokens and holds the exchange policy.
AgentCore Identity	AWS	Brokers the agent’s token exchange with Okta and stores the client secret.

The agent never holds a credential for the MCP runtime. It presents a token describing itself, and the gateway is the only place an upstream credential lives.

One inbound token, two upstream modes. The agent sends the gateway the same thing either way: its own agent token, obtained by exchanging the user’s login token. What differs is only how the gateway authenticates upstream to your MCP runtime — and therefore what your MCP server can see.

Mapping an AgentCore agent to a TrueFoundry agent

Three identities are in play. Keeping them distinct is what makes the governance in this guide possible.

Identity	Where it lives	What it is for
Workload identity (AgentCore)	Created automatically per runtime	Lets your agent call AgentCore Identity to request a token. Internal to AWS — the gateway never sees it.
Okta service app (`agent-service`)	Okta, as an OIDC service application	The agent’s identity in the token chain. Its client id lands in the `cid` claim of the agent’s token — and because that claim sits inside a signed token, the chain of authentication is cryptographically enforced rather than asserted.
TrueFoundry agent (`demo-agent`)	TrueFoundry Agents Registry	The governable principal. Tool access, policy and audit attach here.

The link between the last two is a claim mapping. Register Okta (the agent-as issuer) as an identity provider in TrueFoundry with name claim cid, then register the agent with an identity-provider-backed identity mapping cid = agent-service to demo-agent. A token arriving with that cid now resolves to a named agent, and the gateway applies that agent’s policy. One Okta service application can back several runtimes — useful when they are instances of the same logical agent. Give agents that need different tool access different service applications, since access is granted against the resolved agent.

Okta registrations you need

Three custom authorization servers, one per audience. The audience is what lets each hop confirm a token was minted for it, rather than merely being valid somewhere.

Authorization server	Audience	Issues
`login-as`	`api://chat-client`	the user’s login token, at sign-in
`agent-as`	`api://agent-api`	the agent’s token — the exchange target, and what the gateway validates
`mcp-as`	`api://mcp-api`	the token your MCP runtime validates (Okta OBO only)

Do not use the org authorization server. A token exchange requires the authorization server that issued the subject token to be registered as a trusted server on the server performing the exchange. Okta’s org authorization server cannot be named in that relationship — it is not selectable — and cannot carry a custom audience. Every hop that takes part in an exchange, including the sign-in hop, needs its own custom authorization server.

Applications, and the scope they trade in:

Application	Type	Role
`chat-client`	OIDC web (auth code + PKCE)	Where the user signs in, against `login-as`.
`agent-service`	OIDC service (client credentials)	The agent’s identity. Client of the exchange at `agent-as`; becomes `cid`.
`tfy-mcp-exchange`	OIDC service (client credentials)	The client the gateway uses for the second exchange (Okta OBO only).

Define a real API scope on agent-as and mcp-as, and grant it in each server’s access policy. The examples below use tool.invoke; substitute the scopes your own MCP server expects. A scope is mandatory on every exchange request, and OIDC scopes are refused, so there has to be an API scope to ask for.

Turn DPoP off on the service applications. AgentCore Identity and the gateway both authenticate to Okta with a client secret and do not generate DPoP proofs. If Require Demonstrating Proof of Possession is enabled, every token request from that client fails.

Choosing between the two upstream modes

Both modes give you the same governance at the gateway — the agent is named, policy is enforced, and the call is audited. They differ in what reaches your MCP server.

	IAM SigV4	Okta OBO
Agent resolved at the gateway	yes	yes
Gateway RBAC and audit	yes	yes
User identity at the MCP server	no	yes — `sub`
Per-user logic inside the tool	not possible	yes
MCP runtime inbound auth	IAM (SigV4)	JWT authorizer
Okta work	sign-in + one exchange	sign-in + two exchanges, trust chain
Good for	shared reference data, internal lookups, tools that cannot validate JWTs	anything touching a specific person’s data

Why you may end up with two MCP runtimes. An AgentCore Runtime accepts exactly one inbound auth mode — IAM or JWT, never both. If you want the same tools reachable under both modes, deploy the same MCP image twice and register each runtime as its own MCP server. The tool code is identical; only the runtime’s inbound configuration differs.

IAM SigV4 — agent identity stops at the gateway

The gateway signs its call to your MCP runtime with AWS SigV4, using a dedicated IAM principal. The runtime authorizes that principal; no token travels with the request, so the MCP server sees no user and no agent. Everything you want to control still happens — one hop earlier, at the gateway.

IAM SigV4 flow: the user signs in at login-as, the agent exchanges that token at agent-as so it carries the user in sub and the agent in cid, the TrueFoundry gateway resolves the agent and enforces policy, then signs its upstream call with AWS SigV4 — so neither the user nor the agent travels past the gateway and the MCP server sees only an AWS principal.

Set it up

Create login-as and agent-as, and the applications

Create the two custom authorization servers with their audiences, add the tool.invoke scope and an access policy to each, then create chat-client and agent-service. On agent-service, enable the Token Exchange grant under Advanced → non-interactive grants and turn Require DPoP off.

On agent-as → Trusted servers → add login-as, then add a token-exchange rule letting agent-service exchange a login-as token for one audienced to api://agent-api, granting tool.invoke. Set the user condition so the signed-in user matches.

Create the AgentCore Identity credential provider

aws bedrock-agentcore-control create-oauth2-credential-provider \
  --name okta-agent-obo \
  --credential-provider-vendor CustomOauth2 \
  --oauth2-provider-config-input '{"customOauth2ProviderConfig":{
      "oauthDiscovery":{"discoveryUrl":"https://<org>.okta.com/oauth2/<agent-as-id>/.well-known/openid-configuration"},
      "clientId":"<agent-service client id>",
      "clientSecret":"<agent-service secret>",
      "clientAuthenticationMethod":"CLIENT_SECRET_BASIC",
      "onBehalfOfTokenExchangeConfig":{
        "grantType":"TOKEN_EXCHANGE",
        "tokenExchangeGrantTypeConfig":{"actorTokenContent":"NONE"}}}}'

It points at agent-as — the exchange target. Nothing here names login-as: the subject issuer is established by the trusted-server relationship in Okta and by the agent runtime’s authorizer.

Create the two runtimes

The agent runtime validates the login token and forwards the bearer. The MCP runtime takes no authorizer at all — omitting it is what selects IAM/SigV4 inbound.

# agent runtime
authorizerConfiguration={"customJWTAuthorizer":{
    "discoveryUrl": LOGIN_AS_DISCOVERY,          # login-as
    "allowedAudience": ["api://chat-client"]}},
requestHeaderConfiguration={"requestHeaderAllowlist":["Authorization"]}

# MCP runtime — no authorizerConfiguration, no header allowlist
protocolConfiguration={"serverProtocol":"MCP"}

Have the agent exchange the token and call the gateway

# AgentCore pre-exchanges the validated login token and injects a workload token.
# Read it PER REQUEST — a cached token attributes one user's actions to another.
wat = (request.headers.get("X-Amz-Bedrock-AgentCore-Identity-WAT")
       or request.headers.get("WorkloadAccessToken"))

agent_token = boto3.client("bedrock-agentcore").get_resource_oauth2_token(
    resourceCredentialProviderName="okta-agent-obo",
    oauth2Flow="ON_BEHALF_OF_TOKEN_EXCHANGE",
    workloadIdentityToken=wat,
    scopes=["tool.invoke"],                     # required; never "openid"
    audiences=["api://agent-api"],              # required; no default is assumed
    customParameters={                          # AgentCore's default value is refused by Okta
        "subject_token_type": "urn:ietf:params:oauth:token-type:access_token"},
)["accessToken"]

Send agent_token to the gateway as the bearer. Do not call GetWorkloadAccessTokenForJWT yourself — AgentCore has already done that step, and calling it again from inside the runtime fails.

Create the IAM principal the gateway signs with

A dedicated IAM user whose only permission is invoking that one runtime. Grant both actions — the gateway passes a caller id, and invoking on behalf of a named user is a separate action that a policy with only InvokeAgentRuntime will not cover.

{"Effect":"Allow",
 "Action":["bedrock-agentcore:InvokeAgentRuntime",
           "bedrock-agentcore:InvokeAgentRuntimeForUser"],
 "Resource":["<mcp-runtime-arn>","<mcp-runtime-arn>/*"]}

Use a long-lived access key: the gateway’s SigV4 support does not take a session token, so SSO or STS credentials cannot be used here.

Add Okta (agent-as issuer) as an identity provider with name claim cid; register the agent with an identity-provider-backed identity mapping cid = agent-service; add the MCP server and make the agent an MCP Server User on it.

type: mcp-server/remote
name: agentcore-mcp-sigv4
url: https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-runtime-arn>/invocations?qualifier=DEFAULT
auth_data:
  type: aws-sigv4
  region: <region>
  auth:
    type: aws-access-key
    access_key_id:     tfy-secret://<tenant>:agentcore:AWS_ACCESS_KEY_ID
    secret_access_key: tfy-secret://<tenant>:agentcore:AWS_SECRET_ACCESS_KEY

Use the bare runtime ARN in the URL. The endpoint is selected by the ?qualifier= query parameter, so the ARN embedded in the path must be the runtime ARN. The AWS console shows the endpoint ARN (…/runtime-endpoint/DEFAULT) prominently, and pasting that produces a failure that looks like a permissions problem. The region must also match in three places: the URL, the ARN, and the gateway’s SigV4 region field.

What your MCP server receives

No Authorization header, and no claims — the request is authorized as an AWS principal. Your tool code should handle that explicitly rather than falling back to a default user, so an unauthenticated call never quietly looks like an authenticated one:

user = subject_from_validated_token(ctx)   # None under SigV4
if user is None:
    return non_user_scoped_data()          # or refuse, per tool

Return only data that is safe for any caller the gateway has authorized. Per-user decisions are not possible here — that is what Okta OBO adds.

Okta OBO — user identity reaches the tool

Steps 1 and 2 are unchanged. Instead of signing with SigV4, the gateway performs a second exchange — turning the agent’s token into one audienced to your MCP runtime that still names the user.

Okta OBO flow: the first two hops are unchanged, then the TrueFoundry gateway performs a second token exchange at mcp-as as tfy-mcp-exchange, producing a token audienced to api://mcp-api that still names the user, which the MCP runtime validates and uses to scope its answer.

Set it up

Everything from IAM SigV4 still applies. This is what you add.

Create mcp-as and the exchange client

Add the mcp-as authorization server with audience api://mcp-api and the tool.invoke scope. Create tfy-mcp-exchange as an OIDC service application with the Token Exchange grant enabled and DPoP off.

Extend the trust chain and add the exchange rule

On mcp-as → Trusted servers → add agent-as. Then add a token-exchange rule permitting tfy-mcp-exchange to exchange an agent-as token for one audienced to api://mcp-api, granting tool.invoke.

Add the user claims you want downstream

On mcp-as → Claims, add email as an expression (user.email) included in the access token, with the condition set to any scope. A claim tied to the email or profile scope never appears, because the exchange requests only tool.invoke — the token validates and the claim is simply absent.

Give the MCP runtime a JWT authorizer and the header allowlist

authorizerConfiguration={"customJWTAuthorizer":{
    "discoveryUrl": MCP_AS_DISCOVERY,            # mcp-as
    "allowedAudience": ["api://mcp-api"],
    "allowedScopes": ["tool.invoke"]}},
requestHeaderConfiguration={"requestHeaderAllowlist":["Authorization"]}

The allowlist is essential. AgentCore strips inbound headers by default, even when its authorizer has just validated the token — without it your MCP server receives no token at all, and Okta OBO behaves exactly like IAM SigV4 while looking like a failed exchange.

Switch the gateway's upstream auth

Register the second MCP server against the JWT runtime. No agent code changes — the agent sends the same token it sent under IAM SigV4.

type: mcp-server/remote
name: agentcore-mcp-oauth
url: https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-runtime-arn>/invocations?qualifier=DEFAULT
auth_data:
  type: oauth2
  grant_type: token_exchange        # subject_token = the inbound agent token
  provider: okta
  token_url: https://<org>.okta.com/oauth2/<mcp-as-id>/v1/token
  audience: api://mcp-api
  client_id: <tfy-mcp-exchange client id>
  client_secret: tfy-secret://<tenant>:agentcore:TFY_MCP_EXCHANGE_SECRET
  scopes: [tool.invoke]

What your MCP server receives

Claim	Value	What to do with it
`sub`	the signed-in user	Scope every response to this person.
`email`	their address	Present only if you added the claim.
`aud`	`api://mcp-api`	Minted for this server; reject anything else.
`scp`	`[tool.invoke]`	What was granted.
`cid`	`tfy-mcp-exchange`	The exchanging client — see the note below.

Derive the caller from sub in the validated token, never from a tool argument. Tool arguments are produced by the model, so a user parameter can be steered by prompt injection; a token cannot.

Verify the signature unless a validating layer guarantees it. Behind an AgentCore runtime with a JWT authorizer, the signature, issuer, audience and scopes have already been checked before your code runs, so decoding the payload to read claims is enough. If your MCP server is reachable without such a layer, decoding without verifying accepts any self-signed JWT — a complete authentication bypass. Verify against the issuer’s JWKS in that case.

Where the agent’s name lives. The second exchange is performed by the gateway’s client, so cid in the final token names tfy-mcp-exchange rather than your agent. The user survives the hop; the agent was resolved at the gateway and is recorded there. If your MCP server itself must make agent-aware decisions, have Okta emit an actor claim (act) or a custom claim carrying the agent id.

What you can govern

Because the agent resolves to a named principal at the gateway, policy lives there rather than in agent code — and applies identically in both modes.

Control	How it works	IAM SigV4	Okta OBO
Which agents may reach a server	Collaborators on the MCP server. An agent that is not one is refused, whatever valid token it presents.	yes	yes
What it may do there	The `MCP Server User` role calls tools; `MCP Server Manager` changes configuration.	yes	yes
Which tools	A virtual MCP server exposes a curated subset, so an agent gets three tools rather than thirty.	yes	yes
Credential isolation	The IAM key or client secret lives in the gateway. Agents hold no upstream credential, and rotation is one place.	yes	yes
Attribution	Calls are recorded against the resolved agent — which is why the `cid` mapping matters even when no user is involved.	agent	agent + user
Per-user authorization in the tool	Your MCP server applies its own rules to `sub` — ownership checks, row filtering, per-person limits.	no	yes
Least privilege per call	The upstream token is bound to one audience and scope set, and expires. Compare a shared API key: unscoped, unattributed, long-lived.	n/a	yes

Changing mode is gateway configuration, not an agent change: moving a server from SigV4 to on-behalf-of touches the server registration and the MCP runtime’s inbound auth, and the agent keeps sending the same token.

Verifying what actually arrived

Do not assume identity propagated — assert it. Add a diagnostic tool that returns what your MCP server genuinely sees, and keep it in place:

@mcp.tool()
def whoami(ctx) -> dict:
    claims = validated_claims(ctx)          # {} when no token arrives
    return {"authenticated": bool(claims),
            "sub": claims.get("sub"),  "aud": claims.get("aud"),
            "cid": claims.get("cid"),  "scope": claims.get("scp"),
            "act": claims.get("act"),  "iss": claims.get("iss")}

Field	IAM SigV4	Okta OBO
`authenticated`	false	true
`sub`	absent	the signed-in user
`aud`	absent	`api://mcp-api`
`scope`	absent	`[tool.invoke]`

Ask your agent “who am I?” against each server. Under IAM SigV4 the answer names no user — that is correct, not a failure. Under Okta OBO it names the signed-in person. Seeing the two side by side is the clearest evidence that delegation is real. It also pays to log identity at every hop you own — the client, the agent’s entry point, each exchange (request and result), and the MCP server — recording sub, aud, cid and scopes, with tokens redacted. Log the exchange request before you make it: a failure logged only on success produces silence exactly when you need the detail.

Troubleshooting

When an exchange fails, read Okta’s System Log first. AgentCore and the gateway surface only a generic HTTP error; the log records the precise reason under outcome.reason and echoes what was actually sent, which also confirms whether your change took effect.

Symptom	Cause
MCP server sees no token, though authentication clearly succeeded	`Authorization` is not in the runtime’s header allowlist. AgentCore strips inbound headers by default.
`invalid_subject_token`	The issuing authorization server is not a trusted server on the exchanging one — or the sign-in hop is still using the org authorization server.
`invalid_subject_token_type`	Subject token type is not `…:access_token`. AgentCore’s default value is refused, so set it explicitly.
`openid_not_allowed_token_exchange`	An OIDC scope was requested. Ask for a real API scope defined on the target server.
Exchange succeeds but a configured claim is missing	The claim is conditional on a scope the exchange does not request. Set it to any scope.
Runtime rejects a valid-looking token	Audience mismatch — an access token’s `aud` is the authorization server’s audience, not a client id.
Gateway returns 403	Check policy before credentials: is the agent a collaborator on this server, and did `cid` resolve to a registered agent?
A credential fix appears to have no effect	Upstream credentials bind when the MCP server entry is saved. Re-save the entry after rotating a secret.
`403 AccessDeniedException` from AgentCore	Overloaded — read the response body. The same status covers an IAM denial, an unresolvable resource ARN, and a SigV4 signature mismatch.

A habit worth keeping. If a change that should have altered the failure produces a byte-identical error, stop forming new hypotheses and first prove your change reached the component under test — a cached upstream credential or a runtime still on its previous version will absorb every fix you try.

Agent Harness

Agent Governance

Govern AgentCore Agents calling MCP servers

What you are setting up

Mapping an AgentCore agent to a TrueFoundry agent

Okta registrations you need

Choosing between the two upstream modes

IAM SigV4 — agent identity stops at the gateway

Set it up

What your MCP server receives

Okta OBO — user identity reaches the tool

Set it up

What your MCP server receives

What you can govern

Verifying what actually arrived

Troubleshooting

​What you are setting up

​Mapping an AgentCore agent to a TrueFoundry agent

​Okta registrations you need

​Choosing between the two upstream modes

​IAM SigV4 — agent identity stops at the gateway

​Set it up

​What your MCP server receives

​Okta OBO — user identity reaches the tool

​Set it up

​What your MCP server receives

​What you can govern

​Verifying what actually arrived

​Troubleshooting

What you are setting up

Mapping an AgentCore agent to a TrueFoundry agent

Okta registrations you need

Choosing between the two upstream modes

IAM SigV4 — agent identity stops at the gateway

Set it up

What your MCP server receives

Okta OBO — user identity reaches the tool

Set it up

What your MCP server receives

What you can govern

Verifying what actually arrived

Troubleshooting