MCP Proxy App (Local development)

  • 3 minute(s) read
Prev Next

MCP Proxy App

Configuration Options

Name

name is the unique identifier for this MCP Proxy app.

Type

type must be "mcpProxy" for MCP Proxy applications.

Upstream

upstream contains the configuration for connecting to the upstream MCP server.

Transport

transport specifies the transport protocol to use. Currently supports "stream". Future support planned for "stdio" and "sse".

Stream

URL
url is the address of the target upstream server.

TLS
tls is the named reference to the TLS config that will be used for communication with the upstream.

Connection
connection defines network connection related properties.

Dial Timeout
dialTimeout is the maximum time to establish a TCP connection.

Keep Alive
keepAlive contains TCP keep-alive settings.

Interval
interval is the time between TCP keep-alive probes.

Pool
pool contains connection pool settings.

Max Idle Connections
maxIdleConns is the maximum number of idle connections across all hosts.

Max Idle Connections Per Host
maxIdleConnsPerHost is the maximum number of idle connections per host.

Tool Namespace

toolNamespace is used to define the tool namespacing rules. Namespaces are added to tool names in order to prevent potential tool name conflicts and to provide agents/LLMs the necessary context to ensure the correct tool is called.

Please note that when writing authorization policy, the namespace is stripped prior to evaluation. This means that namespaces can be changed without the need to update policy rules.

Disabled
disabled allows tools to be registered without a namespace prefix.

Name
name is the tool’s namespace.

Authorization

authorization defines the policy for the app.

Inbound

inbound defines authorization rules for inbound requests. For instance, policy authors may want to craft policies that restrict requests to a certain network zone or specific users.

OPA
opa defines the Open Policy Agent driven authorization policy.

Name
name of the policy.

Rego
rego represents the module definition. Please note that the module's package must be orchestrator. rego and file cannot both be defined at the same time.

File
file is the filepath to the module definition. Please note that the module's package must be orchestrator. file and rego cannot both be defined at the same time.

Outbound

outbound defines how the app authorizes with the upstream MCP server. Available
options include unprotected and tokenExchange.

TokenExchange
tokenExchange defines the parameters of the token exchange. To learn more about token exchange, see RFC 8693.

Type
type defines the type of token exchange that is used. The available options include 'delegation' and 'impersonation'. When not defined, 'delegation' will be used by default.

IDP
idp is the identity provider that will be used for token exchange.

Audience
audience is the audience that will be requested when making the token exchange
grant.

Tools
tools defines a list of per-tool configurations.

name is the name of the tool.

ttl is the client-requested access token lifetime.

scopes defines the list of scopes required to interact with the tool.

High-Availability Deployments

When deploying the MCP Proxy behind a load balancer, the use of sticky sessions is required. This is because the proxy maintains per-session state, including the set of tools available to each client based on authorization policies. This state is stored in-memory on the instance that established the session.

Configure your load balancer to use the Mcp-Session-Id HTTP header for session affinity. MCP clients send their session identifier in this header on every request, so your load balancer must be configured to hash or match on this header value to ensure consistent routing.

Example Configuration

maverics.yaml

apps:
  - name: ticket-service
    type: mcpProxy
    upstream:
      transport: stream
      stream:
        url: https://tickets-internal.example.com/mcp
        connection:
          dialTimeout: 10s
          keepAlive:
            interval: 15s
          pool:
            maxIdleConns: 100
            maxIdleConnsPerHost: 100
    toolNamespace:
      name: tickets-mcp.
    authorization:
      inbound:
        opa:
          name: ticketsPolicy
          file: /etc/maverics/example.rego
      outbound:
        type: tokenExchange
        tokenExchange:
          type: delegation
          idp: oauthConnector
          audience: https://tickets.example.com
          tools:
            - name: ~ .*
              ttl: 2m
              scopes:
                - name: tickets:read
            - name: getHeaders
              ttl: 60s
              scopes:
                - name: tickets:read
                - name: tickets:write

/etc/maverics/example.rego

package orchestrator

default result["allowed"] := false

# Helper rule to extract and decode JWT
jwt_payload := payload if {
	auth_header := input.request.http.headers.Authorization
	startswith(auth_header, "Bearer ")
	token := substring(auth_header, 7, -1)
	[_, payload, _] := io.jwt.decode(token)
}

result["allowed"] if {
	input.request.mcp.tool.params.name == "read_file"
	print("request made with subject of:", jwt_payload.sub)
	contains(jwt_payload.sub, "john@example.com")
	print("access granted to subject:", jwt_payload.sub)
}

result["allowed"] if {
	input.request.mcp.tool.params.name == "write_file"
	print("request made with subject of:", jwt_payload.sub)
	contains(jwt_payload.sub, "jane@example.com")
	print("access granted to subject:", jwt_payload.sub)
}
Related articles