For the complete documentation index, see llms.txt.
Skip to main content

Security options & Secrets

Security of MCP endpoints is a hot topic and let’s face it: a fast-moving one! For that, reShapr has been designed to be flexible and allow many different security options. It has been implemented to allow evolution following the emerging best practices.

In a nutshell, the security options we’ll expose just after will encompass two different concerns:

  • Access to the MCP Endpoint exposed by a reShapr gateway itself,
  • Access to the backend API used by the reShapr gateway once MCP endpoint access is safe.
Security ModelSecurity Model

MCP Endpoint access​

Three different options are available to secure the MCP Server or Endpoint exposed by a reShapr gateway:

  • None - which is the default and probably not a good idea! This means that the gateway endpoint is unsecured. In this situation, all headers are propagated to the backend API. So this is a scenario that you would use just for a quick test OR if you decide - with great generosity - to provide a free MCP Server to the world!
  • API Key - means that the gateway will validate the value of the specific x-reshapr-key header in the incoming MCP requests. The API Key is generated and transmitted just once at configuration time. It represents a token that you must store securely and must only share with trusted users. reShapr allows renewing an API Key and propagates the change to the gateways exposing the corresponding service.
  • OAuth2 Bearer - means that the gateway will validate the OAuth2 token provided as a Bearer in the Authorization header in the incoming requests. During the configuration time, you choose your OAuth2 Authorization Servers and the list of required scopes to access the MCP Server. This information is propagated to the gateways that will be in charge of trusting the incoming tokens. reShapr gateways implements the different specifications mentioned in the Model Context Protocol Version 2025-06-18 Authorization recommendations such as:
    • OAuth 2.0 Protected Resource Metadata (RFC9728)
    • OAuth 2.0 Authorization Server Metadata (RFC8414)
    • OAuth 2.0 Resource Indicators (RFC 8707)

Backend Secrets​

In addition to protecting the MCP Endpoint or Server, access to the backend API must also be protected. This backend must have a means to validate authentication and authorization proofs coming from the reShapr gateway.

For this purpose, reShapr supports the concept of Secret, which enables the secure storage of information on how to authenticate the backend API call. In reShapr, a Secret can contain different information:

  • A username/password pair - in case the backend API only supports HTTP Basic authentication mechanisms. An Authorization: Basic <base64(username:password)> header will be automatically issued and transmitted to the backend API.
  • A token (with an optional associated header) - in case the backend supports API Key or token-based authentication mechanisms. If no token header is provided, then the default Authorization: Bearer <token> is assumed and transmitted to the backend API, but the token header can hold any value.
  • A X509 certificate - that will be used to secure the transport, in case the backend API is enforcing TLS communication with a client-side certificate.

reShapr also supports Elicitation-based backend secret. Elicitations are a recent addition to the MCP Protocol, coming in version 2025-11-25 of the protocol. Unlike a standard backend Secret, an Elicitation-based one does not require proactive provisioning: when needed, the reShapr MCP Server will return to the user to request backend credentials or initiate an OAuth authorization flow. Two different flows are supported:

Secret references​

Available since reShapr 0.0.14, backend Secrets can also use secret references. This is especially useful in hybrid deployments where the control plane is managed by reShapr, but the Gateway runs in your own premises. In this situation, you may want the control plane to know that a backend credential exists without storing or distributing the actual credential value.

A secret reference uses the ${scheme:reference} convention. When a sensitive value follows this pattern, the Gateway resolves it locally when it needs to call the backend endpoint. The value stored in the control plane is only the reference.

Today, the supported scheme is env, which resolves a value from the Gateway environment:

${env:GITHUB_TOKEN}

When the Gateway needs to authenticate a backend call, it reads GITHUB_TOKEN from the Gateway process environment, falling back to the Gateway configuration sources such as system properties or a .env file. If the value cannot be resolved, the backend call fails explicitly instead of silently sending an empty credential.

References can be used on their own or interpolated within a larger value:

Bearer ${env:API_TOKEN}
${env:DB_USER}:${env:DB_PASSWORD}

Values that do not match the ${scheme:reference} convention keep being used as literal Secret values, so existing Secrets remain compatible.

Secret references are resolved just in time, on every backend call. Resolved values are not cached as control plane data, and they do not need to be synchronized from the control plane to the Gateway. This also makes secret rotation straightforward: update the value in the Gateway environment, and the next backend call uses the new value.

Secret references are honored for sensitive credentials used by the Gateway to reach backend endpoints:

  • Token authentication for REST, GraphQL, and gRPC backends,
  • Basic authentication username and password,
  • PEM-encoded TLS trust material for gRPC backends,
  • OAuth2 client secrets used during authorization-code exchanges.

Public identifiers, such as an OAuth2 client_id, are intentionally kept as literal values because they are exposed in the browser redirect by design.

Using secret references moves the responsibility for protecting the real credential to the Gateway environment. You should scope environment variables to the Gateway process, prefer mounted secrets where your platform supports them, and make sure resolved values are never written to logs or audit trails.

All together!​

MCP Endpoint security options and backend secret are not exclusive, and they’d rather be combined to secure the transmission chain from end to end. To achieve fully secure and authorized usage of your MCP Endpoint provided by reShapr, we recommend considering OAuth2 + Elicitation-based backend Secret when you configure your Service for exposure on a reShapr gateway. In hybrid deployments, secret references can be added to this model when the actual backend credential must remain local to your Gateway runtime.

Agent View