Overview

Secure AI agent access to your APIs and MCP tools with identity, authentication, and authorization on every call. The Maverics Orchestrator lets you control which agents can access which tools, trace every action back to the human user who authorized it, and audit everything — so AI agents operate with the same identity governance as your human users. The Orchestrator provides two approaches for securing AI agent access through the Model Context Protocol (MCP), an open standard that lets AI agents discover and invoke tools in a structured, protocol-driven way. Each approach adds identity, authentication, and authorization to MCP connections in a different way, depending on your architecture and what you already have in place. Whether you have existing REST APIs you want to open up to AI agents or existing MCP servers that need identity awareness — there is an approach that fits your situation.

Choose Your Approach

Approach	When to Use	How It Works
Expose APIs to Agents	You have existing REST APIs you want AI agents to access	Translates REST APIs into MCP tools automatically — agents discover and invoke tools via MCP while the Orchestrator handles the REST translation behind the scenes
Protect MCP Servers	You have existing MCP servers that need identity	Proxies MCP connections with identity injection — the Orchestrator sits between agents and your MCP servers, adding authentication and authorization to every tool invocation

Not sure which approach to start with? If you have REST APIs today and want to expose them to AI agents, start with MCP Bridge. If you already have MCP servers running, start with MCP Proxy.

Agent Identity Concepts

AI agents are not humans — but they still need identity. When an AI agent accesses a tool, reads data, or performs an action on behalf of a user, something needs to answer these questions: Who is this agent? Who authorized it to act? What is it allowed to do? And what did it actually do? Agent identity addresses this by adding three capabilities that traditional service accounts lack:

Delegation chains — Every agent action traces back to the human user who authorized it. When Agent X accesses a tool, the system knows that Alice delegated authority to Agent X and that Alice’s permissions (not just the agent’s) determine what the agent can do. This is implemented through OAuth 2.0 token exchange, which supports two modes. Delegation (default) produces a token with an act claim that identifies both the user and the agent acting on their behalf, giving downstream services full visibility for auditability. Impersonation produces a token that fully assumes the user’s identity, with no trace of agent involvement — use this when downstream services do not support the actor claim pattern. See the MCP Bridge and MCP Proxy references for configuration details.
Dynamic scopes — Agent permissions can change based on context. An agent might have broad scopes for one task and narrow scopes for another, depending on what the delegating user authorized. Scopes are named permissions (like read:orders, write:invoices, or admin:users) that your identity provider issues in the agent’s token.
Action-level audit — Every tool invocation is logged with the full identity context: which agent, which user, which tool, what parameters, and what result. This gives you a complete audit trail that satisfies compliance requirements and enables forensic analysis when something goes wrong.

The Maverics Orchestrator works with your existing identity provider to manage agent identity. You register agents in your identity provider (just like you register applications), configure their scopes and permissions, and the Orchestrator enforces those permissions at runtime — whether you are using MCP Bridge or MCP Proxy mode.

How Token Security Works

The AI Identity Gateway involves two orchestrator deployments working together:

Auth Provider Orchestrator — A separate orchestrator deployment running as an OIDC Provider (authorization server). It handles agent authentication, token issuance, and token exchange (minting short-lived, scoped delegation tokens for each tool invocation).
AI Identity Gateway Orchestrator — Runs the MCP Provider with MCP Bridge and/or MCP Proxy apps. It handles MCP transport, tool routing, inbound authorization (OPA policies), and upstream forwarding.

These can be the same orchestrator instance for simpler deployments, but are typically separate deployments in production. Every tool invocation gets its own token. When an agent calls a tool, the AI Identity Gateway Orchestrator does not reuse the agent’s existing token or forward it to the upstream service. Instead, it requests a token exchange from the Auth Provider Orchestrator — trading the agent’s token for a brand-new token specific to that single tool call. Each token carries only the scopes that tool needs (like employee:List for listing employees) and expires in seconds (typically a ttl of 5s). A different tool call a moment later gets a completely different token with different scopes.

MCP Spec OAuth Discovery (RFC 9470)

When an agent first connects to the AI Identity Gateway, it goes through a standards-based OAuth discovery flow:

