Description
To solve the Meta-Routing paradox for AllowPassThroughAuth (where an LLM client doesn't know what dynamic auth token to pre-fetch for an unknown backend), we need to implement an LLM-native Auth Challenge flow leveraging standard MCP 2026-07-28 features.
The router will dynamically rewrite tool descriptions to explicitly prompt the LLM for the required authentication, and gracefully challenge the LLM if it fails to provide it.
Detailed Requirements
1. Configurable Auth Prompts (UI / DB)
- Add a new database column / configuration field to the MCP Server entity:
DynamicAuthPrompt (string).
- Expose this field in the Web UI dashboard under the Server Management -> Security tab.
- This allows administrators to define the exact instructions the LLM needs to fetch the token.
- Example 1 (Azure OIDC): `"This tool requires an Azure AD JWT. Run 'az account get-access-token --resource api://finance' and provide the raw token."*
- Example 2 (API Key Shape): `"This tool requires a personal API key. Please ask the user to provide their GitHub PAT."*
- Example 3 (Custom Script): `"Run the local python script 'auth.py' to generate a short-lived HMAC token."*
2. Tool Description Rewriting (search_tools / tools/list)
- When the routing engine aggregates tools from backends configured with
AllowPassThroughAuth (or requiring user-provided secrets), it must automatically append the DynamicAuthPrompt to the end of the tool's description field.
- Why: The MCP spec natively exposes the
description field to the LLM. By injecting the auth instructions here, the LLM caller knows the exact auth shape and requirements before it attempts to call the tool.
3. Update Meta-Mode execute_tool Schema
- Update the
execute_tool input schema to include a new, optional string argument: target_auth_token.
- When provided, the router maps this value into the transport's internal
X-Target-Auth pipeline, which then applies the backend's configured AuthShape (e.g., prepending Bearer or Basic ) before sending it downstream.
4. Graceful Auth Challenge & Retry Flow (Error Handling)
- If an agent calls
execute_tool for a protected backend without providing the required target_auth_token, or if the downstream backend returns a 401 Unauthorized, the Router MUST NOT crash the connection or drop the SSE stream.
- Instead, the router must catch the error and return an MCP
ToolResult with isError: true.
- The error text must restate the
DynamicAuthPrompt to the LLM.
- Result: Autonomous agents (like Claude Desktop or Cursor) will natively read the error, execute the instructions to fetch the token, and automatically retry the
execute_tool call with the valid token.
Description
To solve the Meta-Routing paradox for
AllowPassThroughAuth(where an LLM client doesn't know what dynamic auth token to pre-fetch for an unknown backend), we need to implement an LLM-native Auth Challenge flow leveraging standard MCP 2026-07-28 features.The router will dynamically rewrite tool descriptions to explicitly prompt the LLM for the required authentication, and gracefully challenge the LLM if it fails to provide it.
Detailed Requirements
1. Configurable Auth Prompts (UI / DB)
DynamicAuthPrompt(string).2. Tool Description Rewriting (
search_tools/tools/list)AllowPassThroughAuth(or requiring user-provided secrets), it must automatically append theDynamicAuthPromptto the end of the tool'sdescriptionfield.descriptionfield to the LLM. By injecting the auth instructions here, the LLM caller knows the exact auth shape and requirements before it attempts to call the tool.3. Update Meta-Mode
execute_toolSchemaexecute_toolinput schema to include a new, optional string argument:target_auth_token.X-Target-Authpipeline, which then applies the backend's configuredAuthShape(e.g., prependingBearerorBasic) before sending it downstream.4. Graceful Auth Challenge & Retry Flow (Error Handling)
execute_toolfor a protected backend without providing the requiredtarget_auth_token, or if the downstream backend returns a401 Unauthorized, the Router MUST NOT crash the connection or drop the SSE stream.ToolResultwithisError: true.DynamicAuthPromptto the LLM.execute_toolcall with the valid token.