Protect MCP Servers

Add identity governance to your existing MCP servers — authenticate every agent, authorize every tool call, and audit every action, without modifying your MCP servers.

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

How It Works

MCP Proxy is for when you already have MCP servers running but they lack identity awareness. Maybe you built MCP servers that expose tools for your AI agents, but those servers do not know who is calling them or whether the caller is authorized. MCP Proxy solves this by adding an identity-aware layer between your agents and your existing MCP servers — without modifying either side. The Model Context Protocol (MCP) is an open standard for AI agent-to-tool communication. When you have MCP servers already deployed, they speak MCP natively — agents connect, discover tools, and invoke them. The problem is that vanilla MCP does not include identity. Any agent that can reach your MCP server can invoke any tool. MCP Proxy fixes this gap. The Maverics Orchestrator acts as a transparent proxy between agents and your MCP servers. Agents connect to the Orchestrator (thinking it is the MCP server), and the Orchestrator forwards their requests to your actual MCP servers after applying identity and authorization. Here is the flow:

Agent connects — The AI agent connects to the Orchestrator’s MCP endpoint, treating it as a standard MCP server.
Authentication — 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 and obtains a token, which the gateway validates before allowing the connection to proceed.
Identity injection — For every tool invocation, the Orchestrator injects identity context into the request before forwarding it to the upstream MCP server. This context includes the agent’s identity, the delegating user’s identity, and any relevant claims or attributes.
Authorization — The Orchestrator evaluates authorization policies to determine whether this agent, acting on behalf of this user, is allowed to invoke this specific tool.
Transparent forwarding — The Orchestrator exchanges the agent’s token for a short-lived, narrowly scoped token specific to the tool being invoked, then forwards the authorized request to the upstream MCP server with this fresh token and identity context attached. The MCP server receives the request as if the agent connected directly — but now with identity information it can use.
Response passthrough — The MCP server’s response flows back through the Orchestrator to the agent, with audit logging capturing the complete interaction.

MCP Proxy vs MCP Bridge: MCP Proxy proxies existing MCP server connections with identity injection — choose it when you already have MCP servers running. MCP Bridge translates REST APIs into MCP tools — choose it when you have REST APIs, not MCP servers.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 and resolve user context.
One or more existing MCP servers — These are the upstream MCP servers that your AI agents will access through the proxy. They must be reachable from the Orchestrator over the network.
An AI agent that supports the Model Context Protocol (MCP) — The agent connects to the Orchestrator’s MCP endpoint (not directly to your MCP servers).

Configure MCP Proxy

Configure the MCP Provider

The MCP Provider is the Orchestrator’s entry point for AI agent connections — the same component used by MCP Bridge. It handles MCP transport, agent authentication via OAuth, and routes tool calls to the correct MCP Proxy app.

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.

AI Identity Gateway mode selection screen in Maverics Console showing MCP Proxy option

Define the MCP Provider and the OIDC connector for agent authentication. This configuration is identical to the MCP Bridge setup — the MCP Provider serves both Bridge and Proxy apps.

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 configuration is shared across all MCP apps (both Bridge and Proxy). Agents authenticate once at the MCP Provider level (via the Auth Provider Orchestrator) and can then invoke tools from any registered MCP app.

Define the MCP Proxy app

Register your upstream MCP server as an MCP Proxy app. The Orchestrator proxies MCP protocol natively — it receives MCP requests from agents and forwards them to your upstream MCP server over the Streamable HTTP transport.

Console UI
Configuration

Upstream MCP server registration screen in Maverics Console showing server endpoint and transport settings

Define an MCP Proxy app in the apps section. The upstream configuration points to your existing MCP server, and toolNamespace prefixes tool names to avoid collisions.

maverics.yaml

apps:
  - name: my-mcp-server-proxy
    type: mcpProxy
    toolNamespace:
      disabled: false
      name: my_server_
    upstream:
      transport: stream
      stream:
        url: http://mcp-server.example.com:8080/mcp
        connection:
          dialTimeout: 10s
          keepAlive:
            interval: 15s
          pool:
            maxIdleConns: 100
            maxIdleConnsPerHost: 100

The upstream.stream.url points to your MCP server’s Streamable HTTP endpoint. The toolNamespace.name prefix is added to all tools from this upstream server — for example, my_server_listItems. This prevents naming collisions when you proxy multiple MCP servers.The connection settings control how the Orchestrator maintains its connection pool to the upstream MCP server, including dial timeouts and keep-alive intervals.

If your MCP servers are behind a firewall or VPN, make sure the Orchestrator has network access to them. The Orchestrator needs to reach each upstream server to discover its tools and forward requests.

Configure authorization

Like MCP Bridge, every MCP Proxy app requires both inbound authorization (OPA policy) and outbound authorization (how the Orchestrator authenticates to the upstream MCP server on behalf of the agent). This is the same authorization pattern used across all MCP apps.

Console UI
Configuration

Agent authentication and authorization configuration screen in Maverics Console for MCP Proxy

The outbound authorization is where the Orchestrator’s per-tool token exchange happens. Instead of forwarding the agent’s original token to your MCP server, the Orchestrator mints a fresh, short-lived token for each tool invocation — scoped to exactly the permissions that tool needs, with a TTL measured in seconds.Add the authorization block to your MCP Proxy app. The inbound section defines the OPA policy, and the outbound section configures token exchange (or marks the upstream as unprotected).

