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:

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

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

Configure the MCP Provider

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

Define the MCP Provider and the OIDC connector that authenticates agents. The mcpProvider.authorization.oauth section configures how agent tokens are validated.

maverics.yaml

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: <gateway.clientSecret>
    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.

Define the MCP Bridge app

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
Configuration

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.

maverics.yaml

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.

Configure authorization

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
Configuration

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.

maverics.yaml

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

Verify the agent-to-tool flow

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:

Discover tools — The agent’s MCP client lists available tools and sees the REST APIs you registered
Authenticate — The agent presents its OAuth credentials and receives a valid session
Invoke a tool — The agent calls a tool, and the Orchestrator translates it to the REST API call
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

Agent cannot discover any tools

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.

Authentication fails for agent connections

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.

REST API returns unexpected errors

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

AI Identity Overview

Learn about agent identity concepts and set up the Auth Provider for token exchange

MCP Bridge Reference

Detailed configuration reference for all MCP Bridge settings and options

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

How It Works

Prerequisites

Configure MCP Bridge

Troubleshooting

What’s Next

AI Identity Overview

MCP Bridge Reference

​How It Works

​Prerequisites

​Configure MCP Bridge

​Troubleshooting

​What’s Next

AI Identity Overview

MCP Bridge Reference

How It Works

Prerequisites

Configure MCP Bridge

Troubleshooting

What’s Next