MCP Proxy

​

Overview

​

How It Works

1. Agent connects — The AI agent connects to the Orchestrator’s MCP endpoint (SSE or Streamable HTTP).
2. OAuth authentication — The Orchestrator validates the agent’s OAuth token against the configured authorization server.
3. Tool discovery — The Orchestrator proxies tool discovery to the upstream MCP server and returns the available tools (optionally namespaced with a prefix).
4. Policy evaluation — When the agent invokes a tool, the Orchestrator evaluates OPA policies before forwarding the request.
5. Token exchange — The Orchestrator exchanges the agent’s token for a delegation token scoped to the upstream MCP server, with per-tool scopes and TTLs.
6. Upstream forwarding — The tool call is forwarded to the upstream MCP server via the configured transport (stdio subprocess or HTTP streaming).
7. Response passthrough — The upstream server’s response flows back through the Orchestrator to the agent, with audit logging capturing the interaction.

​

Use Cases

• Securing existing MCP servers — Add identity and authorization to upstream MCP servers without modifying them. The Orchestrator handles OAuth authentication and token exchange.
• Per-tool authorization — Apply different scopes and TTLs to different tools based on the tool name. Read-only tools get read scopes; write tools get write scopes.
• Multiple transport support — Connect to upstream servers via stdio (subprocess managed by the Orchestrator) or HTTP streaming (remote MCP server over the network).
• Centralized token exchange — Exchange agent tokens for service-specific delegation tokens with per-tool granularity, preserving the user’s identity through the agent-to-server chain.

​

Key Concepts

​

Transport Flexibility

​

Tool Namespacing

​

Token Exchange for MCP Servers

​

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 server’s own identifier — The aud claim should contain the MCP server’s registered audience.
• Check that the token’s scopes authorize the requested tool invocation — The scope claim should include the permissions required for the specific tool.

​

Interface

apps:
  - name: mission-control-proxy
    type: mcpProxy
    toolNamespace:
      disabled: false
      name: mission_control_
    upstream:
      transport: stream
      stream:
        url: http://mission-control:8080/mcp
        connection:
          dialTimeout: 10s
          keepAlive:
            interval: 15s
          pool:
            maxIdleConns: 100
            maxIdleConnsPerHost: 100
    authorization:
      inbound:
        opa:
          name: mission-control-authz
          file: /etc/maverics/policies/mission-control-authz.rego
      outbound:
        type: tokenExchange
        tokenExchange:
          type: delegation
          idp: oidc-provider
          audience: https://mission-control.example.com/
          tools:
            - name: listMissions
              ttl: 5s
              scopes:
                - name: mission:List
            - name: getMission
              ttl: 5s
              scopes:
                - name: mission:Get
            - name: createMission
              ttl: 5s
              scopes:
                - name: mission:Create

​

Configuration Reference

​

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

​

Upstream Transports

upstream:
  transport: stdio
  stdio:
    command: /usr/local/bin/mcp-server
    args:
      - --port
      - "0"
    env:
      API_KEY: "{{ env.MCP_SERVER_API_KEY }}"

upstream:
  transport: stream
  stream:
    url: http://mcp-server:8080/mcp
    tls: upstream-tls
    connection:
      dialTimeout: 10s
      keepAlive:
        interval: 15s
      pool:
        maxIdleConns: 100
        maxIdleConnsPerHost: 100

​

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 upstream MCP server 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 upstream MCP server receives a token that looks like it came directly from the user, meaning audit trails at the upstream server will not show agent participation. Impersonation may be required when upstream MCP servers 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. Tool names support exact matching and regex patterns for wildcarding.

authorization:
  outbound:
    type: tokenExchange
    tokenExchange:
      type: delegation
      idp: oidc-provider
      audience: https://service.example.com/
      tools:
        - name: listItems
          ttl: 5s
          scopes:
            - name: items:read
        - name: "~ create.*"
          ttl: 5s
          scopes:
            - name: items:write

​

Inbound Authorization (OPA)

​

Troubleshooting

​

Related Pages