The agent connects to the AI Identity Gateway Orchestrator’s MCP endpoint.
The gateway returns a 401 along with a pointer to its protected resource metadata endpoint.
The gateway exposes /.well-known/oauth-protected-resource (per RFC 9470), which returns protected resource metadata including the list of authorization server(s) the agent can authenticate against.
The agent reads the metadata, authenticates against the Auth Provider Orchestrator (one of the listed authorization servers), and obtains a token.
The agent returns to the gateway with a valid token. The gateway validates the token and proceeds with tool discovery and invocation.

This flow means agents do not need to be pre-configured with authorization server URLs — they discover them dynamically from the gateway’s protected resource metadata. Traditional approaches give agents broad, long-lived tokens that accumulate permissions. The Orchestrator takes the opposite approach: every tool invocation gets a fresh, minimal-privilege token that expires in seconds. No single token ever carries more permissions than a single tool needs, and no token lives longer than it takes to complete the call.

Set Up the Auth Provider

Set up the OIDC Provider for agent tokens

The OIDC Provider you configure here is the Orchestrator’s own token minting infrastructure. It does not just validate tokens from an external provider — it issues short-lived, narrowly scoped tokens for each tool invocation. You configure it with token exchange grant types so it can mint delegation tokens that carry both the agent’s identity and the delegating user’s identity.

Console UI
Configuration

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

This configuration is for the Auth Provider Orchestrator deployment — the separate orchestrator instance that runs the OIDC Provider. It is not the same deployment as the AI Identity Gateway Orchestrator that runs the MCP Provider.Configure the oidcProvider and register the AI Identity Gateway as an OIDC application with token exchange grants and custom scopes for MCP tools.

maverics.yaml

connectors:
  - name: upstream-idp
    type: oidc
    oidcWellKnownURL: https://your-idp.example.com/.well-known/openid-configuration
    oauthClientID: orchestrator-client
    oauthClientSecret: <idp.clientSecret>
    oauthLoginRedirect:
      urls:
        - https://your-auth-server.example.com/oidc-callback
    oauthLogoutRedirect:
      urls:
        - https://your-auth-server.example.com/logout
    disablePKCE: false
    scopes: openid profile email

oidcProvider:
  correlateSession: true
  discovery:
    issuer: https://your-auth-server.example.com
    endpoints:
      wellKnown: https://your-auth-server.example.com/.well-known/oauth-authorization-server
      jwks: https://your-auth-server.example.com/oauth2/jwks
      auth: https://your-auth-server.example.com/oauth2/auth
      token: https://your-auth-server.example.com/oauth2/token
      userinfo: https://your-auth-server.example.com/oauth2/userinfo
      introspect: https://your-auth-server.example.com/oauth2/introspect
  jwks:
    - algorithm: RSA256
      publicKey: <oidc.signingPublicKey>
      privateKey: <oidc.signingPrivateKey>

The OIDC Provider issues tokens that the AI Identity Gateway validates when agents connect. The jwks section defines the signing keys used to sign tokens — the gateway fetches the public key from the jwks endpoint to verify token signatures.

Treat agent credentials with the same care as user passwords. Store the client secret in a secret provider — never in source code, configuration files, or environment variables that might be logged or exposed.

Register the AI Identity Gateway as an OIDC application that can perform token exchange. This client uses the urn:ietf:params:oauth:grant-type:token-exchange grant type to exchange a user’s token for a delegation token scoped to specific downstream APIs.

Console UI
Configuration

Define the gateway client in the apps section with grantTypes that include both client_credentials and token-exchange. Configure customScopes for the MCP tools the gateway will broker access to.

maverics.yaml

apps:
  - name: ai-identity-gateway
    type: oidc
    clientID: ai-identity-gateway
    credentials:
      secrets:
        - <gateway.clientSecret>
    grantTypes:
      - client_credentials
      - urn:ietf:params:oauth:grant-type:token-exchange
    accessToken:
      type: jwt
    allowedAudiences:
      - https://your-api.example.com/
      - https://mcp-server.example.com/
    customScopes:
      scopes:
        - name: user:List
        - name: user:Get
        - name: user:Create
        - name: user:Update
        - name: item:List
        - name: item:Get
        - name: item:Create
    claimsMapping:
      email: upstream-idp.email
      name: upstream-idp.name
      sub: upstream-idp.sub

