mcp server support API auth through OAS3 security schemes || mcp server support API auth through OAS3 security schemes

[johnlanni]

Ⅰ. Describe what this PR did

This PR introduces comprehensive API authentication capabilities to the Higress MCP Server plugin. These enhancements allow for secure and flexible integration with backend REST APIs that employ various authentication strategies, including HTTP Basic, HTTP Bearer, and API Key authentication. A key feature is the introduction of transparent credential passthrough.

Motivation/Background

As AI agents and MCP-enabled tools interact with an increasingly diverse set of external APIs, robust and flexible authentication mechanisms are crucial. This PR addresses the need to:

• Securely manage credentials for backend API calls.
• Support common API authentication patterns in line with industry standards like OpenAPI Specification (OAS3).
• Enable scenarios where client-provided credentials need to be passed through to backend services.
• Simplify the configuration of secure API integrations within the MCP Server.

Key Changes

• Reusable Security Schemes (server.securitySchemes):
  • Implemented a new server-level configuration securitySchemes allowing users to define reusable authentication methods.
  • This design aligns with the OpenAPI Specification (OAS3) for defining security schemes.
  • Currently supports:
    • http (with scheme: basic or scheme: bearer)
    • apiKey (with in: header or in: query)
  • Future support for oauth2 and openIdConnect (OIDC) is planned.
• Backend API Authentication (requestTemplate.security):
  • Tools can now specify a security block within their requestTemplate to apply a defined securityScheme when the MCP Server calls the backend REST API.
  • Supports overriding the defaultCredential from the scheme for specific tools.
• Client-to-MCP Server Authentication & Credential Passthrough (tools[].security):
  • Introduced a tool-level security configuration block (tools[].security).
  • tools[].security.id: Specifies the scheme the MCP client is expected to use. The MCP Server uses this to extract the client's credential.
  • tools[].security.passthrough: true: Enables transparent credential passthrough. If true, the credential extracted from the client request is used for the backend API call, applied according to the scheme defined in requestTemplate.security.
  • The original client credential header is removed from the request before it's processed further or passed to the backend (unless passthrough is used for that specific credential).

Associated SDK changes:
017f47f
c8f491d

Ⅱ. Does this pull request fix one issue?

Ⅲ. Why don't you add test cases (unit test/integration test)?

Ⅳ. Describe how to verify it

Ⅴ. Special notes for reviews

---

Ⅰ. Describe what this PR did

This PR introduces comprehensive API authentication capabilities to the Higress MCP Server plugin. These enhancements allow for secure and flexible integration with backend REST APIs that employ various authentication strategies, including HTTP Basic, HTTP Bearer, and API Key authentication. A key feature is the introduction of transparent credential passthrough.

Motivation/Background

As AI agents and MCP-enabled tools interact with an increasingly diverse set of external APIs, robust and flexible authentication mechanisms are crucial. This PR addresses the need to:

• Securely manage credentials for backend API calls.
• Support common API authentication patterns in line with industry standards like OpenAPI Specification (OAS3).
• Enable scenarios where client-provided credentials need to be passed through to backend services.
• Simplify the configuration of secure API integrations within the MCP Server.

Key Changes

• Reusable Security Schemes (server.securitySchemes):
  • Implemented a new server-level configuration securitySchemes allowing users to define reusable authentication methods.
  • This design aligns with the OpenAPI Specification (OAS3) for defining security schemes.
  • Currently supports:
    • http (with scheme: basic or scheme: bearer)
    • apiKey (with in: header or in: query)
  • Future support for oauth2 and openIdConnect (OIDC) is planned.
• Backend API Authentication (requestTemplate.security):
  • Tools can now specify a security block within their requestTemplate to apply a defined securityScheme when the MCP Server calls the backend REST API.
  • Supports overriding the defaultCredential from the scheme for specific tools.
• Client-to-MCP Server Authentication & Credential Passthrough (tools[].security):
  • Introduced a tool-level security configuration block (tools[].security).
  • tools[].security.id: Specifies the scheme the MCP client is expected to use. The MCP Server uses this to extract the client's credential.
  • tools[].security.passthrough: true: Enables transparent credential passthrough. If true, the credential extracted from the client request is used for the backend API call, applied according to the scheme defined in requestTemplate.security.
  • The original client credential header is removed from the request before it's processed further or passed to the backend (unless passthrough is used for that specific credential).

Associated SDK changes:
017f47f
c8f491d

Ⅱ. Does this pull request fix one issue?

Ⅲ. Why don't you add test cases (unit test/integration test)?

Ⅳ. Describe how to verify it

Ⅴ. Special notes for reviews

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 45.81%. Comparing base (ef31e09) to head (6987b99).
Report is 508 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2241      +/-   ##
==========================================
+ Coverage   35.91%   45.81%   +9.89%     
==========================================
  Files          69       79      +10     
  Lines       11576    12912    +1336     
==========================================
+ Hits         4157     5915    +1758     
+ Misses       7104     6650     -454     
- Partials      315      347      +32     

see 77 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.