The system of record for every agent in your organization — what a registry entry carries, and the full walkthrough for registering an agent.
The Agent Registry is TrueFoundry’s implementation of the register-and-own pillar of the governance blueprint: one place where every agent in your organization is registered, discovered, accessed, and governed. Whatever the agent is built on — Bedrock, Vertex AI, LangGraph, a custom HTTP service, an A2A agent, or a copilot embedded in a SaaS product — it enters governance by being registered here, without moving or rewriting anything.
Registration is not documentation — it is what makes the rest of governance enforceable. Each entry gives the agent the attributes the blueprint requires:
Attribute
In TrueFoundry
Verifiable identity
Every registered agent gets exactly one Agent Identity — TrueFoundry-backed or identity provider-backed — created as part of registration.
Accountable owner
The Owner team set on the Access Control step, separate from the grants that control who can use the agent.
Defined authority
Collaborator grants: who may invoke the agent, whom it may act for, and which MCP servers and models it may reach.
Routing
Whether the Agent Gateway proxies inbound calls to the agent, or the registration is governance-only.
Because the gateways deny callers that present no registered identity, the registry doubles as the enforcement point: nothing acts anonymously, and the inventory is complete by construction.
Coming soon — agent discovery. The registry is being extended with the discover pillar: continuous scanning of gateway traffic, cloud platforms, and identity providers to surface agents that exist but are not registered, as a triage queue feeding into registration. See what’s coming soon.
Three ideas the registration flow is built around — the product counterparts of the section’s key concepts.
Agent Identity — how an agent proves who it is
Every agent has an identity: the credential it presents whenever it reaches the Agent
Gateway or the MCP Gateway. The Gateway resolves that credential to this agent and enforces the
permissions granted to it — no matter which layer the call lands on.There are two kinds of identity:
TrueFoundry-backed — TrueFoundry issues and signs the agent’s token. Simplest option, and
the right default for agents you build and run yourself. See the
TrueFoundry as identity broker scenario.
Identity provider-backed — the agent authenticates with a token from your own identity provider
(Okta, Entra, any OIDC provider, or a SPIFFE/SPIRE OIDC endpoint). You map specific claim values to
the agent so an incoming token resolves to it. This unlocks ID-JAG / On-Behalf-Of (OBO) delegation —
see the Okta,
Entra, and
SPIFFE scenarios.
Proxy via Gateway vs Embedded — inbound enforcement vs governance-only
The Config step decides whether the Agent Gateway sits in front of your agent:
Proxy via Gateway (default) — callers hit a TrueFoundry Gateway URL; the Gateway
authenticates the caller, enforces policies and guardrails, then forwards the request to your
agent’s real endpoint. You provide that endpoint URL.
Embedded — no callable URL — the agent is registered for governance only: it appears in
the registry, has an identity, and can be granted access to MCP servers, but TrueFoundry does not
proxy inbound calls to it. No URL required. This is how copilots embedded in third-party products
are governed — their outbound calls still pass through the gateways.
Collaborators — who (and what) can access the agent
Collaborators grant access to the agent. A collaborator can be a user, a team, or
another agent, with one of two roles:
Agent Manager — can edit the agent.
Agent Access — can invoke the agent, and be acted for by it.
On the Agent Registry page, click Create New Agent and select Integrate a Remote Agent.
Create New Agent button on the Agent Registry page
Select Integrate a Remote Agent
Registration is a four-step wizard: Metadata → Agent Identity → Config → Access Control. Each step
is described below. You can also register the agent as YAML with Apply using YAML at any step.
Choose how the agent proves who it is — the mandatory baseline for every agent. Whenever the agent
reaches the MCP Gateway or the Agent Gateway, it presents this credential; the Gateway resolves it to
this agent and enforces the permissions granted to it, no matter which layer the call lands on.
TrueFoundry-backed
Identity provider-backed
TrueFoundry issues and signs the agent’s token. This is the simplest option for agents you build
and run yourself — there is nothing else to configure. After the agent is created, fetch the token
from its ⋮ → Get Token menu (see Getting and using the agent’s token).
Agent Identity step — TrueFoundry-backed selected
The agent authenticates with a token from your own identity provider (Okta, Entra, or any OIDC provider) —
unlocking ID-JAG / OBO. Add one or more Identity Provider Mappings; the agent is authenticated
when any mapping matches.
Field
Required
Description
Identity Provider
Yes
The identity provider to trust. Must already be configured under Platform → Identity Providers.
Subject value
Yes
The claim value that must appear in an incoming identity provider token for it to resolve to this agent.
Use + Add Identity Provider Mappings to add more than one. See the
identity provider scenarios
for the end-to-end flow per provider.
Agent Identity step — Identity provider-backed with identity provider and subject value
Decides whether the Agent Gateway sits in front of the agent.
Proxy via Gateway
Embedded — no callable URL
The Agent Gateway proxies calls to the agent’s endpoint and enforces policy on the way in.
URL to proxy(required) — the agent’s endpoint; the Gateway forwards inbound requests here.
Framework — the protocol the agent speaks:
A2A — the server implements the Agent-to-Agent (A2A) protocol
and exposes a machine-readable agent card. Set the Agent Card Endpoint
(default /.well-known/agent-card.json).
Custom — any other HTTP-based agent API. TrueFoundry forwards requests as-is, with no
protocol-specific handling.
How the Gateway calls this agent(optional) — the credential the Gateway presents when it
forwards a request to the agent’s URL. Same choices as an MCP server target (e.g. header auth or
token passthrough).
Config step — Proxy via Gateway with A2A framework
Config step — Proxy via Gateway with Custom framework
Governance-only registration. The agent appears in the registry, has an identity, and can be
granted access to resources, but the Gateway does not proxy inbound calls to it — there is no
URL. This governs the agent’s outbound calls, not the inbound call.
Config step — Embedded (governance-only, no callable URL)
Grant access to the agent and, optionally, set an owning team.
Collaborators(required) — the list of subjects that have access to this agent. A collaborator
can be a user, a team, or another agent, each with one of two roles.
Owner(optional) — off by default. When enabled, you must select a team that owns this
agent. Ownership is a governance attribute and is separate from the collaborator grants that control
who can use the agent — it is the accountability anchor the
blueprint requires.
Access Control step — collaborators and optional owner
Access is allow-list based — there is no separate “deny” setting. A subject can reach the agent
only if it is added as a collaborator; to deny access, don’t add it (or remove it).
Give a user or team access — add them as a collaborator with Agent Access (invoke only) or
Agent Manager (invoke + edit).
Give another agent access — add the agent as a collaborator (subject agent:<agent-name>). That
agent can then call this one through the Gateway under its own identity.
Give everyone in the tenant access — add the built-in everyone team as a collaborator
(it appears by default with Agent Access). Remove it to restrict the agent to specific subjects.
Remove / deny access — delete the collaborator row (the trash icon). Once the grant is gone, the
Gateway returns 403 – not authorized when that subject tries to reach the agent. Not adding a
subject in the first place has the same effect.
Scope Agent Access to the teams that actually use the agent. Because the same grant also decides
whom the agent may act for, granting it to everyone gives the agent tenant-wide delegation reach —
convenient for getting started, and wider than most agents need.
Collaborator grants are stored on the agent’s identity, so they are enforced wherever the agent’s call
lands — at the Agent Gateway when someone invokes this agent, and at the MCP Gateway when this
agent (as a collaborator elsewhere) calls an MCP server.
The token is the agent’s identity. Your agent presents it as a bearer credential when it calls
resources through TrueFoundry — the MCP servers and models you’ve made it a collaborator on
(see Letting the agent use MCP servers and models),
or another agent it has access to. On each call the Gateway validates the token, resolves it to this
agent, and allows the call only if the agent has been granted access to that specific resource.How the agent obtains that token depends on the identity type you chose in Step 2.
TrueFoundry-backed
Identity provider-backed
TrueFoundry issues and signs the token, but it is not shown at creation time. Fetch it from
the agent’s row in the Agent Registry: open the three-dots (⋮) menu and click Get Token.
Get Token from the agent's three-dots menu in the Agent Registry
1
Get Token
On the agent’s row, open the ⋮ menu and choose Get Token. A TrueFoundry-signed token is
generated on demand (or the current valid one is returned if it already exists). Copy it and
store it securely.
2
Present it to call a resource
Your agent sends the token as Authorization: Bearer <token> when it calls an MCP server
(via the MCP Gateway) or another agent (via the Agent Gateway). The Gateway validates it,
resolves it to this agent, and allows the call if this agent is a collaborator on that
resource — otherwise it returns 403.
3
Refresh when needed
Use Get Token again at any time to retrieve the current token; a fresh one is issued if the
stored one has expired.
There is no TrueFoundry-issued token and no Get Token option — the agent authenticates with
a token from your own identity provider (the one you mapped in Step 2).
1
Obtain a token from your identity provider
The agent gets an access token from your configured identity provider (Okta, Entra, or any OIDC provider) —
e.g. via client-credentials or an OBO / token-exchange flow. The token must carry the claim
value you set as the Subject value in the identity provider mapping.
2
Present it to call a resource
The agent sends that identity provider token as Authorization: Bearer <token> when it calls an MCP server
or another agent. The Gateway validates it against the configured identity provider, reads the
mapped claim, resolves it to this agent, and allows the call if this agent is a collaborator on
that resource.
The agent identity token authenticates the agent itself. Keep it out of source control and out of
anything the model can read back — an agent that can be prompted into disclosing its own token can be
impersonated. To act on behalf of a user, the agent passes the user’s token in Authorization and
its own token in x-tfy-agent-authorization — see
passing the identity in your code.
The agent’s identity is not just for invoking the agent — it’s also what lets the agent reach other
resources. To allow this agent to call an MCP server or use a model, add it as a collaborator on
that resource. This is the same collaborator model used everywhere else; the agent simply appears
alongside users and teams in the picker.
1
Open the resource's Access Control
Go to the MCP server (or the model’s provider account) you want the agent to use, and open its
Collaborators / Access Control section.
2
Add the agent as a collaborator
In the subject picker, switch to the Agents tab and select this agent (the subject is
agent:<agent-name>). Choose the role that fits:
On an MCP server — a role that grants use of the server (so the agent can call its tools).
On a model / provider account — a role that grants use of the integration (so the agent
can call the model).
Adding an agent as a collaborator on an MCP server — the Agents tab in the subject picker
3
Save
Once saved, the grant is stored on the agent’s identity. When the agent presents its token
(TrueFoundry-backed or identity provider-backed) to the Gateway, the Gateway resolves it to this agent and
allows the call to that MCP server or model.
Access is allow-list based, exactly like agent access control: the agent
can reach a resource only if it is a collaborator on that resource. Remove the collaborator to
revoke access — the Gateway then returns 403 – not authorized for that agent.
To restrict an agent to a subset of a server’s tools, curate that subset as a
Virtual MCP Server and grant the agent access to that
instead of the full server. Per-agent tool scoping on the grant itself is
coming soon.
Being a collaborator settles authorization — whether the agent is allowed to use the server. It
does not by itself provide credentials for the upstream service. Whether an agent can complete the
call therefore depends on how the MCP server authenticates:
MCP server auth
Works with an agent token
Why
No auth
Yes
Nothing to present upstream.
TrueFoundry-managed
Yes
TrueFoundry manages the upstream credential centrally.
Shared / global header
Yes
One credential is shared by every caller, so it is not tied to a person.
Token passthrough
Yes
The Gateway forwards the caller’s TrueFoundry credential.
OAuth2 — client credentials
Yes
App-to-app grant; the token belongs to the application, not a user.
OAuth2 — authorization code
No
Interactive grant: it requires a person to sign in at the provider’s consent screen.
An agent cannot complete an OAuth2 authorization-code flow — there is no human to approve the
consent screen, and the resulting token would belong to that person rather than the agent. Calling
such a server with an agent token returns MCP server authentication required, even when the agent is
a collaborator. If you need an agent to reach a provider like this, configure the MCP server with
client credentials instead where the provider supports it.
Once registered and proxied, the agent is reachable through the Agent Gateway. On the Agent Registry
page, click the code snippet button on the agent to get a ready-to-use snippet.
Agent Registry showing the code snippet button on a registered agent
For A2A agents, the generated snippet handles agent card resolution, client setup, and message
exchange — all routed through TrueFoundry’s proxy with your configured authentication. The caller
presents its own credential (a user token, or an agent’s identity token); the Gateway authenticates
it, applies policy, then forwards to the agent’s endpoint.
Python code snippet using A2A SDK to invoke a registered agent
An Embedded agent (governance-only, no callable URL) is not called through TrueFoundry — it has an
identity and appears in the registry for discovery and access control, but there is no Gateway
endpoint to invoke.
