> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Expose APIs to Agents
Make your existing REST APIs available to AI agents as discoverable MCP tools -- with full identity verification and authorization on every call.
## How It Works
MCP Bridge enables AI agents to access your existing REST APIs as MCP tools -- without modifying either the agents or the APIs. The Model Context Protocol (MCP) is an open standard that provides a structured way for AI agents to discover and invoke tools. MCP Bridge brings this capability to your existing REST APIs by translating between the two protocols automatically.
The Maverics Orchestrator sits between the AI agent and your REST APIs, acting as a translator. When an agent makes an MCP tool request, the Orchestrator converts it into the corresponding REST API call. When the REST API responds, the Orchestrator translates the response back into MCP format. This means your REST APIs become discoverable, invocable tools for AI agents -- without any changes to your existing API code.
But translation alone is not enough. Every tool invocation also passes through the Orchestrator's identity and authorization layer. Here is what happens when an agent requests a tool:
1. **Authenticates the agent** -- When the agent first connects, the AI Identity Gateway Orchestrator returns protected resource metadata (per RFC 9470) that tells the agent which authorization server(s) to authenticate against. The agent authenticates with the Auth Provider Orchestrator (or your external IdP) and obtains a token, then presents it to the gateway for validation.
2. **Resolves the user context** -- AI agents typically act on behalf of a human user. The Orchestrator identifies which user delegated authority to the agent, so authorization decisions reflect the user's actual permissions -- not just the agent's.
3. **Evaluates authorization policies** -- The Orchestrator checks whether the agent (acting on behalf of the user) is permitted to invoke the requested tool. Policies can restrict access based on the agent's scopes, the user's group memberships, the specific tool being invoked, or any combination of these factors.
4. **Translates and forwards** -- The Orchestrator exchanges the agent's token for a short-lived, narrowly scoped token specific to the tool being invoked, then converts the MCP tool call into the corresponding REST API request (mapping parameters, headers, and body content) and forwards it to your backend service with this fresh token.
5. **Returns the response** -- The REST API response is translated back into MCP format and returned to the agent, along with any identity context the agent needs for subsequent calls.
```mermaid theme={null}
flowchart LR
Agent["AI Agent"] --> Gateway["MCP Bridge
(AI Identity Gateway Orchestrator)"]
Gateway --> AuthServer["Auth Provider
(Orchestrator / OIDC Provider)"]
Gateway --> API1["REST API 1"]
Gateway --> API2["REST API 2"]
```
**MCP Bridge vs MCP Proxy:** MCP Bridge translates REST APIs into MCP tools --
choose it when you want to expose existing REST APIs to AI agents via MCP. MCP Proxy proxies existing MCP server connections with identity injection -- choose
it when you already have MCP servers running.
See the [AI overview](/guides/ai-identity/overview) for a side-by-side
comparison of both approaches.
## Prerequisites
* **A running Maverics Orchestrator** -- If you have not installed the Orchestrator yet, follow the [Quick Start guide](/guides/getting-started/quick-start) first. The Orchestrator is a small, lightweight runtime that deploys almost anywhere.
* **An identity provider configured as an identity connector** -- The Orchestrator needs an [Identity Fabric](/reference/orchestrator/identity-fabric) to authenticate agents. If you have not connected an identity provider yet, the Quick Start guide covers this step.
* **One or more REST APIs you want to expose as MCP tools** -- These are the backend APIs that AI agents will access. The APIs must use OAuth for authentication (MCP Bridge performs token exchange to call them on behalf of agents) and must be under your organization's control.
* **An OpenAPI spec for your REST API** -- MCP Bridge uses the OpenAPI specification to generate MCP tool definitions from your API endpoints.
* **An AI agent that supports the Model Context Protocol (MCP)** -- The agent connects to MCP Bridge as its MCP server, discovering and invoking tools through the standard MCP protocol.
## Configure MCP Bridge
The MCP Provider is the Orchestrator's entry point for AI agent connections. It handles MCP transport (how agents connect), agent authentication (verifying agent identity via OAuth), and tool routing (directing tool calls to the correct app).
Configure the MCP Provider with transport settings and OAuth-based agent authentication. The MCP Provider supports both SSE (Server-Sent Events) and Streamable HTTP transports.
**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.
Define the MCP Provider and the OIDC connector that authenticates agents. The `mcpProvider.authorization.oauth` section configures how agent tokens are validated.
```yaml maverics.yaml theme={null}
connectors:
# Points to the Auth Provider Orchestrator (the separate OIDC Provider deployment)
- name: auth-provider
type: oidc
oidcWellKnownURL: https://your-auth-server.example.com/.well-known/openid-configuration
oauthClientID: ai-identity-gateway
oauthClientSecret:
oauthLoginRedirect:
urls:
- https://your-gateway.example.com/oidc-callback
oauthLogoutRedirect:
urls:
- https://your-gateway.example.com/logout
mcpProvider:
enabled: true
transports:
sse:
enabled: true
path: "/mcp/sse"
messagePath: "/mcp/message"
keepAlive:
enabled: true
interval: 30s
stream:
enabled: true
path: "/mcp"
session:
enabled: true
headerName: "Mcp-Session-Id"
allowClientTermination: true
timeout: 1h
authorization:
oauth:
enabled: true
metadataPath: /.well-known/oauth-protected-resource
servers:
- wellKnownEndpoint: https://your-auth-server.example.com/.well-known/oauth-authorization-server
refreshInterval: 24h
tokenValidation:
expectedAudiences:
- https://your-gateway.example.com/
method: jwt
jwt:
clockSkew: 15s
```
The MCP Provider enables both SSE and Streamable HTTP transports so agents can connect using whichever method they support. The `authorization.oauth` section configures JWT-based token validation -- the Orchestrator fetches the Auth Provider Orchestrator's signing keys from the well-known endpoint and validates agent tokens against them.
For the full set of AI Identity Gateway mode options, see the
[AI Identity Gateway reference](/reference/modes/ai-identity-gateway).
Register your REST API as an MCP Bridge app. The Orchestrator reads your API's OpenAPI specification and automatically generates MCP tool definitions for each endpoint. Agents discover these tools through the standard MCP protocol.
**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.
Define an MCP Bridge app in the `apps` section. The `openapi.spec.uri` points to your API's OpenAPI specification, and `openapi.baseURL` points to the actual REST API server.
```yaml maverics.yaml theme={null}
apps:
- name: my-api-bridge
type: mcpBridge
mode: openapi
toolNamespace:
disabled: false
name: my_api_
openapi:
spec:
uri: https://your-api.example.com/openapi.yaml
baseURL: https://your-api.example.com/api/v1
```
The `toolNamespace.name` prefix is added to all tool names generated from this API. For example, if your API has a `listUsers` endpoint, agents will see it as `my_api_listUsers`. This prevents naming collisions when you have multiple MCP Bridge apps exposing tools from different APIs.
The `openapi.spec.uri` can be an HTTP URL or a local file path (`file:///path/to/spec.yaml`). The `openapi.baseURL` is the base URL where the Orchestrator sends the translated REST API requests.
Authorization is critical for MCP apps. Every MCP app requires both **inbound** authorization (OPA policy that decides whether a tool call is allowed) and **outbound** authorization (how the Orchestrator authenticates to the upstream REST API on behalf of the agent).
**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.
The outbound authorization is where the Orchestrator's per-tool token exchange happens. Instead of forwarding the agent's original token to your REST API, the Orchestrator mints a fresh, short-lived token for each tool invocation. Each token carries only the scopes needed for that specific tool and expires in seconds.
Add the `authorization` block to your MCP Bridge app. The `inbound` section defines the OPA policy, and the `outbound` section configures token exchange for the upstream REST API.
```yaml maverics.yaml theme={null}
apps:
- name: my-api-bridge
type: mcpBridge
mode: openapi
toolNamespace:
disabled: false
name: my_api_
openapi:
spec:
uri: https://your-api.example.com/openapi.yaml
baseURL: https://your-api.example.com/api/v1
authorization:
inbound:
opa:
name: my-api-bridge-inbound-authz
rego: |
package orchestrator
default result["allowed"] := false
result["allowed"] := true {
input.request.mcp.tool.params.name == "listUsers"
}
result["allowed"] := true {
input.request.mcp.tool.params.name == "getUser"
}
outbound:
type: tokenExchange
tokenExchange:
type: delegation
idp: auth-provider
audience: https://your-api.example.com/
tools:
- name: listUsers
ttl: 5s
scopes:
- name: user:List
- name: getUser
ttl: 5s
scopes:
- name: user:Get
- name: createUser
ttl: 5s
scopes:
- name: user:Create
```
**Inbound authorization (OPA):** The Rego policy evaluates every tool invocation against the OPA input schema. The `input.request.mcp.tool.params.name` field contains the MCP tool name, and `input.request.mcp.tool.params.arguments` contains the tool arguments. You can also access `input.request.http.headers` (including the inbound access token), `input.request.http.method`, and `input.source.ip` for richer policy decisions. See the [Authorization Policies guide](/guides/security/policies#opa-authorization-ai-identity-gateway) for the full input schema and example policies.
**Outbound authorization (token exchange):** The Orchestrator exchanges the agent's token for a delegation token scoped to the target REST API. Each tool can have its own `scopes` (the permissions included in the delegated token) and `ttl` (how long the delegated token is valid). The `idp` references the connector used for the token exchange.
This means when an agent calls `listUsers`, the Orchestrator mints a token with only `user:List` scope that expires in 5 seconds. When the same agent calls `createUser` a moment later, a completely different token is minted with only `user:Create` scope. No single token ever carries more permissions than a single tool needs, and no token lives longer than it takes to complete the call.
For unprotected upstream APIs that do not require authentication, use `type: unprotected` instead of `type: tokenExchange`.
See [MCP Bridge Reference](/reference/orchestrator/applications/mcp-bridge) for all available fields.
Start with a deny-by-default policy and explicitly grant access to specific
tools. This is safer than starting with allow-all and trying to restrict
later -- it ensures agents only access what you intentionally permit.
Test the complete flow by connecting an AI agent to MCP Bridge and invoking a registered tool. This verifies that authentication, authorization, and REST API translation all work correctly end-to-end.
Connect your AI agent to the Orchestrator's MCP endpoint. The agent should be able to:
1. **Discover tools** -- The agent's MCP client lists available tools and sees the REST APIs you registered
2. **Authenticate** -- The agent presents its OAuth credentials and receives a valid session
3. **Invoke a tool** -- The agent calls a tool, and the Orchestrator translates it to the REST API call
4. **Receive a response** -- The REST API response is returned to the agent in MCP format
Check the Orchestrator logs to confirm that each step completed successfully. The logs show authentication events, policy evaluations, API translations, and any errors that occurred.
**Success!** Your REST APIs are now accessible as MCP tools through the
Orchestrator. AI agents authenticate with their credentials, authorization
policies control which tools each agent can access, and every tool
invocation is logged for audit and compliance.
## Troubleshooting
If the agent connects to MCP Bridge but sees no tools, check the following:
* Verify that REST APIs are correctly registered as MCP tools in the Bridge
configuration. Each API endpoint needs a valid URL, method, and tool name.
* Check that the agent has the required scopes to discover tools. Some
configurations restrict tool listing based on the agent's permissions.
* Look at the Orchestrator logs for errors during tool registration. If an
API endpoint is unreachable during startup, the tool may not be registered.
* Confirm that authorization policies do not block tool listing. A policy
that denies all access will also prevent tool discovery.
Agent authentication failures typically have one of these causes:
* The agent's OAuth client credentials (client ID and secret) are incorrect.
Double-check them against your identity provider's application registration.
* The identity provider is not reachable from the Orchestrator. Test
connectivity to your IdP's token endpoint.
* The agent's client registration has expired or been revoked in the identity
provider.
* The Orchestrator's identity connector is misconfigured. Check that the
connector's issuer URL and client configuration match your IdP.
Check the Orchestrator logs for specific authentication error details -- the
logs include the identity provider's error response, which usually identifies
the exact issue.
MCP Bridge translates MCP tool invocations to REST API calls and translates
the responses back. When the underlying REST API returns an error, the
Orchestrator passes it through as an MCP error response.
To isolate the issue:
* Call the REST API directly (bypassing MCP Bridge) to confirm it works on
its own. This tells you whether the issue is in the translation or the API.
* Check the Orchestrator logs for the full REST request and response. The
logs show how MCP Bridge mapped tool parameters to API parameters.
* Verify that parameter mappings are correct -- a common issue is mapping an
MCP tool parameter to the wrong REST query parameter or header.
* If the REST API requires authentication, ensure the outbound authorization
is configured with the correct token exchange settings and scopes.
## What's Next
Learn about agent identity concepts and set up the Auth Provider for token exchange
Detailed configuration reference for all MCP Bridge settings and options