The grantTypes array enables both client_credentials (for machine-to-machine auth) and urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693 token exchange for delegation). The allowedAudiences list restricts which downstream services the gateway can request tokens for. The customScopes define the per-tool permissions that can be included in exchanged tokens.Administrators can also configure token minting policies on the OIDC Provider app (authorization.tokenMinting.accessToken.policies) to apply OPA-based governance over which tokens get issued during exchange. This provides a second control point beyond inbound OPA policies — inbound policies control which tool calls are allowed, while token minting policies control which tokens are issued. See the OIDC Provider reference for configuration details.

Per-Tool Token Exchange

Each tool in the tools array gets its own ttl and scopes, and each tool invocation triggers a separate token exchange operation. This is not a single token with all scopes — every tool call gets its own freshly minted token.For example, when an agent calls listEmployees, the Orchestrator mints a token with only employee:List scope, valid for 5 seconds. When the same agent calls createEmployee a moment later, the Orchestrator performs a completely separate token exchange, minting a different token with only employee:Create scope, also valid for 5 seconds. The first token has already expired by the time the second call completes.This means no token ever accumulates permissions across tools, and no token outlives its purpose. The ttl and scopes fields in the YAML above are not just configuration — they define the security boundary for each individual tool invocation.

Document your scope naming convention and share it with your team. Consistent scope names (like always using the action:resource pattern) make policies easier to write, review, and audit.

Guides

Expose APIs to Agents

Make your existing REST APIs available to AI agents as discoverable MCP tools with full identity and authorization

Protect MCP Servers

Add identity governance to your existing MCP servers — authenticate every agent and authorize every tool call

Troubleshooting

Agent credentials rejected by identity provider

If an agent cannot authenticate with its client credentials, check the following:

Verify the client ID and client secret are correct. Client secrets are often only shown once when created — if you have lost the secret, generate a new one in your identity provider.
Check that the agent’s application registration is active and has not been disabled or deleted in the identity provider.
Confirm the grant type is set to “client_credentials” in the agent’s application registration.
Verify that the token endpoint URL in the Orchestrator’s identity connector matches your identity provider’s actual token endpoint.
If the agent’s credentials have an expiration date, check whether they have expired.

Delegation chain not resolving

If the Orchestrator cannot resolve the delegation chain (the agent authenticates but the user context is missing):

Verify that the delegated token includes the act (actor) claim or whatever custom claim your identity provider uses for delegation.
Check that the token exchange was performed correctly — the original user token must be exchanged for a delegated agent token, not simply passed through.
Verify that the gateway client’s grantTypes includes urn:ietf:params:oauth:grant-type:token-exchange.
If your identity provider does not support the standard OAuth 2.0 token exchange, check the Orchestrator’s identity connector documentation for provider-specific delegation configuration.
Enable debug logging in the Orchestrator to see the full token contents and identify which claims are present or missing.

Token exchange fails with invalid audience

If the token exchange succeeds but the downstream service rejects the exchanged token:

Verify the allowedAudiences in the gateway client includes the audience value used in the MCP app’s outbound.tokenExchange.audience.
Check that the downstream service’s expected audience matches the audience value in the token exchange configuration.
Review the exchanged token’s claims (using a JWT debugger) to confirm the aud claim contains the expected value.

AI Identity Gateway Reference

Detailed configuration reference for all AI Identity Gateway modes and settings

Security Guides

TLS, secrets management, authorization policies, and compliance guides

Authentication Guides

SSO, OIDC, SAML federation, and identity provider migration guides

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

Choose Your Approach

Agent Identity Concepts

How Token Security Works

MCP Spec OAuth Discovery (RFC 9470)

Set Up the Auth Provider

Per-Tool Token Exchange

Guides

Expose APIs to Agents

Protect MCP Servers

Troubleshooting

AI Identity Gateway Reference

Security Guides

Authentication Guides

​Choose Your Approach

​Agent Identity Concepts

​How Token Security Works

​MCP Spec OAuth Discovery (RFC 9470)

​Set Up the Auth Provider

​Per-Tool Token Exchange

​Guides

Expose APIs to Agents

Protect MCP Servers

​Troubleshooting

​Related Pages

AI Identity Gateway Reference

Security Guides

Authentication Guides

Choose Your Approach

Agent Identity Concepts

How Token Security Works

MCP Spec OAuth Discovery (RFC 9470)

Set Up the Auth Provider

Per-Tool Token Exchange

Guides

Troubleshooting

Related Pages