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

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

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

1. **Agent connects** -- The AI agent connects to the Orchestrator's MCP endpoint, treating it as a standard MCP server.
2. **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.
3. **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.
4. **Authorization** -- The Orchestrator evaluates authorization policies to determine whether this agent, acting on behalf of this user, is allowed to invoke this specific tool.
5. **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.
6. **Response passthrough** -- The MCP server's response flows back through the Orchestrator to the agent, with audit logging capturing the complete interaction.

```mermaid theme={null}
flowchart LR
    Agent["AI Agent"] --> Gateway["MCP Proxy<br/>(AI Identity Gateway Orchestrator)"]
    Gateway --> AuthServer["Auth Provider<br/>(Orchestrator / OIDC Provider)"]
    Gateway --> MCP1["MCP Server 1"]
    Gateway --> MCP2["MCP Server 2"]
```

<Tip>
  **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](/guides/ai-identity/overview) for a side-by-side
  comparison of both approaches.
</Tip>

## Prerequisites

* **A running Maverics Orchestrator** -- If you have not installed the Orchestrator yet, follow the [Quick Start guide](/guides/getting-started/quick-start) 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](/reference/orchestrator/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

<Steps>
  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        <Info>
          **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.
        </Info>

        <Frame caption="AI Identity Gateway mode selection with MCP Proxy in Maverics Console">
          <img src="https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max&auto=format&n=yo114yy_clZj7p9v&q=85&s=ea8d2ec72a69d5a8c7955d78abba6a30" alt="AI Identity Gateway mode selection screen in Maverics Console showing MCP Proxy option" width="800" height="400" data-path="images/placeholder.svg" />
        </Frame>
      </Tab>

      <Tab title="Configuration">
        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.

        ```yaml maverics.yaml theme={null}
        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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        <Info>
          **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.
        </Info>

        <Frame caption="Upstream MCP server registration in Maverics Console">
          <img src="https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max&auto=format&n=yo114yy_clZj7p9v&q=85&s=ea8d2ec72a69d5a8c7955d78abba6a30" alt="Upstream MCP server registration screen in Maverics Console showing server endpoint and transport settings" width="800" height="400" data-path="images/placeholder.svg" />
        </Frame>
      </Tab>

      <Tab title="Configuration">
        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.

        ```yaml maverics.yaml theme={null}
        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.
      </Tab>
    </Tabs>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        <Info>
          **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.
        </Info>

        <Frame caption="Agent authentication and authorization for MCP Proxy in Maverics Console">
          <img src="https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max&auto=format&n=yo114yy_clZj7p9v&q=85&s=ea8d2ec72a69d5a8c7955d78abba6a30" alt="Agent authentication and authorization configuration screen in Maverics Console for MCP Proxy" width="800" height="400" data-path="images/placeholder.svg" />
        </Frame>
      </Tab>

      <Tab title="Configuration">
        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).

        ```yaml maverics.yaml theme={null}
        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.http.headers` (including the inbound access token), and `input.source.ip` (the client IP). See the [Authorization Policies guide](/guides/security/policies#opa-authorization-ai-identity-gateway) for the full input schema and example policies.

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

        ```yaml theme={null}
        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](/reference/orchestrator/applications/mcp-proxy) for all available fields.
      </Tab>
    </Tabs>

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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:

    1. **Agent authentication** -- The Orchestrator logs show the agent was authenticated successfully
    2. **Tool discovery** -- The agent sees tools from all registered upstream MCP servers
    3. **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)
    4. **Authorization enforcement** -- Try invoking a tool the agent should not have access to and confirm the request is denied

    <Check>
      **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.
    </Check>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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 -- ensure the MCP server and
      the Orchestrator are using compatible transport protocols.
    * Look at the Orchestrator logs for specific timeout or connection error
      details.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/guides/ai-identity/overview) for more
    detail on agent credential management and common authentication issues.
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="AI Identity Overview" icon="compass" href="/guides/ai-identity/overview">
    Learn about agent identity concepts and set up the Auth Provider for token exchange
  </Card>

  <Card title="MCP Proxy Reference" icon="rectangle-list" href="/reference/orchestrator/applications/mcp-proxy">
    Detailed configuration reference for all MCP Proxy settings and options
  </Card>
</CardGroup>