Higress MCP Server Security Boost: API Authentication Safeguarding AI Connections

Higress, as a powerful AI-native API gateway, excels at bridging AI with real-world services. A core capability is its support for seamlessly converting existing OpenAPI specifications into MCP Servers. This allows AI agents to quickly and cost-effectively connect to a vast array of APIs, instantly transforming them into accessible tools and paving the shortest path for AI to interact with the digital world.

When integrating AI with external services via an MCP Server hosted on Higress, there are typically two main stages of authentication to consider:

1. Client-to-MCP Server Authentication: This is the authentication of the MCP Client (e.g., an AI Agent) to the Higress Gateway endpoint where the MCP Server is hosted. Higress provides robust, gateway-level authentication mechanisms for this stage, such as Key Auth, JWT Auth, and OAuth2 support. These existing Higress features ensure that only authorized clients can access your MCP Server.

2. MCP Server-to-Backend API Authentication: Once an authorized client calls an MCP tool, the MCP Server plugin itself may need to authenticate with the final backend REST API that the tool represents.

This announcement focuses on significant enhancements to the second stage: providing comprehensive API authentication capabilities within the Higress MCP Server plugin for its communication with backend REST APIs. This update empowers developers to securely integrate a wider range of backend services by providing flexible and robust mechanisms for managing credentials and authentication flows, all configurable within the MCP Server plugin and aligned with OpenAPI standards.

The following diagram illustrates these two authentication stages:

Newly Added Core Authentication Features (for MCP Server to Backend API)

This release introduces several key features to manage API authentication:

1. Reusable Security Schemes: Define common authentication methods (HTTP Basic, HTTP Bearer, API Key) at the server level.

2. Tool-Specific Backend Authentication: Apply defined security schemes to individual tools, specifying how the MCP Server should authenticate itself when calling the backend REST API.

3. Transparent Credential Passthrough: A powerful feature allowing credentials provided by the MCP client (e.g., an AI assistant) to be securely passed through to the backend API.

4. Flexible Credential Management: Support for default credentials at the scheme level and the ability to override them for specific tools.

Let’s dive into how you can leverage these features.

Defining Security Schemes (server.securitySchemes)

You can now define a collection of securitySchemes at the server level in your MCP Server configuration. This approach aligns with the OpenAPI Specification (OAS3) for defining security requirements, making it familiar and standardized. Each scheme represents a distinct authentication method that your backend APIs might use.

Currently, the Higress MCP Server plugin supports the following scheme types:

• http with scheme: basic (HTTP Basic Auth)

• http with scheme: bearer (HTTP Bearer Token)

• apiKey with in: header or in: query (API Key in header or query parameter)

Support for oauth2 and openIdConnect (OIDC) schemes is planned for future releases, further expanding the range of APIs you can securely integrate.

Configuration Fields for securitySchemes:

Example:

server:
  name: my-secure-api-server
  securitySchemes:
    - id: backendBasicAuth
      type: http
      scheme: basic
      defaultCredential: "service_user:p@$$wOrd"
    - id: backendBearerToken
      type: http
      scheme: bearer
      defaultCredential: "your_static_bearer_token_for_backend"
    - id: backendApiKeyHeader
      type: apiKey
      in: header
      name: X-Internal-ApiKey
      defaultCredential: "secret_backend_api_key"

Applying Security to Backend API Calls (requestTemplate.security)

Once security schemes are defined, you can apply them to the requests your MCP Server makes to backend REST APIs. This is configured within each tool’s requestTemplate:

• requestTemplate.security.id: References the id of a scheme defined in server.securitySchemes.

• requestTemplate.security.credential: (Optional) Allows you to override the defaultCredential from the scheme for this specific tool’s backend call.

Example:

tools:
  - name: fetch-sensitive-data
    description: "Fetches sensitive data from a backend service requiring Bearer token."
    args: # ...
    requestTemplate:
      url: "https://api.internal.com/data"
      method: GET
      security:
        id: backendBearerToken # Uses the 'backendBearerToken' scheme
        # credential: "override_token_for_this_tool_if_needed"

