> ## 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.
# MCP Bridge App
Expose existing REST APIs as MCP tools for AI agents without any API code changes. The MCP Bridge app reads an OpenAPI specification and automatically generates a tool catalog that agents can discover and invoke through the Model Context Protocol. The Orchestrator handles MCP-to-REST translation, identity, and authorization -- so your REST APIs gain AI agent connectivity with zero modification.
## Overview
The MCP Bridge app type enables [AI Identity Gateway](/reference/modes/ai-identity-gateway) mode by translating between the Model Context Protocol and your existing REST APIs. It requires an [MCP Provider](/reference/modes/ai-identity-gateway#setup) to be configured. In bridge mode, the Orchestrator reads an OpenAPI specification and auto-generates an MCP tool catalog -- each operation with an `operationId` becomes a discoverable tool that AI agents can invoke. The Orchestrator enforces inbound authorization on agent requests and handles outbound token exchange when calling the upstream REST API.
## How It Works
The MCP Bridge operates as a translator between the MCP protocol and REST APIs:
1. **Agent discovers tools** -- MCP Bridge exposes your REST API endpoints as discoverable MCP tools. Agents see a catalog of tools with names, descriptions, and parameter schemas -- all generated from your OpenAPI spec.
2. **Agent requests tool** -- The AI agent invokes an MCP tool, which maps to a specific REST API endpoint. The agent provides parameters in MCP format; the Orchestrator handles the translation.
3. **Identity and authorization** -- The Orchestrator authenticates the agent via OAuth, then evaluates OPA policies before the request proceeds.
4. **Token exchange** -- The Orchestrator exchanges the agent's token for a delegation token scoped to the target REST API, preserving the user's identity through the agent-to-API chain.
5. **REST translation** -- The Orchestrator converts the MCP tool call into the corresponding REST API request, mapping parameters to path variables, query strings, headers, and request body as defined in the OpenAPI spec.
6. **Response translation** -- The REST API response is converted back into MCP format and returned to the agent, with audit logging capturing the complete interaction for compliance.
## Use Cases
* **Opening REST APIs to AI agents without API code changes** -- deploy the Orchestrator in front of existing REST APIs and let AI agents discover and call them through MCP, with no modifications to the API itself
* **Multi-API tool catalogs** -- aggregate tools from multiple REST APIs into a single MCP endpoint, giving agents a unified catalog of capabilities with tool namespacing to avoid name collisions
* **Compliance and audit** -- log every agent-to-tool interaction through the Orchestrator, providing a centralized audit trail of which agents called which tools, when, and on behalf of which users
* **Gradual AI adoption** -- start by exposing a few endpoints as MCP tools, then expand coverage over time as confidence grows, using per-tool authorization to control access at each step
## Key Concepts
### OpenAPI-Driven Tool Generation
MCP Bridge reads an OpenAPI specification and automatically generates an MCP tool catalog. Each `operationId` in the spec becomes a discoverable MCP tool. Parameter definitions in the spec determine how MCP tool inputs map to REST request components (path params, query params, headers, body). No manual tool definition is required -- the spec IS the tool catalog.
### Tool Namespacing
When multiple MCP Bridge apps serve tools from different APIs, tool names can collide. The `toolNamespace` feature adds a configurable prefix to all tool names from an app (e.g., `employee_directory_listEmployees`). This lets agents access tools from multiple APIs through a single MCP endpoint without ambiguity.
### Token Exchange for REST APIs
MCP Bridge uses RFC 8693 token exchange to convert the agent's inbound OAuth token into a scoped token for the target REST API. Each tool can have its own scopes and TTL, so a `listEmployees` tool gets `employee:List` scope while `createEmployee` gets `employee:Create` scope. The delegation token preserves both agent and user identity for audit.
### Inbound OPA Policies
Before any REST API call is made, OPA Rego policies evaluate the inbound MCP request. This provides a governance layer at the gateway -- blocking unauthorized tool calls before they reach the backend API. Policies can evaluate agent identity, requested tool name, and user attributes. See the [Authorization Policies guide](/guides/security/policies#opa-authorization-ai-identity-gateway) for the full OPA input schema, output schema, and example policies.
### Upstream Token Validation Best Practice
The target REST APIs do not need to know about MCP, agents, or the Orchestrator -- they receive standard REST requests with OAuth tokens, and the entire MCP-to-REST translation is transparent to the backend.
While no MCP-specific changes are required, it is best practice for upstream REST APIs to validate the received token. Specifically, upstreams should:
* **Validate the token signature and expiry** -- Confirm the token has not been tampered with and is still valid.
* **Confirm the issuer matches the Auth Provider Orchestrator** -- The `iss` claim should match the expected authorization server.
* **Verify the audience claim matches the API's own identifier** -- The `aud` claim should contain the API's registered audience.
* **Check that the token's scopes authorize the requested operation** -- The `scope` claim should include the permissions required for the specific endpoint.
This defense-in-depth approach ensures that even if the gateway is misconfigured or compromised, the upstream API independently enforces authorization.
## Setup
Go to **Applications** in the sidebar and click **Create**. Select **MCP Bridge App** from the application type list.
Enter a **Name** to identify this MCP Bridge application.
Tool namespacing is enabled by default. Enter a **Namespace** prefix for tool names (e.g., `employee_directory_`). Only alphanumeric characters, dots, dashes, and underscores are allowed. Disable the **Enable Tool Namespacing** toggle only if this is the sole MCP app.
Drag or click to upload an icon image (JPEG, PNG, or SVG, up to 2MB).
Click **Add** or drag and drop to upload your OpenAPI specification file (YAML or JSON format). Each operation with an `operationId` in the spec becomes a discoverable MCP tool.
Enter a **Base URL Override** if the actual API URL differs from what is defined in the OpenAPI spec. This is useful when the spec references a public URL but the Orchestrator connects to an internal address.
Under **Inbound Request Policy**, upload an OPA policy definition (.rego file) to enforce fine-grained access control for incoming MCP requests. Policies can evaluate agent identity, requested tool name, and user attributes.
Under **Outbound Request Authorization**, select the **Authorization Type** (Token Exchange). Choose the **Exchange Type**: **Delegation** (recommended -- preserves both agent and user identity) or **Impersonation** (fully assumes user identity). Select the **OIDC Identity Provider** and enter the **Audience** for the target REST API.
Click **Add Tool Configuration** to set per-tool authorization including custom token lifetimes and OAuth scopes. Tool names can be exact matches or regex patterns (prefix with `~ `).
Click **Save** to create the MCP Bridge application.
MCP Bridge apps are defined under the `apps` top-level key with `type: mcpBridge`:
#### Configuration Reference
| Key | Type | Required | Description |
| ------------------------------------------------------------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `apps[].mode` | String | Yes | Bridge mode. Currently only `openapi` is supported. |
| `apps[].toolNamespace.disabled` | Boolean | No | Disable tool namespacing. When `false`, all tool names are prefixed with `toolNamespace.name`. |
| `apps[].toolNamespace.name` | String | No | Prefix for tool names (e.g., `api_`). Characters allowed: a-z, A-Z, 0-9, `.`, `-`, `_`. |
| `apps[].openapi.spec.uri` | String | Conditional | URI to the OpenAPI spec file (e.g., `file:///path/to/spec.yaml`). Mutually exclusive with `spec.data`. |
| `apps[].openapi.spec.data` | String | Conditional | Inline OpenAPI spec content. Mutually exclusive with `spec.uri`. |
| `apps[].openapi.baseURL` | String | No | Override the server URL from the OpenAPI spec. Used when the actual API URL differs from what the spec declares. |
| `apps[].authorization.inbound.opa.name` | String | No | Name identifier for the OPA policy. |
| `apps[].authorization.inbound.opa.file` | String | Conditional | Path to the Rego policy file. Mutually exclusive with `rego`. |
| `apps[].authorization.inbound.opa.rego` | String | Conditional | Inline Rego policy. Mutually exclusive with `file`. |
| `apps[].authorization.outbound.type` | String | No | Outbound authorization type: `tokenExchange` or `unprotected`. |
| `apps[].authorization.outbound.tokenExchange.type` | String | No | Token exchange type: `delegation` (default) or `impersonation`. |
| `apps[].authorization.outbound.tokenExchange.idp` | String | Conditional | Identity provider connector name for token exchange. Required when using token exchange. |
| `apps[].authorization.outbound.tokenExchange.audience` | String | Conditional | Token audience for the target API. Required when using token exchange. |
| `apps[].authorization.outbound.tokenExchange.tools[].name` | String | No | Tool name (exact) or regex pattern (`~ pattern`) for per-tool config. |
| `apps[].authorization.outbound.tokenExchange.tools[].ttl` | String | No | Access token lifetime for this tool (duration string, e.g., `5s`). |
| `apps[].authorization.outbound.tokenExchange.tools[].scopes[].name` | String | No | OAuth scope to request when exchanging tokens for this tool. |
#### OpenAPI-to-MCP Tool Conversion
MCP Bridge reads an OpenAPI specification and automatically generates an MCP tool catalog. Each operation in the spec becomes a discoverable MCP tool.
* **Spec loading** -- Use `openapi.spec.uri` with a `file://` URI to load the spec from a local file (e.g., `file:///etc/maverics/apps/api/openapi.yaml`). Alternatively, use `openapi.spec.data` to provide the spec inline. These two options are mutually exclusive.
* **Base URL override** -- `openapi.baseURL` overrides the `servers[].url` declared in the OpenAPI spec. This is useful when the spec references a public URL but the Orchestrator connects to an internal address.
* **Tool name generation** -- Tool names derive from the `operationId` values in the OpenAPI spec. For example, an operation with `operationId: listEmployees` becomes an MCP tool named `listEmployees` (or `employee_directory_listEmployees` with namespacing enabled).
* **Parameter mapping** -- The Orchestrator maps MCP tool input parameters to the appropriate REST request components (path parameters, query parameters, headers, and request body) based on the OpenAPI parameter definitions.
* **Response translation** -- REST API responses are converted back into MCP tool results. The Orchestrator handles status codes, response bodies, and error conditions.
MCP Bridge supports the `openapi` mode. The tool catalog is auto-generated from the spec -- no manual tool definition is required.
#### Token Exchange
MCP Bridge uses [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token exchange to obtain scoped tokens for outbound API calls. Token exchange supports two modes: delegation (default) and impersonation.
* **Delegation** (`tokenExchange.type: delegation`) -- Delegation is the default and recommended mode. The Orchestrator exchanges the agent's token for a delegation token that contains an `act` (actor) claim identifying the agent alongside the original user's identity. The target API sees both identities -- who the user is and which agent is acting on their behalf -- which supports auditability and least-surprise behavior for downstream services.
* **Impersonation** (`tokenExchange.type: impersonation`) -- The Orchestrator exchanges the agent's token for an impersonation token that fully assumes the user's identity, with no trace of agent involvement. The target API receives a token that looks like it came directly from the user, meaning audit trails at the downstream API will not show agent participation. Impersonation may be required when downstream APIs do not support the `act` claim pattern.
* **Token minting policies** -- When token exchange is processed by the [OIDC Provider](/reference/modes/oidc-provider), administrators can configure OPA-based token minting policies (`authorization.tokenMinting.accessToken.policies` on the OIDC Provider app) to control which tokens get issued. These policies evaluate the token exchange request context and can deny token issuance based on agent identity, requested scopes, audience, or delegating user attributes. This provides a governance layer over token exchange independent of the inbound OPA policies that control tool access.
* **Per-tool scopes** -- Each tool can have its own OAuth scopes and token TTL. This enables least-privilege access: a read-only tool gets `employee:List` scope, while a write tool gets `employee:Create` scope. Tool names support exact matching and regex patterns (prefix with `~`) for wildcarding.
Token exchange configuration for MCP Bridge apps is available via YAML only. The Console UI does not yet support configuring outbound authorization or per-tool token exchange settings.
```yaml theme={null}
authorization:
outbound:
type: tokenExchange
tokenExchange:
type: delegation
idp: oidc-provider
audience: https://api.example.com/
tools:
- name: listResources
ttl: 5s
scopes:
- name: resources:read
- name: "~ create.*"
ttl: 5s
scopes:
- name: resources:write
```
In the example above, the tool named `listResources` is matched exactly, while `~ create.*` uses a regex pattern to match any tool name starting with `create` (e.g., `createResource`, `createUser`). Per-tool token exchange ensures each tool invocation receives a minimally-scoped token.
The token exchange connects to the [OIDC Provider](/reference/modes/oidc-provider) for token issuance. The OIDC Provider must be configured with the `urn:ietf:params:oauth:grant-type:token-exchange` grant type to support token exchange requests.
#### Inbound Authorization (OPA)
MCP Bridge evaluates OPA (Open Policy Agent) Rego policies on inbound MCP requests before performing outbound token exchange. This blocks unauthorized tool calls early, before any outbound API call is made.
Configure `authorization.inbound.opa` with a `name` and either a `file` path to a Rego policy file or inline `rego` content. The policy is evaluated against the MCP request context including the agent's identity and the requested tool.
#### Example
An MCP Bridge app exposing an employee directory REST API as MCP tools with delegation-based token exchange and per-tool scopes:
```yaml theme={null}
apps:
- name: employee-directory-bridge
type: mcpBridge
mode: openapi
toolNamespace:
disabled: false
name: employee_directory_
openapi:
spec:
uri: file:///etc/maverics/apps/employee-directory/openapi.yaml
baseURL: https://employee-directory.example.com/api/v1
authorization:
inbound:
opa:
name: employee-directory-authz
file: /etc/maverics/policies/employee-directory-authz.rego
outbound:
type: tokenExchange
tokenExchange:
type: delegation
idp: oidc-provider
audience: https://employee-directory.example.com/
tools:
- name: listEmployees
ttl: 5s
scopes:
- name: employee:List
- name: getEmployee
ttl: 5s
scopes:
- name: employee:Get
```
## Troubleshooting
**Symptoms:** The agent connects and authenticates successfully, but `tools/list` returns no tools.
**Causes:**
* The OpenAPI spec URL is unreachable from the Orchestrator.
* The spec has parsing errors (invalid YAML/JSON, unsupported OpenAPI features).
* The spec contains no `operationId` definitions -- MCP Bridge requires `operationId` values to generate tool names.
**Resolution:**
* Verify the OpenAPI spec URL is accessible from the Orchestrator host (e.g., `file://` path exists or HTTP URL is reachable).
* Check Orchestrator logs for spec parsing errors.
* Confirm the OpenAPI spec contains operations with `operationId` values.
**Symptoms:** The agent gets an error when invoking a tool. Orchestrator logs show a token exchange failure.
**Causes:**
* The Auth Provider Orchestrator's token endpoint is unreachable.
* The `urn:ietf:params:oauth:grant-type:token-exchange` grant type is not enabled on the OIDC Provider app.
* Audience mismatch -- the `audience` in the token exchange configuration does not match the OIDC Provider's `expectedAudiences`.
**Resolution:**
* Verify the Auth Provider Orchestrator's token endpoint is reachable from the Gateway Orchestrator.
* Ensure the OIDC Provider app has `urn:ietf:params:oauth:grant-type:token-exchange` in its `grantTypes` list.
* Check that the `audience` value in the MCP Bridge app's `tokenExchange` configuration matches the OIDC Provider app's `expectedAudiences`.
**Symptoms:** Tool invocation fails with an upstream authentication or authorization error even though token exchange succeeded.
**Causes:**
* The exchanged token's scopes do not match what the REST API requires.
* The API's expected audience does not match the `aud` claim in the token.
**Resolution:**
* Verify the `scopes` in the tool's `tokenExchange` configuration match the scopes the REST API expects.
* Check the API's expected audience against the `aud` claim in the exchanged token.
* Review the REST API's authorization configuration to confirm it accepts tokens from the Auth Provider Orchestrator.
**Symptoms:** The REST API receives wrong parameters, missing required fields, or unexpected values.
**Causes:**
* The OpenAPI spec parameter definitions do not accurately describe the API's actual parameters.
* Path parameter extraction fails because the `operationId` path template does not match the actual API path structure.
**Resolution:**
* Verify the OpenAPI spec accurately describes all parameters (path, query, header, body) for each operation.
* Check Orchestrator logs for parameter mapping details.
* Test the OpenAPI spec against the actual API to confirm parameter definitions are correct.
**Symptoms:** Authorized agents are denied access to tools they should be able to invoke.
**Causes:**
* The OPA Rego policy contains a logic error that incorrectly denies valid requests.
* The policy input data does not contain the expected fields or values.
**Resolution:**
* Review the OPA policy Rego code for logic errors.
* Add logging to inspect the policy input data and confirm it contains the expected agent identity, tool name, and user attributes.
* Test the policy independently using the OPA CLI (`opa eval`) with sample input data.
## Related Pages
Overview of application types, route patterns, and shared configuration
AI Identity Gateway mode configuration and concepts
Proxy MCP traffic to upstream MCP servers with identity