maverics.yaml

apps:
  - name: my-mcp-server-proxy
    type: mcpProxy
    toolNamespace:
      disabled: false
      name: my_server_
    upstream:
      transport: stream
      stream:
        url: http://mcp-server.example.com:8080/mcp
        connection:
          dialTimeout: 10s
          keepAlive:
            interval: 15s
          pool:
            maxIdleConns: 100
            maxIdleConnsPerHost: 100
    authorization:
      inbound:
        opa:
          name: my-mcp-server-inbound-authz
          rego: |
            package orchestrator

            default result["allowed"] := false

            result["allowed"] := true {
              input.request.mcp.tool.params.name == "listItems"
            }

            result["allowed"] := true {
              input.request.mcp.tool.params.name == "getItem"
            }
      outbound:
        type: tokenExchange
        tokenExchange:
          type: delegation
          idp: auth-provider
          audience: https://mcp-server.example.com/
          tools:
            - name: listItems
              ttl: 5s
              scopes:
                - name: item:List
            - name: getItem
              ttl: 5s
              scopes:
                - name: item:Get
            - name: createItem
              ttl: 5s
              scopes:
                - name: item:Create
            - name: updateItem
              ttl: 5s
              scopes:
                - name: item:Update

Inbound authorization (OPA): The Rego policy controls which tool calls are allowed. The OPA input schema provides input.request.mcp.tool.params.name (the tool name), input.request.mcp.tool.params.arguments (the tool arguments), input.request.oauth.client_id (the agent), and input.source.ip (the client IP).Outbound authorization (token exchange): Each tool gets its own scopes and TTL for the delegated token. The type: delegation means the exchanged token preserves both the agent’s and the delegating user’s identity.This means when an agent calls listItems, the Orchestrator mints a token with only item:List scope that expires in 5 seconds. When the same agent calls createItem next, a completely different token is minted with only item:Create scope. Every tool invocation gets a fresh, minimal-privilege token — nothing is reused or over-scoped.If your upstream MCP server does not require authentication, use type: unprotected:

authorization:
  inbound:
    opa:
      name: my-mcp-server-inbound-authz
      file: /etc/maverics/policies/my-mcp-server-inbound-authz.rego
  outbound:
    type: unprotected

See MCP Proxy Reference for all available fields.

If your upstream MCP servers are also accessible directly (not just through the proxy), agents could bypass the identity layer by connecting to the MCP server directly. Restrict network access so that MCP servers only accept connections from the Orchestrator.

Verify proxied connections

Test the complete flow by connecting an AI agent to MCP Proxy and verifying that identity context is correctly injected into upstream requests.Connect your agent to the Orchestrator’s MCP endpoint and invoke a tool. Then check:

Agent authentication — The Orchestrator logs show the agent was authenticated successfully
Tool discovery — The agent sees tools from all registered upstream MCP servers
Identity injection — The upstream MCP server received the request with identity context attached (check the MCP server’s logs or add a debug tool that echoes received metadata)
Authorization enforcement — Try invoking a tool the agent should not have access to and confirm the request is denied

Success! Your existing MCP servers are now protected by the Orchestrator’s identity layer. Agents authenticate before accessing tools, identity context is injected into every request, and authorization policies control which tools each agent can use.

Troubleshooting

Connection timeouts to upstream MCP servers

If the Orchestrator cannot reach your upstream MCP servers, agents will see connection timeout errors. Check the following:

Verify that the upstream MCP server is running and listening on the configured endpoint.
Test network connectivity from the Orchestrator to the MCP server. If the server is behind a firewall, ensure the Orchestrator’s IP is allowed.
Check the transport protocol configuration — if the MCP server uses HTTP with Server-Sent Events but the Orchestrator is configured for stdio (or vice versa), the connection will fail.
Look at the Orchestrator logs for specific timeout or connection error details.

Identity not propagating to upstream MCP server

If your MCP server is receiving requests but without identity context, the outbound authorization configuration may be incorrect:

Verify the outbound type is set to tokenExchange (not unprotected) if you need identity context forwarded.
Check that the token exchange idp references a valid connector and that the audience matches what the upstream server expects.
If using per-tool scopes, verify the tool names in the tools array match the actual tool names from the upstream MCP server.
Enable debug logging in the Orchestrator to see the full token exchange flow and identify where identity context is lost.

Agent authentication failures

Authentication failures for MCP Proxy follow the same patterns as MCP Bridge:

Verify the agent’s OAuth credentials (client ID and secret) are correct.
Confirm the identity provider is reachable from the Orchestrator.
Check that the agent’s client registration has not expired or been revoked.
Review the Orchestrator logs for the identity provider’s error response.

See the AI Identity overview for more detail on agent credential management and common authentication issues.

What’s Next

AI Identity Overview

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

MCP Proxy Reference

Detailed configuration reference for all MCP Proxy settings and options

Getting Started

Authentication

AI Identity

Operations

Security

How It Works

Prerequisites

Configure MCP Proxy

Troubleshooting

What’s Next

AI Identity Overview

MCP Proxy Reference

Getting Started

Authentication

AI Identity

Operations

Security

​How It Works

​Prerequisites

​Configure MCP Proxy

​Troubleshooting

​What’s Next

AI Identity Overview

MCP Proxy Reference

How It Works

Prerequisites

Configure MCP Proxy

Troubleshooting

What’s Next