MCP Bridge

​

Overview

​

How It Works

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 — Expose existing REST APIs as MCP tools without modifying API code. Agents discover and invoke your APIs through the standard MCP protocol.
• Multi-API tool catalogs — Aggregate tools from multiple REST APIs into a single MCP tool catalog for agents. One MCP endpoint gives agents access to tools across all your backend services.
• Compliance and audit — Log every agent-to-tool interaction with both agent and user identity for regulatory compliance. Every REST API call made through MCP Bridge includes full identity context.
• Gradual AI adoption — Start with a few REST endpoints and expand the tool catalog over time. You control exactly which APIs are exposed as MCP tools and who can access them.

​

Key Concepts

​

OpenAPI-Driven Tool Generation

​

Tool Namespacing

​

Token Exchange for REST APIs

​

Inbound OPA Policies

​

Upstream Token Validation Best Practice

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

​

Interface

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
            - name: createEmployee
              ttl: 5s
              scopes:
                - name: employee:Create

​

Configuration Reference

​

mcpBridge App Type (apps[].type: mcpBridge)

​

OpenAPI-to-MCP Tool Conversion

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

​

Token Exchange

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

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

​

Inbound Authorization (OPA)

​

Troubleshooting

​

Related Pages