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.

Console terminology: In the Maverics Console, the combination of applications, policies, and connector bindings is managed through User Flows. In YAML, these elements are configured directly within each app’s configuration block under apps[].

Overview

The MCP Bridge app type enables AI Identity Gateway mode by translating between the Model Context Protocol and your existing REST APIs. It requires an MCP Provider 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:

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.
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.
Identity and authorization — The Orchestrator authenticates the agent via OAuth, then evaluates OPA policies before the request proceeds.
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.
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.
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.

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

Console UI
Configuration

Navigate to Applications

Go to Applications in the sidebar and click Create. Select MCP Bridge App from the application type list.

Set the application name

Enter a Name to identify this MCP Bridge application.

Configure tool namespacing

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.

Upload an application icon (optional)

Drag or click to upload an icon image (JPEG, PNG, or SVG, up to 2MB).

Upload the OpenAPI specification

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.

Set the base URL override (optional)

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.

Configure inbound authorization

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.

Configure outbound authorization

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.

Add tool configurations (optional)

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 ~ ).

Save

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 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, 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.

Console UI
Configuration

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.

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 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:

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

Tool discovery returns empty list

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.

Token exchange fails during tool invocation

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.

REST API returns 401/403 after token exchange

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.

Parameter mapping errors

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.

OPA policy evaluation blocks valid requests

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.

Applications

Overview of application types, route patterns, and shared configuration

AI Identity Gateway

AI Identity Gateway mode configuration and concepts

MCP Proxy App

Proxy MCP traffic to upstream MCP servers with identity

Console Administration

Orchestration

Overview

How It Works

Use Cases

Key Concepts

OpenAPI-Driven Tool Generation

Tool Namespacing

Token Exchange for REST APIs

Inbound OPA Policies

Upstream Token Validation Best Practice

Setup

Configuration Reference

OpenAPI-to-MCP Tool Conversion

Token Exchange

Inbound Authorization (OPA)

Example

Troubleshooting

Applications

AI Identity Gateway

MCP Proxy App

Console Administration

Orchestration

​Overview

​How It Works

​Use Cases

​Key Concepts

​OpenAPI-Driven Tool Generation

​Tool Namespacing

​Token Exchange for REST APIs

​Inbound OPA Policies

​Upstream Token Validation Best Practice

​Setup

​Configuration Reference

​OpenAPI-to-MCP Tool Conversion

​Token Exchange

​Inbound Authorization (OPA)

​Example

​Troubleshooting

​Related Pages

Applications

AI Identity Gateway

MCP Proxy App

Overview

How It Works

Use Cases

Key Concepts

OpenAPI-Driven Tool Generation

Tool Namespacing

Token Exchange for REST APIs

Inbound OPA Policies

Upstream Token Validation Best Practice

Setup

Configuration Reference

OpenAPI-to-MCP Tool Conversion

Token Exchange

Inbound Authorization (OPA)

Example

Troubleshooting

Related Pages