Transparent Credential Passthrough

One of the most powerful additions is the ability to transparently pass credentials from the incoming client request (e.g., from an AI Agent to the MCP Server) through to the backend API call (MCP Server to the actual REST API). This is invaluable when the backend API requires user-specific authentication that the AI client possesses.

How it Works:

1. Client-Side Scheme Definition: The MCP Server needs to know how the client is authenticating itself. This is also defined using a scheme from server.securitySchemes.

2. Tool-Level Security Configuration (tools[].security):

   • id: References the security scheme the client is expected to use when calling this MCP tool. The MCP Server will use this to extract the client’s credential.

   • passthrough: true: This flag enables the passthrough mechanism.

3. Backend Authentication: The requestTemplate.security (as described above) defines how the passthrough credential will be applied to the backend API call.

Example:

Imagine an AI client calls your MCP tool with a user-specific JWT Bearer token. You want to use this same token to call a backend service.

server:
  name: user-data-passthrough-server
  securitySchemes:
    - id: clientUserBearer # Scheme for client's incoming Bearer token
      type: http
      scheme: bearer
    - id: backendServiceBearer # Scheme for backend API (also Bearer, but could be different)
      type: http
      scheme: bearer
      # No defaultCredential needed here if always relying on passthrough

tools:
  - name: get-user-profile
    description: "Gets user profile using the client's provided token."
    security: # Configuration for how the CLIENT authenticates to THIS MCP tool
      id: clientUserBearer   # MCP Server expects a Bearer token from the client
      passthrough: true     # Enable passthrough
    args: # ...
    requestTemplate:
      url: "https://api.user-profiles.com/me"
      method: GET
      security: # Configuration for how MCP Server authenticates to the BACKEND API
        id: backendServiceBearer # The passthrough token will be sent as a Bearer token
                                 # to the backend

Workflow:

1. The AI client calls the get-user-profile tool, providing an Authorization: Bearer <user_jwt_token> header.

2. The Higress MCP Server, based on tools[].security.id: clientUserBearer, extracts <user_jwt_token>. The original Authorization header from the client is removed.

3. Since passthrough: true is set, <user_jwt_token> is designated as the credential to use for the backend call.

4. The MCP Server then uses the scheme defined in requestTemplate.security.id: backendServiceBearer to format and send this <user_jwt_token> to the https://api.user-profiles.com/me endpoint (i.e., it sends Authorization: Bearer <user_jwt_token>).

Important Notes on Passthrough:

• When passthrough: true, any credential specified in requestTemplate.security.credential is ignored.

• The MCP Server intelligently extracts the core credential part (e.g., the token from “Bearer token”, the base64 part from “Basic base64value”) from the client request before passing it through.

Benefits

These new authentication features provide:

• Enhanced Security: Properly secure interactions with your backend services.

• Increased Flexibility: Support for various common authentication patterns.

• Simplified Integration: Easier integration with APIs that have diverse security requirements.

• Seamless User Context Propagation: Transparently use client-provided credentials for backend calls, enabling personalized API interactions.

We believe these enhancements will significantly improve the security posture and integration capabilities of your AI-powered applications built with Higress and MCP Server.

Streamlined Configuration with openapi-to-mcp

To further simplify the setup process, the latest version of our openapi-to-mcp tool (available on GitHub) now supports the automatic conversion of OpenAPI documents that include securitySchemes definitions directly into this MCP Server plugin configuration. If your OpenAPI specification already describes its security requirements, the tool can generate the corresponding server.securitySchemes and link them to the appropriate tools, significantly reducing manual configuration efforts.

Getting Started

Update your Higress MCP Server plugin and refer to the MCP Server README documentation for detailed configuration instructions and more examples.

We are committed to making Higress a powerful and developer-friendly AI-native API gateway, capable of interfacing with LLM APIs, MCP APIs, and Agent APIs. Stay tuned for more updates!