> ## 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
(AI Identity Gateway Orchestrator)"]
Gateway --> AuthServer["Auth Provider
(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.
## 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
**1. 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**
> [!NOTE]
>
> **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.
**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:
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.
**2. 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**
> [!NOTE]
>
> **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.
**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.
> [!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.
**3. 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**
> [!NOTE]
>
> **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.
**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.
> [!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.
**4. 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
> [!TIP]
>
> **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 -- ensure the MCP server and
> the Orchestrator are using compatible transport protocols.
> * 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](/guides/ai-identity/overview) for more
> detail on agent credential management and common authentication issues.
## What's Next
> **[AI Identity Overview](/guides/ai-identity/overview)**
>
> Learn about agent identity concepts and set up the Auth Provider for token exchange
> **[MCP Proxy Reference](/reference/orchestrator/applications/mcp-proxy)**
>
> Detailed configuration reference for all MCP Proxy settings and options