Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

📪 feat: Send Per-Request MCP Headers Without Hiding the Tool Catalog (#15988)

lia-by-librechat[bot]a26a6709ff30
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 681057eabb..3ab4225018 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -522,6 +522,11 @@ actions:
# # connection once after a 401/403. A rejected tools/call is never replayed automatically.
# # Enabled oauth or obo configuration takes precedence over this passthrough mode.
# Authorization: "Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}"
+# # Sent only during a chat turn, merged over `headers` (these win on a duplicate name).
+# # Tool discovery has no conversation to resolve them against, so it omits them entirely:
+# # a `{{LIBRECHAT_BODY_*}}` placeholder here no longer hides the server's tool list.
+# requestHeaders:
+# X-Conversation-Id: "{{LIBRECHAT_BODY_CONVERSATIONID}}"
# puppeteer:
# type: stdio
# command: npx
diff --git a/packages/api/src/mcp/MCPConnectionFactory.ts b/packages/api/src/mcp/MCPConnectionFactory.ts
index 68a02d004d..2ddf0ca81a 100644
--- a/packages/api/src/mcp/MCPConnectionFactory.ts
+++ b/packages/api/src/mcp/MCPConnectionFactory.ts
@@ -31,6 +31,14 @@ import {
ReauthenticationRequiredError,
resolveOboToken,
} from '~/mcp/oauth';
+import {
+ isOAuthServer,
+ waitUntilDeadline,
+ applyRequestHeaders,
+ isClientRejectionMessage,
+ createDeadlineAbortSignal,
+ toCatalogConnectionConfig,
+} from './utils';
import {
isDirectOpenIDBearerRecoveryEnabled,
resolveDirectOpenIDBearerConfig,
@@ -41,12 +49,6 @@ import {
isMCPTransportAuthenticationError,
MCPAuthenticationRejectedError,
} from './errors';
-import {
- isOAuthServer,
- waitUntilDeadline,
- isClientRejectionMessage,
- createDeadlineAbortSignal,
-} from './utils';
import { PENDING_STALE_MS, FlowStateNotFoundError, normalizeExpiresAt } from '~/flow/manager';
import { createLazyOboUpstreamTokenProvider, awaitOboOperation } from '~/mcp/oauth/obo';
import { preProcessGraphTokens } from '~/utils/graph';
@@ -153,11 +155,20 @@ export class MCPConnectionFactory {
basic: t.BasicConnectionOptions,
oauth?: t.OAuthConnectionOptions | t.UserConnectionContext,
): Promise<MCPConnection> {
- const directBearerRecoveryState = basic.directBearerRecoveryState ?? { attempted: false };
+ /** Chat-time entry point: the operator's `requestHeaders` join `headers`
+ * here, ahead of direct-bearer detection and Graph preprocessing, so an
+ * `Authorization` or `{{LIBRECHAT_GRAPH_*}}` template declared there gets
+ * exactly the handling it would get in `headers`. */
+ const runtime: t.BasicConnectionOptions = {
+ ...basic,
+ serverConfig: applyRequestHeaders(basic.serverConfig),
+ serverDefinition: basic.serverDefinition ?? basic.serverConfig,
+ };
+ const directBearerRecoveryState = runtime.directBearerRecoveryState ?? { attempted: false };
const directBearerSourceConfig =
- basic.directBearerSourceConfig ??
- (isDirectOpenIDBearerRecoveryEnabled(basic.serverConfig)
- ? (basic.serverConfig as t.ParsedServerConfig)
+ runtime.directBearerSourceConfig ??
+ (isDirectOpenIDBearerRecoveryEnabled(runtime.serverConfig)
+ ? (runtime.serverConfig as t.ParsedServerConfig)
: undefined);
const create = async (candidate: t.BasicConnectionOptions): Promise<MCPConnection> => {
const prepared = await this.prepareBasicConnectionOptions(
@@ -171,11 +182,11 @@ export class MCPConnectionFactory {
return factory.createConnection();
};
if (!directBearerSourceConfig) {
- return create(basic);
+ return create(runtime);
}
try {
- return await create(basic);
+ return await create(runtime);
} catch (error) {
if (!isMCPTransportAuthenticationError(error) || this.isRequestCancelled(oauth)) {
throw error;
@@ -192,7 +203,7 @@ export class MCPConnectionFactory {
});
directBearerRecoveryState.resolvedConfig = refreshedConfig;
try {
- return await create({ ...basic, serverConfig: refreshedConfig });
+ return await create({ ...runtime, serverConfig: refreshedConfig });
} catch (refreshedError) {
if (isMCPTransportAuthenticationError(refreshedError)) {
throw new MCPAuthenticationRejectedError(basic.serverName, false, refreshedError);
@@ -233,7 +244,15 @@ export class MCPConnectionFactory {
: undefined);
const discover = async (candidate: t.BasicConnectionOptions): Promise<ToolDiscoveryResult> => {
const prepared = await this.prepareBasicConnectionOptions(
- { ...candidate, directBearerSourceConfig },
+ {
+ ...candidate,
+ /** Applied to every discovery attempt, not just the first: a config
+ * refreshed for direct-bearer recovery comes from the untouched
+ * definition and would otherwise carry the chat-only map back in. */
+ serverConfig: toCatalogConnectionConfig(candidate.serverConfig),
+ serverDefinition: basic.serverDefinition ?? basic.serverConfig,
+ directBearerSourceConfig,
+ },
options,
);
if (options != null && 'useOAuth' in options) {
diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.ts
index bf5196c382..429df3af63 100644
--- a/packages/api/src/mcp/MCPManager.ts
+++ b/packages/api/src/mcp/MCPManager.ts
@@ -18,13 +18,14 @@ import type { RequestBody } from '~/types';
import type * as t from './types';
import {
getMissingRuntimeBodyPlaceholderFields,
+ toCatalogConnectionConfig,
+ applyRequestHeaders,
createDeadlineAbortSignal,
canUseAppConnection,
isOAuthServer,
isUserSourced,
requiresEphemeralUserConnection,
requiresOAuthMachinery,
- requiresUserScopedConnection,
resolveServerInstructions,
} from './utils';
import { getMCPAppToolsPublicationGeneration, getMCPToolsChangedGeneration } from './toolsChanged';
@@ -363,7 +364,7 @@ export class MCPManager extends UserConnectionManager {
? await MCPServersRegistry.getInstance().getServerConfig(args.serverName, userId)
: undefined);
- if (effectiveConfig && userId && requiresUserScopedConnection(effectiveConfig)) {
+ if (effectiveConfig && userId && !canUseAppConnection(effectiveConfig)) {
return this.getUserConnection({
...args,
serverConfig: effectiveConfig,
@@ -444,8 +445,12 @@ export class MCPManager extends UserConnectionManager {
return { tools: null, oauthRequired: false, oauthUrl: null };
}
+ /** Discovery sends no `requestHeaders`, so only the body values the catalog
+ * connection itself needs can block it. A server whose body placeholders
+ * live solely in `requestHeaders` still lists its tools. */
+ const catalogConfig = toCatalogConnectionConfig(serverConfig);
const missingBodyFields = getMissingRuntimeBodyPlaceholderFields(
- serverConfig,
+ catalogConfig,
args.requestBody,
);
if (missingBodyFields.length > 0) {
@@ -458,7 +463,7 @@ export class MCPManager extends UserConnectionManager {
const { allowedDomains, allowedAddresses, useSSRFProtection } =
await registry.resolveAllowlists({ userId: user?.id, role: user?.role });
await this.assertResolvedRuntimeConfigAllowed({
- config: serverConfig,
+ config: catalogConfig,
user,
customUserVars: args.customUserVars,
requestBody: args.requestBody,
@@ -473,7 +478,8 @@ export class MCPManager extends UserConnectionManager {
const basic: t.BasicConnectionOptions = {
dbSourced,
serverName,
- serverConfig,
+ serverConfig: catalogConfig,
+ serverDefinition: serverConfig,
useSSRFProtection,
allowedDomains,
allowedAddresses,
@@ -893,7 +899,7 @@ Please follow these instructions when using tools from the respective MCP server
try {
recoverySignal.throwIfAborted();
const refreshedConfig = await resolveDirectOpenIDBearerConfig({
- config: serverConfig,
+ config: applyRequestHeaders(serverConfig),
upstreamTokenProvider,
forceRefresh: true,
signal: recoverySignal,
@@ -1246,8 +1252,13 @@ Please follow these instructions when using tools from the respective MCP server
}
const registry = MCPServersRegistry.getInstance();
- const rawConfig = providedConfig ?? (await registry.getServerConfig(serverName, userId));
- if (!rawConfig) {
+ const declaredConfig =
+ providedConfig ?? (await registry.getServerConfig(serverName, userId));
+ /** Folded in before scope detection, Graph preprocessing and
+ * direct-bearer resolution, so this pipeline sees the same single
+ * header map the factory does. */
+ const rawConfig = declaredConfig && applyRequestHeaders(declaredConfig);
+ if (!rawConfig || !declaredConfig) {
throw new McpError(
ErrorCode.InvalidRequest,
`${logPrefix} Configuration for server "${serverName}" not found.`,
@@ -1385,6 +1396,7 @@ Please follow these instructions when using tools from the respective MCP server
{
serverName,
serverConfig: currentOptions,
+ serverDefinition: declaredConfig,
dbSourced: isDbSourced,
skipEnvProcessing: true,
useSSRFProtection,
@@ -1439,7 +1451,7 @@ Please follow these instructions when using tools from the respective MCP server
const recovery = this.recoverDirectOpenIDBearerConnection({
connection,
serverName,
- serverConfig: rawConfig,
+ serverConfig: declaredConfig,
user,
flowManager,
tokenMethods,
@@ -1530,7 +1542,7 @@ Please follow these instructions when using tools from the respective MCP server
const recovery = this.recoverDirectOpenIDBearerConnection({
connection,
serverName,
- serverConfig: rawConfig,
+ serverConfig: declaredConfig,
user,
flowManager,
tokenMethods,
diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.ts
index d264f039ca..8ee4c63d56 100644
--- a/packages/api/src/mcp/UserConnectionManager.ts
+++ b/packages/api/src/mcp/UserConnectionManager.ts
@@ -2,6 +2,8 @@ import { logger } from '@librechat/data-schemas';
import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
import type * as t from './types';
import {
+ applyRequestHeaders,
+ canUseAppConnection,
canBackfillSharedServerInstructions,
getMissingRuntimeBodyPlaceholderFields,
hasRuntimeUrlPlaceholders,
@@ -602,16 +604,21 @@ export abstract class UserConnectionManager {
): Promise<MCPConnection> {
signal?.throwIfAborted();
this.assertCreationNotCancelled(creationGuard, userId, serverName);
- if (await this.appConnections!.has(serverName)) {
+ const declaredConfig =
+ providedConfig ??
+ (await MCPServersRegistry.getInstance().getServerConfig(serverName, userId));
+ if (
+ (!declaredConfig || canUseAppConnection(declaredConfig)) &&
+ (await this.appConnections!.has(serverName))
+ ) {
throw new McpError(
ErrorCode.InvalidRequest,
`[MCP][User: ${userId}] Trying to create user-specific connection for app-level server "${serverName}"`,
);
}
- const config =
- providedConfig ??
- (await MCPServersRegistry.getInstance().getServerConfig(serverName, userId));
+ /** Resolution uses effective headers; identity and persistence keep the declaration. */
+ const config = declaredConfig && applyRequestHeaders(declaredConfig);
/** Capture before resolving credentials/creating the connection. If another replica rotates
* the generation while creation is in flight, this connection's publications are fenced. */
@@ -641,7 +648,9 @@ export abstract class UserConnectionManager {
const existingPublicationGeneration = connection
? this.toolPublicationGenerations.get(connection)
: undefined;
- const configGeneration = config ? getMCPAppToolsPublicationGeneration(config) : undefined;
+ const configGeneration = declaredConfig
+ ? getMCPAppToolsPublicationGeneration(declaredConfig)
+ : undefined;
const existingConfigGeneration = connection
? this.toolConfigGenerations.get(connection)
: undefined;
@@ -739,7 +748,7 @@ export abstract class UserConnectionManager {
}
// Now check if config exists for new connection creation
- if (!config) {
+ if (!config || !declaredConfig) {
throw new McpError(
ErrorCode.InvalidRequest,
`[MCP][User: ${userId}] Configuration for server "${serverName}" not found.`,
@@ -786,7 +795,7 @@ export abstract class UserConnectionManager {
serverConfig: runtimeConfig,
/** Runtime OAuth detection enriches the connection config. Keep the durable definition
* separate so callback liveness compares against the config that actually owns it. */
- serverDefinition: config,
+ serverDefinition: declaredConfig,
...(usesDirectOpenIDBearerRecovery(config) && { directBearerSourceConfig: config }),
directBearerRecoveryState,
serverName: serverName,
@@ -903,7 +912,7 @@ export abstract class UserConnectionManager {
tools,
userId,
serverName,
- serverConfig: config,
+ serverConfig: declaredConfig,
...(effectiveGeneration && { publicationGeneration: effectiveGeneration }),
...(publicationRevision && { publicationRevision }),
});
@@ -958,7 +967,7 @@ export abstract class UserConnectionManager {
connectionTimeout,
graphTokenResolver,
ephemeralConnection,
- serverConfig: config,
+ serverConfig: declaredConfig,
directBearerRecoveryState,
directBearerResolvedConfig: refreshedConfig,
},
@@ -978,7 +987,7 @@ export abstract class UserConnectionManager {
}
logger.info(`[MCP][User: ${userId}][${serverName}] Connection successfully established`);
- await this.backfillResolvedInstructions(serverName, config, connection, userId);
+ await this.backfillResolvedInstructions(serverName, declaredConfig, connection, userId);
signal?.throwIfAborted();
if (!ephemeralConnection) {
await this.updateUserLastActivity(userId);
@@ -1079,12 +1088,16 @@ export abstract class UserConnectionManager {
requestBody?: t.UserMCPConnectionOptions['requestBody'];
graphTokenResolver?: t.UserMCPConnectionOptions['graphTokenResolver'];
}): Promise<t.ParsedServerConfig> {
- const dbSourced = isUserSourced(config);
+ /** Mirrors the factory's entry-point normalization; without it this
+ * validation pass would inspect a different header map than the one the
+ * connection ends up sending. */
+ const runtimeConfig = applyRequestHeaders(config);
+ const dbSourced = isUserSourced(runtimeConfig);
/** Plugin-authored placeholders must never resolve against the user's Graph token. */
const graphProcessedConfig =
- dbSourced || isPluginSourced(config)
- ? config
- : await preProcessGraphTokens(config, {
+ dbSourced || isPluginSourced(runtimeConfig)
+ ? runtimeConfig
+ : await preProcessGraphTokens(runtimeConfig, {
user,
graphTokenResolver,
scopes: process.env.GRAPH_API_SCOPES,
diff --git a/packages/api/src/mcp/__tests__/ConnectionsRepository.test.ts b/packages/api/src/mcp/__tests__/ConnectionsRepository.test.ts
index b8e4f57408..a4dbb5d158 100644
--- a/packages/api/src/mcp/__tests__/ConnectionsRepository.test.ts
+++ b/packages/api/src/mcp/__tests__/ConnectionsRepository.test.ts
@@ -151,6 +151,33 @@ describe('ConnectionsRepository', () => {
expect(mockConnection.refreshToolList).not.toHaveBeenCalled();
});
+ it('refuses an app connection for a server declaring chat-only headers', async () => {
+ mockServerConfigs.server1 = {
+ ...mockServerConfigs.server1,
+ requestHeaders: { 'X-Workspace': 'workspace-1' },
+ } as t.ParsedServerConfig;
+
+ const result = await repository.get('server1');
+
+ /** A shared session would carry these into its own `initialize` and
+ * `tools/list`, which every later catalog read reuses. */
+ expect(result).toBeNull();
+ expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
+ });
+
+ it('still creates a user-owned connection for a server declaring chat-only headers', async () => {
+ mockServerConfigs.server1 = {
+ ...mockServerConfigs.server1,
+ requestHeaders: { 'X-Workspace': 'workspace-1' },
+ } as t.ParsedServerConfig;
+ const userRepository = new ConnectionsRepository('user-1');
+
+ const result = await userRepository.get('server1');
+
+ expect(result).toBe(mockConnection);
+ expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
+ });
+
it('serializes concurrent creation so only one connection is retained', async () => {
const [first, second] = await Promise.all([
repository.get('server1'),
diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts
index b00df44d9d..5e505685fe 100644
--- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts
+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts
@@ -12,6 +12,7 @@ import {
import { PENDING_STALE_MS, FlowStateNotFoundError } from '~/flow/manager';
import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';
import { MCPAuthenticationRejectedError } from '~/mcp/errors';
+import { getMCPServerGeneration } from '~/mcp/oauth/cleanup';
import { preProcessGraphTokens } from '~/utils/graph';
import { MCPConnection } from '~/mcp/connection';
import { processMCPEnv } from '~/utils';
@@ -396,6 +397,42 @@ describe('MCPConnectionFactory', () => {
expect(mockConnectionInstance.connect).toHaveBeenCalled();
});
+ it('should merge requestHeaders before Graph pre-processing, overriding by case', async () => {
+ const graphTokenResolver = jest.fn();
+ const serverConfig = {
+ type: 'streamable-http',
+ url: 'https://api.example.com/mcp',
+ source: 'yaml',
+ apiKey: { source: 'admin', authorization_type: 'bearer', key: 'catalog-key' },
+ headers: { 'X-Workspace': 'workspace-1', Authorization: 'Bearer stale' },
+ requestHeaders: { authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}' },
+ } as t.MCPOptions;
+
+ mockPreProcessGraphTokens.mockImplementation(async (config) => config as t.MCPOptions);
+ mockProcessMCPEnv.mockImplementation(
+ ({ options }: { options: t.MCPOptions }) => options as t.MCPOptions,
+ );
+ mockConnectionInstance.isConnected.mockResolvedValue(true);
+
+ await MCPConnectionFactory.create(
+ { serverName: 'test-server', serverConfig },
+ { user: mockUser, graphTokenResolver },
+ );
+
+ /** The preprocessor only inspects `headers`, so the chat-only map has to be
+ * folded in before it runs — and the base `Authorization` must be gone,
+ * since keeping both spellings would let Undici join the two values. */
+ const preprocessed = mockPreProcessGraphTokens.mock.calls[0][0] as {
+ headers?: Record<string, string>;
+ requestHeaders?: Record<string, string>;
+ };
+ expect(preprocessed.headers).toEqual({
+ 'X-Workspace': 'workspace-1',
+ authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
+ });
+ expect(preprocessed).not.toHaveProperty('requestHeaders');
+ });
+
it('should pre-process Graph placeholders before connection config resolution', async () => {
const graphTokenResolver = jest.fn();
const serverConfig: t.MCPOptions = {
@@ -4288,6 +4325,43 @@ describe('MCPConnectionFactory', () => {
});
});
+ describe('declared identity across connection transformations', () => {
+ it.each(['create', 'discoverTools'] as const)(
+ '%s retains the callback identity while transforming only wire headers',
+ async (entry) => {
+ const declared: t.ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ headers: { 'X-Workspace': 'catalog' },
+ requestHeaders: { 'X-Workspace': 'chat' },
+ };
+ let definition: t.MCPOptions | undefined;
+ let wireConfig: t.MCPOptions | undefined;
+ class IdentityFactory extends MCPConnectionFactory {
+ protected async createConnection(): Promise<MCPConnection> {
+ definition = this.serverDefinition;
+ wireConfig = this.serverConfig;
+ return mockConnectionInstance;
+ }
+
+ protected async discoverToolsInternal() {
+ await this.createConnection();
+ return { tools: [], connection: null, oauthRequired: false, oauthUrl: null };
+ }
+ }
+ mockProcessMCPEnv.mockImplementation(({ options }) => options);
+ await IdentityFactory[entry]({ serverName: 'identity', serverConfig: declared });
+ expect(definition).toBe(declared);
+ expect(getMCPServerGeneration(definition!)).toBe(getMCPServerGeneration(declared));
+ expect(wireConfig).not.toHaveProperty('requestHeaders');
+ expect(wireConfig).toMatchObject({
+ headers: { 'X-Workspace': entry === 'create' ? 'chat' : 'catalog' },
+ });
+ },
+ );
+ });
+
describe('discoverTools static method', () => {
const mockTools = [
{ name: 'tool1', description: 'First tool', inputSchema: { type: 'object' } },
diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.ts
index 32b75090e3..976e22fbe4 100644
--- a/packages/api/src/mcp/__tests__/MCPManager.test.ts
+++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts
@@ -2343,6 +2343,61 @@ describe('MCPManager', () => {
);
});
+ it('detects direct-bearer mode when the Authorization template lives in requestHeaders', async () => {
+ mockAppConnections({
+ has: jest.fn().mockResolvedValue(false),
+ });
+ const connection = {
+ isConnected: jest.fn().mockResolvedValue(true),
+ refreshToolList: jest.fn().mockResolvedValue({ tools: [] }),
+ on: jest.fn(),
+ } as unknown as MCPConnection;
+ (MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
+ (graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
+ const manager = await MCPManager.createInstance(newMCPServersConfig());
+ const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'live-token' });
+
+ await manager.getUserConnection({
+ serverName,
+ user: { id: 'direct-user', provider: 'openid', openidId: 'direct-subject' } as IUser,
+ serverConfig: {
+ ...serverConfig,
+ source: 'yaml',
+ requestHeaders: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
+ } as t.ParsedServerConfig,
+ flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
+ upstreamTokenProvider,
+ });
+
+ /** The manager's own bearer decisions read the config directly, so the map
+ * has to be folded in before them or a 401 never reaches recovery. */
+ expect(upstreamTokenProvider).toHaveBeenCalled();
+ const createCalls = (MCPConnectionFactory.create as jest.Mock).mock.calls;
+ const [basic] = createCalls[createCalls.length - 1];
+ expect(basic.directBearerSourceConfig).toBeDefined();
+ expect(basic.serverConfig.headers).toEqual({ Authorization: 'Bearer live-token' });
+ expect(basic.serverConfig).not.toHaveProperty('requestHeaders');
+ expect(basic.serverDefinition.requestHeaders).toEqual({
+ Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
+ });
+ const published = jest.fn();
+ toolsChanged.setMCPToolsChangedHandler(published);
+ try {
+ const listener = (connection.on as jest.Mock).mock.calls.find(
+ ([event]) => event === 'toolsChanged',
+ )?.[1];
+ listener([]);
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(published).toHaveBeenCalledWith(
+ expect.objectContaining({
+ serverConfig: basic.serverDefinition,
+ }),
+ );
+ } finally {
+ toolsChanged.setMCPToolsChangedHandler(null);
+ }
+ });
+
it('waits for an active recovery before reusing a cached connection', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
@@ -3253,63 +3308,80 @@ describe('MCPManager', () => {
openidId: 'direct-subject',
} as IUser;
- it('refreshes and replaces the connection without replaying a rejected tool call', async () => {
- const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
- const connection = {
- isConnected: jest.fn().mockResolvedValue(true),
- setRequestHeaders: jest.fn(),
- stopReconnecting: jest.fn(),
- isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
- timeout: 30000,
- client: { request: jest.fn().mockRejectedValue(rejection) },
- } as unknown as MCPConnection;
- const replacement = {
- isConnected: jest.fn().mockResolvedValue(true),
- } as unknown as MCPConnection;
- const upstreamTokenProvider = jest
- .fn()
- .mockResolvedValueOnce({ access_token: 'current-token' })
- .mockResolvedValueOnce({ access_token: 'refreshed-token' });
-
- (graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
- (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
- const manager = await MCPManager.createInstance(newMCPServersConfig());
- const getUserConnection = jest
- .spyOn(manager, 'getUserConnection')
- .mockResolvedValueOnce(connection)
- .mockResolvedValueOnce(replacement);
+ it.each(['headers', 'requestHeaders'] as const)(
+ 'refreshes %s without replaying a rejected tool call or losing its declaration',
+ async (headerMap) => {
+ const declared: t.ParsedServerConfig = {
+ ...serverConfig,
+ headers: undefined,
+ [headerMap]: serverConfig.headers,
+ ...(headerMap === 'requestHeaders' && {
+ apiKey: {
+ source: 'admin' as const,
+ authorization_type: 'bearer' as const,
+ key: 'catalog-key',
+ },
+ }),
+ };
+ const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
+ const connection = {
+ isConnected: jest.fn().mockResolvedValue(true),
+ setRequestHeaders: jest.fn(),
+ stopReconnecting: jest.fn(),
+ isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
+ timeout: 30000,
+ client: { request: jest.fn().mockRejectedValue(rejection) },
+ } as unknown as MCPConnection;
+ const replacement = {
+ isConnected: jest.fn().mockResolvedValue(true),
+ } as unknown as MCPConnection;
+ const upstreamTokenProvider = jest
+ .fn()
+ .mockResolvedValueOnce({ access_token: 'current-token' })
+ .mockResolvedValueOnce({ access_token: 'refreshed-token' });
- await expect(
- manager.callTool({
- user,
- serverName,
- toolName: 'mutating_tool',
- provider: 'openai',
- flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
- upstreamTokenProvider,
- }),
- ).rejects.toMatchObject({
- code: 'MCP_AUTHENTICATION_REJECTED',
- connectionRefreshed: true,
- } satisfies Partial<MCPAuthenticationRejectedError>);
+ (graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
+ async (config) => config,
+ );
+ (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(declared);
+ const manager = await MCPManager.createInstance(newMCPServersConfig());
+ const getUserConnection = jest
+ .spyOn(manager, 'getUserConnection')
+ .mockResolvedValueOnce(connection)
+ .mockResolvedValueOnce(replacement);
- expect(connection.client.request).toHaveBeenCalledTimes(1);
- expect(upstreamTokenProvider).toHaveBeenNthCalledWith(2, {
- forceRefresh: true,
- signal: expect.any(AbortSignal),
- });
- expect(connection.stopReconnecting).toHaveBeenCalled();
- expect(getUserConnection).toHaveBeenLastCalledWith(
- expect.objectContaining({
- forceNew: true,
- serverConfig,
- directBearerRecoveryState: expect.objectContaining({ attempted: true }),
- directBearerResolvedConfig: expect.objectContaining({
- headers: { Authorization: 'Bearer refreshed-token' },
+ await expect(
+ manager.callTool({
+ user,
+ serverName,
+ toolName: 'mutating_tool',
+ provider: 'openai',
+ flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
+ upstreamTokenProvider,
}),
- }),
- );
- });
+ ).rejects.toMatchObject({
+ code: 'MCP_AUTHENTICATION_REJECTED',
+ connectionRefreshed: true,
+ } satisfies Partial<MCPAuthenticationRejectedError>);
+
+ expect(connection.client.request).toHaveBeenCalledTimes(1);
+ expect(upstreamTokenProvider).toHaveBeenNthCalledWith(2, {
+ forceRefresh: true,
+ signal: expect.any(AbortSignal),
+ });
+ expect(connection.stopReconnecting).toHaveBeenCalled();
+ expect(getUserConnection).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ forceNew: true,
+ serverConfig: declared,
+ directBearerRecoveryState: expect.objectContaining({ attempted: true }),
+ directBearerResolvedConfig: expect.objectContaining({
+ headers: { Authorization: 'Bearer refreshed-token' },
+ }),
+ }),
+ );
+ },
+ );
it('preserves a JSON-RPC tool failure that mentions downstream authentication', async () => {
const toolError = new McpError(ErrorCode.InternalError, 'downstream HTTP 401 invalid_token');
@@ -3988,6 +4060,43 @@ describe('MCPManager', () => {
expect(getUserConnectionSpy).not.toHaveBeenCalled();
});
+ it('keeps a static request-header overlay off its same-named shared app connection', async () => {
+ const appConnections = {
+ get: jest.fn(),
+ has: jest.fn().mockResolvedValue(true),
+ };
+ mockAppConnections(appConnections);
+ const candidate = {
+ isConnected: jest.fn().mockResolvedValue(true),
+ refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),
+ on: jest.fn(),
+ } as unknown as MCPConnection;
+ (MCPConnectionFactory.create as jest.Mock).mockResolvedValue(candidate);
+ const declared: t.ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://api.example.com/mcp',
+ source: 'yaml',
+ requestHeaders: { 'X-Workspace': 'chat-only' },
+ };
+ const manager = await MCPManager.createInstance(newMCPServersConfig());
+ await expect(
+ manager.getConnection({
+ serverName,
+ user: mockUser as IUser,
+ serverConfig: declared,
+ }),
+ ).resolves.toBe(candidate);
+ expect(appConnections.get).not.toHaveBeenCalled();
+ expect(appConnections.has).not.toHaveBeenCalled();
+ expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ serverDefinition: declared,
+ serverConfig: expect.objectContaining({ headers: { 'X-Workspace': 'chat-only' } }),
+ }),
+ expect.any(Object),
+ );
+ });
+
it('should use user-scoped connections for trusted runtime context placeholders', async () => {
const appConnection = {
isConnected: jest.fn().mockResolvedValue(true),
@@ -4051,6 +4160,32 @@ describe('MCPManager', () => {
(MCPConnectionFactory.discoverTools as jest.Mock) = jest.fn();
});
+ it('keeps the declared OAuth identity while stripping discovery headers', async () => {
+ const declared: t.ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ requiresOAuth: true,
+ requestHeaders: { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ };
+ mockRegistryInstance.getServerConfig.mockResolvedValue(declared);
+ (MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
+ tools: mockTools,
+ connection: null,
+ oauthRequired: false,
+ oauthUrl: null,
+ });
+ const manager = await MCPManager.createInstance(newMCPServersConfig());
+ await manager.discoverServerTools({
+ serverName,
+ user: { id: 'oauth-user' } as IUser,
+ flowManager: {} as Parameters<typeof manager.discoverServerTools>[0]['flowManager'],
+ });
+ const [basic] = (MCPConnectionFactory.discoverTools as jest.Mock).mock.calls[0];
+ expect(basic.serverDefinition).toBe(declared);
+ expect(basic.serverConfig).not.toHaveProperty('requestHeaders');
+ });
+
it('should return tools from existing app connection when available', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
@@ -4625,77 +4760,92 @@ describe('MCPManager', () => {
expect(mockConnection.refreshToolList).toHaveBeenCalledTimes(1);
});
- it('recovers an ephemeral initial tools/list rejection once and fences the replacement', async () => {
- const authenticationError = Object.assign(new Error('unauthorized'), { status: 401 });
- const rejectedConnection = newUserConnection();
- const replacementConnection = newUserConnection();
- (rejectedConnection.refreshToolList as jest.Mock).mockResolvedValue({
- tools: [],
- complete: false,
- authenticationError,
- });
- (replacementConnection.refreshToolList as jest.Mock).mockResolvedValue({
- tools: [],
- complete: false,
- authenticationError,
- });
- const directBearerConfig: t.ParsedServerConfig = {
- type: 'streamable-http',
- url: 'https://mcp.example.com/mcp',
- source: 'yaml',
- headers: {
- Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
- 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
- },
- };
- const upstreamTokenProvider = jest
- .fn()
- .mockResolvedValueOnce({ access_token: 'stale-token' })
- .mockResolvedValueOnce({ access_token: 'fresh-token' })
- .mockResolvedValueOnce({ access_token: 'fresh-token' });
- mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
- (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directBearerConfig);
- (MCPConnectionFactory.create as jest.Mock)
- .mockResolvedValueOnce(rejectedConnection)
- .mockResolvedValueOnce(replacementConnection);
-
- const manager = await MCPManager.createInstance(newMCPServersConfig());
- await expect(
- manager.getUserConnection({
- serverName,
- user: mockUser,
- requestBody: { conversationId: 'conversation-1' },
- upstreamTokenProvider,
- }),
- ).rejects.toMatchObject({
- code: 'MCP_AUTHENTICATION_REJECTED',
- connectionRefreshed: false,
- } satisfies Partial<MCPAuthenticationRejectedError>);
+ it.each(['headers', 'requestHeaders'] as const)(
+ 'recovers an initial tools/list rejection with %s and preserves the replacement identity',
+ async (headerMap) => {
+ const authenticationError = Object.assign(new Error('unauthorized'), { status: 401 });
+ const rejectedConnection = newUserConnection();
+ const replacementConnection = newUserConnection();
+ (rejectedConnection.refreshToolList as jest.Mock).mockResolvedValue({
+ tools: [],
+ complete: false,
+ authenticationError,
+ });
+ (replacementConnection.refreshToolList as jest.Mock).mockResolvedValue({
+ tools: [],
+ complete: false,
+ authenticationError,
+ });
+ const directBearerConfig: t.ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ source: 'yaml',
+ ...(headerMap === 'requestHeaders' && {
+ apiKey: {
+ source: 'admin' as const,
+ authorization_type: 'bearer' as const,
+ key: 'catalog-key',
+ },
+ }),
+ [headerMap]: {
+ Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
+ 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ },
+ };
+ const upstreamTokenProvider = jest
+ .fn()
+ .mockResolvedValueOnce({ access_token: 'stale-token' })
+ .mockResolvedValueOnce({ access_token: 'fresh-token' })
+ .mockResolvedValueOnce({ access_token: 'fresh-token' });
+ mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
+ (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directBearerConfig);
+ (MCPConnectionFactory.create as jest.Mock)
+ .mockResolvedValueOnce(rejectedConnection)
+ .mockResolvedValueOnce(replacementConnection);
- expect(rejectedConnection.dispose).toHaveBeenCalledTimes(1);
- expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
- expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
- expect.objectContaining({
- ephemeralConnection: true,
- directBearerRecoveryState: expect.objectContaining({ attempted: true }),
- }),
- expect.any(Object),
- );
- expect(upstreamTokenProvider.mock.calls).toEqual([
- [{ forceRefresh: false }],
- [{ forceRefresh: true }],
- ]);
- expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
- expect.objectContaining({
- serverDefinition: directBearerConfig,
- directBearerSourceConfig: directBearerConfig,
- serverConfig: expect.objectContaining({
- headers: expect.objectContaining({ Authorization: 'Bearer fresh-token' }),
+ const manager = await MCPManager.createInstance(newMCPServersConfig());
+ await expect(
+ manager.getUserConnection({
+ serverName,
+ user: mockUser,
+ requestBody: { conversationId: 'conversation-1' },
+ upstreamTokenProvider,
}),
- }),
- expect.any(Object),
- );
- });
+ ).rejects.toMatchObject({
+ code: 'MCP_AUTHENTICATION_REJECTED',
+ connectionRefreshed: false,
+ } satisfies Partial<MCPAuthenticationRejectedError>);
+
+ expect(rejectedConnection.dispose).toHaveBeenCalledTimes(1);
+ expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
+ expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ ephemeralConnection: true,
+ directBearerRecoveryState: expect.objectContaining({ attempted: true }),
+ }),
+ expect.any(Object),
+ );
+ expect(upstreamTokenProvider.mock.calls).toEqual([
+ [{ forceRefresh: false }],
+ [{ forceRefresh: true }],
+ ]);
+ expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ serverDefinition: directBearerConfig,
+ directBearerSourceConfig: expect.objectContaining({
+ headers: {
+ Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
+ 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ },
+ }),
+ serverConfig: expect.objectContaining({
+ headers: expect.objectContaining({ Authorization: 'Bearer fresh-token' }),
+ }),
+ }),
+ expect.any(Object),
+ );
+ },
+ );
it.each([false, true])(
'does not publish a cancelled initial catalog (request-scoped=%s)',
diff --git a/packages/api/src/mcp/__tests__/scope.integration.test.ts b/packages/api/src/mcp/__tests__/scope.integration.test.ts
index 59fe600f6f..84a5f2d1fd 100644
--- a/packages/api/src/mcp/__tests__/scope.integration.test.ts
+++ b/packages/api/src/mcp/__tests__/scope.integration.test.ts
@@ -52,6 +52,7 @@ interface RequestScopedTestServer {
toolCallCount: () => number;
observedRunIds: () => string[];
observedParentMessageIds: () => string[];
+ observedHeaders: () => Record<string, string>[];
}
function trackSockets(httpServer: http.Server): () => Promise<void> {
@@ -74,6 +75,7 @@ async function createRequestScopedTestServer(): Promise<RequestScopedTestServer>
const sessions = new Map<string, StreamableHTTPServerTransport>();
const runIds: string[] = [];
const parentMessageIds: string[] = [];
+ const postHeaders: Record<string, string>[] = [];
let created = 0;
let deletes = 0;
let toolCalls = 0;
@@ -85,6 +87,14 @@ async function createRequestScopedTestServer(): Promise<RequestScopedTestServer>
}
if (req.method === 'POST') {
+ postHeaders.push(
+ Object.fromEntries(
+ Object.entries(req.headers).map(([key, value]) => [
+ key,
+ Array.isArray(value) ? value.join(',') : (value ?? ''),
+ ]),
+ ),
+ );
const runId = req.headers['x-run-id'];
if (typeof runId === 'string') {
runIds.push(runId);
@@ -134,6 +144,7 @@ async function createRequestScopedTestServer(): Promise<RequestScopedTestServer>
toolCallCount: () => toolCalls,
observedRunIds: () => [...runIds],
observedParentMessageIds: () => [...parentMessageIds],
+ observedHeaders: () => postHeaders.map((headers) => ({ ...headers })),
close: async () => {
const closing = [...sessions.values()].map((transport) =>
transport.close().catch(() => undefined),
@@ -317,3 +328,259 @@ describe('request-scoped MCP lifecycle integration', () => {
expect(new Set(server.observedRunIds())).toEqual(new Set(['recovery-run']));
});
});
+
+describe('operator requestHeaders integration', () => {
+ const serverName = 'request-headers';
+ let server: RequestScopedTestServer;
+ let manager: MCPManager;
+ const contexts = new Set<MCPRequestContext>();
+
+ /**
+ * `X-Conversation-Id` is declared in BOTH maps so precedence is observable,
+ * and `X-Trace-Id` only in the chat-only map so its absence proves discovery
+ * never sent it.
+ */
+ function createRequestHeadersConfig(url: string): ParsedServerConfig {
+ return {
+ type: 'streamable-http',
+ url,
+ source: 'yaml',
+ requiresOAuth: false,
+ initTimeout: 500,
+ headers: {
+ 'X-Workspace': 'workspace-1',
+ 'X-Conversation-Id': 'from-headers',
+ },
+ requestHeaders: {
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ 'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}',
+ },
+ } as ParsedServerConfig;
+ }
+
+ beforeEach(async () => {
+ server = await createRequestScopedTestServer();
+ manager = createManager();
+ jest.spyOn(MCPServersRegistry, 'getInstance').mockReturnValue({
+ resolveAllowlists: jest.fn(async () => ({
+ allowedDomains: null,
+ allowedAddresses: null,
+ useSSRFProtection: false,
+ })),
+ getServerConfig: jest.fn(async () => createRequestHeadersConfig(server.url)),
+ isAppServerConfig: jest.fn(async () => false),
+ } as unknown as MCPServersRegistry);
+ });
+
+ afterEach(async () => {
+ await Promise.all([...contexts].map((context) => cleanupMCPRequestContext(context)));
+ contexts.clear();
+ MCPConnection.clearCooldown(serverName);
+ jest.restoreAllMocks();
+ await server.close();
+ });
+
+ function createContext(): MCPRequestContext {
+ const context = createMCPRequestContext();
+ contexts.add(context);
+ return context;
+ }
+
+ function callEchoWithBody({
+ requestScopedConnections,
+ requestBody,
+ value,
+ }: {
+ requestScopedConnections: RequestScopedMCPConnectionStore;
+ requestBody: Record<string, string>;
+ value: string;
+ }) {
+ return manager.callTool({
+ user,
+ serverName,
+ serverConfig: createRequestHeadersConfig(server.url),
+ toolName: 'echo',
+ provider: 'openai',
+ toolArguments: { value },
+ requestBody,
+ requestScopedConnections,
+ flowManager,
+ });
+ }
+
+ function conversationIdsSeen(): Set<string> {
+ return new Set(
+ server
+ .observedHeaders()
+ .map((headers) => headers['x-conversation-id'])
+ .filter((value): value is string => value != null),
+ );
+ }
+
+ it('populates the tool catalog and disposes the discovery connection', async () => {
+ const result = await manager.discoverServerTools({
+ serverName,
+ user,
+ configServers: { [serverName]: createRequestHeadersConfig(server.url) },
+ });
+
+ expect(result.tools?.map((tool) => tool.name)).toContain('echo');
+ expect(result.oauthRequired).toBe(false);
+ expect(server.deleteCount()).toBe(1);
+ expect(server.liveSessionCount()).toBe(0);
+ });
+
+ it('sends the regular headers but not the chat-only ones during discovery', async () => {
+ await manager.discoverServerTools({
+ serverName,
+ user,
+ configServers: { [serverName]: createRequestHeadersConfig(server.url) },
+ });
+
+ const observed = server.observedHeaders();
+ expect(observed.length).toBeGreaterThan(0);
+ for (const headers of observed) {
+ expect(headers['x-workspace']).toBe('workspace-1');
+ expect(headers['x-conversation-id']).toBe('from-headers');
+ expect(headers['x-trace-id']).toBeUndefined();
+ }
+ });
+
+ it('resolves and merges both maps at chat time, the request map winning', async () => {
+ await callEchoWithBody({
+ requestScopedConnections: createContext(),
+ requestBody: { conversationId: 'conv-1', messageId: 'msg-1' },
+ value: 'merged',
+ });
+
+ const observed = server.observedHeaders();
+ expect(observed.length).toBeGreaterThan(0);
+ for (const headers of observed) {
+ expect(headers['x-workspace']).toBe('workspace-1');
+ expect(headers['x-conversation-id']).toBe('conv-1');
+ expect(headers['x-trace-id']).toBe('msg-1');
+ }
+ });
+
+ it('isolates two request bodies in separate connections with distinct headers', async () => {
+ await callEchoWithBody({
+ requestScopedConnections: createContext(),
+ requestBody: { conversationId: 'conv-1', messageId: 'msg-1' },
+ value: 'first',
+ });
+ await callEchoWithBody({
+ requestScopedConnections: createContext(),
+ requestBody: { conversationId: 'conv-2', messageId: 'msg-2' },
+ value: 'second',
+ });
+
+ expect(server.sessionsCreated()).toBe(2);
+ expect(conversationIdsSeen()).toEqual(new Set(['conv-1', 'conv-2']));
+ expect(server.toolCallCount()).toBe(2);
+ });
+
+ it('admits a chat whose request override removes a catalog body requirement', async () => {
+ const config = createRequestHeadersConfig(server.url);
+ await manager.callTool({
+ user,
+ serverName,
+ toolName: 'echo',
+ provider: 'openai',
+ toolArguments: { value: 'shadowed' },
+ serverConfig: {
+ ...config,
+ headers: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ requestHeaders: {
+ 'x-conversation-id': 'fixed',
+ 'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}',
+ },
+ } as ParsedServerConfig,
+ requestBody: { messageId: 'msg-1' },
+ requestScopedConnections: createContext(),
+ flowManager,
+ });
+ expect(server.toolCallCount()).toBe(1);
+ expect(conversationIdsSeen()).toEqual(new Set(['fixed']));
+ });
+
+ it.each([
+ {
+ mode: 'bearer' as const,
+ name: 'Authorization',
+ chatName: 'Authorization',
+ catalog: 'Bearer catalog-key',
+ },
+ {
+ mode: 'bearer' as const,
+ name: 'Authorization',
+ chatName: 'authorization',
+ catalog: 'Bearer catalog-key',
+ },
+ {
+ mode: 'basic' as const,
+ name: 'Authorization',
+ chatName: 'AUTHORIZATION',
+ catalog: 'Basic catalog-key',
+ },
+ { mode: 'custom' as const, name: 'X-Api-Key', chatName: 'x-api-key', catalog: 'catalog-key' },
+ {
+ mode: 'custom' as const,
+ name: 'X-Custom-Key',
+ chatName: 'x-custom-key',
+ catalog: 'catalog-key',
+ },
+ ])(
+ 'uses the $mode catalog key only in discovery when chat overrides $chatName',
+ async ({ mode, name, chatName, catalog }) => {
+ const config: ParsedServerConfig = {
+ ...createRequestHeadersConfig(server.url),
+ type: 'streamable-http',
+ url: server.url,
+ apiKey: {
+ source: 'admin',
+ authorization_type: mode,
+ key: 'catalog-key',
+ ...(mode === 'custom' && name !== 'X-Api-Key' ? { custom_header: name } : {}),
+ },
+ requestHeaders: {
+ [chatName]: '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ },
+ };
+ jest.spyOn(MCPServersRegistry.getInstance(), 'getServerConfig').mockResolvedValue(config);
+ await manager.discoverServerTools({ serverName, user });
+ const discoveryHeaders = server.observedHeaders();
+ expect(discoveryHeaders.length).toBeGreaterThan(0);
+ expect(discoveryHeaders.every((headers) => headers[name.toLowerCase()] === catalog)).toBe(
+ true,
+ );
+ await manager.callTool({
+ user,
+ serverName,
+ serverConfig: config,
+ toolName: 'echo',
+ provider: 'openai',
+ toolArguments: { value: 'chat-credential' },
+ requestBody: { conversationId: 'chat-key' },
+ requestScopedConnections: createContext(),
+ flowManager,
+ });
+ const chatHeaders = server.observedHeaders().slice(discoveryHeaders.length);
+ expect(chatHeaders.length).toBeGreaterThan(0);
+ expect(chatHeaders.every((headers) => headers[name.toLowerCase()] === 'chat-key')).toBe(true);
+ expect(server.toolCallCount()).toBe(1);
+ },
+ );
+
+ it('fails closed when a runtime value the request headers need is missing', async () => {
+ await expect(
+ callEchoWithBody({
+ requestScopedConnections: createContext(),
+ requestBody: { conversationId: 'conv-1' },
+ value: 'no-message-id',
+ }),
+ ).rejects.toThrow(/messageId/);
+
+ expect(server.sessionsCreated()).toBe(0);
+ expect(server.toolCallCount()).toBe(0);
+ });
+});
diff --git a/packages/api/src/mcp/__tests__/utils.test.ts b/packages/api/src/mcp/__tests__/utils.test.ts
index 8b533241ad..f25a8e6e82 100644
--- a/packages/api/src/mcp/__tests__/utils.test.ts
+++ b/packages/api/src/mcp/__tests__/utils.test.ts
@@ -8,12 +8,16 @@ import {
redactAllServerSecrets,
redactServerSecrets,
requiresUserScopedConnection,
+ canUseAppConnection,
+ canBackfillSharedServerInstructions,
isInvalidClientMessage,
isClientRejectionMessage,
getMissingCustomUserVars,
hasCustomUserVars,
hasRuntimeUrlPlaceholders,
getMCPRequestScope,
+ toCatalogConnectionConfig,
+ applyRequestHeaders,
hasRuntimeContextPlaceholders,
getRuntimeBodyPlaceholderFields,
getMissingRuntimeBodyPlaceholderFields,
@@ -25,6 +29,7 @@ import {
filterChatSelectableMCPServers,
waitUntilDeadline,
} from '~/mcp/utils';
+import { usesDirectOpenIDBearerRecovery } from '~/mcp/openid';
describe('normalizeServerName', () => {
it('should not modify server names that already match the pattern', () => {
@@ -997,6 +1002,250 @@ describe('getMissingRuntimeBodyPlaceholderFields', () => {
});
});
+describe('operator requestHeaders', () => {
+ const config = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ source: 'yaml',
+ headers: { Authorization: 'Bearer static-token' },
+ requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ } as ParsedServerConfig;
+
+ it('leaves the catalog unscoped while the runtime stays request-scoped', () => {
+ expect(getMCPRequestScope(config)).toEqual({
+ requestScoped: true,
+ requiredBodyFields: ['conversationId'],
+ });
+ expect(requiresEphemeralUserConnection(config)).toBe(true);
+
+ const catalogConfig = toCatalogConnectionConfig(config);
+ expect(getMCPRequestScope(catalogConfig)).toEqual({
+ requestScoped: false,
+ requiredBodyFields: [],
+ });
+ expect(requiresEphemeralUserConnection(catalogConfig)).toBe(false);
+ expect(getMissingRuntimeBodyPlaceholderFields(catalogConfig)).toEqual([]);
+ });
+
+ it('still blocks the catalog for a body placeholder discovery itself sends', () => {
+ const urlScoped = toCatalogConnectionConfig({
+ ...config,
+ url: 'https://mcp.example.com/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
+ } as ParsedServerConfig);
+
+ expect(getMCPRequestScope(urlScoped).requiredBodyFields).toEqual(['messageId']);
+ expect(getMissingRuntimeBodyPlaceholderFields(urlScoped)).toEqual(['messageId']);
+ });
+
+ it('fails closed when the runtime value the request headers need is absent', () => {
+ expect(getMissingRuntimeBodyPlaceholderFields(config, { messageId: 'msg-1' })).toEqual([
+ 'conversationId',
+ ]);
+ expect(getMissingRuntimeBodyPlaceholderFields(config, { conversationId: ' ' })).toEqual([
+ 'conversationId',
+ ]);
+ expect(getMissingRuntimeBodyPlaceholderFields(config, { conversationId: 'conv-1' })).toEqual(
+ [],
+ );
+ });
+
+ it('does not resolve requestHeaders placeholders for untrusted configs', () => {
+ for (const untrusted of [
+ { ...config, source: 'user' as const, dbId: 'server-123' },
+ { ...config, source: 'plugin' as const },
+ ]) {
+ expect(getMCPRequestScope(untrusted).requestScoped).toBe(false);
+ expect(requiresEphemeralUserConnection(untrusted)).toBe(false);
+ expect(getMissingRuntimeBodyPlaceholderFields(untrusted)).toEqual([]);
+ }
+ });
+
+ it('keeps a server with chat-only headers off the shared app connection', () => {
+ const shareable = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ source: 'yaml',
+ } as ParsedServerConfig;
+
+ expect(canUseAppConnection(shareable)).toBe(true);
+ /** Static values too: the shared connection's own handshake is catalog work. */
+ expect(
+ canUseAppConnection({
+ ...shareable,
+ requestHeaders: { 'X-Workspace': 'workspace-1' },
+ } as ParsedServerConfig),
+ ).toBe(false);
+ expect(canUseAppConnection(config)).toBe(false);
+ /** An empty map declares nothing, so it must not cost the server its sharing. */
+ expect(canUseAppConnection({ ...shareable, requestHeaders: {} } as ParsedServerConfig)).toBe(
+ true,
+ );
+ });
+
+ it('does not require body values from headers shadowed by the runtime map', () => {
+ const declared: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ headers: { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ requestHeaders: { 'x-conversation': 'fixed' },
+ };
+ expect(getMissingRuntimeBodyPlaceholderFields(declared)).toEqual([]);
+ expect(hasRuntimeContextPlaceholders(declared)).toBe(false);
+ expect(getMissingRuntimeBodyPlaceholderFields(toCatalogConnectionConfig(declared))).toEqual([
+ 'conversationId',
+ ]);
+ });
+
+ it('keeps chat-only instructions out of the shared catalog, including static headers', () => {
+ const deferred: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ startup: false,
+ };
+ expect(canBackfillSharedServerInstructions(deferred)).toBe(true);
+ expect(canBackfillSharedServerInstructions({ ...deferred, requestHeaders: {} })).toBe(true);
+ expect(
+ canBackfillSharedServerInstructions({
+ ...deferred,
+ requestHeaders: { 'X-Workspace': 'chat' },
+ }),
+ ).toBe(false);
+ });
+
+ it('drops a shadowed API-key body requirement while preserving discovery authentication', () => {
+ const declared: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ apiKey: {
+ source: 'admin',
+ authorization_type: 'bearer',
+ key: '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ },
+ requestHeaders: { authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
+ };
+ const runtime = applyRequestHeaders(declared);
+ expect(getMissingRuntimeBodyPlaceholderFields(declared)).toEqual([]);
+ expect(usesDirectOpenIDBearerRecovery(runtime)).toBe(true);
+ expect(runtime.apiKey?.key).toBeUndefined();
+ expect(declared.apiKey?.key).toBe('{{LIBRECHAT_BODY_CONVERSATIONID}}');
+ expect(getMissingRuntimeBodyPlaceholderFields(toCatalogConnectionConfig(declared))).toEqual([
+ 'conversationId',
+ ]);
+ expect(applyRequestHeaders(runtime)).toBe(runtime);
+ const unshadowed = applyRequestHeaders({ ...declared, requestHeaders: { 'X-Trace': 'trace' } });
+ expect(unshadowed.apiKey).toBe(declared.apiKey);
+ });
+
+ it('never returns either header map to a client', () => {
+ const redacted = redactServerSecrets(config, { canEdit: true });
+
+ expect(redacted).not.toHaveProperty('requestHeaders');
+ expect(redacted).not.toHaveProperty('headers');
+ expect(redacted.requestScoped).toBe(true);
+ });
+});
+
+describe('toCatalogConnectionConfig', () => {
+ it('strips the chat-only map a discovery connection cannot resolve', () => {
+ const config = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { Authorization: 'Bearer static-token' },
+ requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ } as ParsedServerConfig;
+
+ const catalogConfig = toCatalogConnectionConfig(config);
+
+ expect(catalogConfig).not.toHaveProperty('requestHeaders');
+ expect((catalogConfig as { headers?: Record<string, string> }).headers).toEqual({
+ Authorization: 'Bearer static-token',
+ });
+ expect(config).toHaveProperty('requestHeaders');
+ });
+
+ it('returns the same reference when there is nothing to strip', () => {
+ const config = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { Authorization: 'Bearer static-token' },
+ } as ParsedServerConfig;
+
+ expect(toCatalogConnectionConfig(config)).toBe(config);
+ });
+});
+
+describe('applyRequestHeaders', () => {
+ it('merges the request map over headers', () => {
+ const merged = applyRequestHeaders({
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { Authorization: 'Bearer static', 'X-Keep': 'kept' },
+ requestHeaders: { 'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}' },
+ } as ParsedServerConfig) as { headers?: Record<string, string> };
+
+ expect(merged.headers).toEqual({
+ Authorization: 'Bearer static',
+ 'X-Keep': 'kept',
+ 'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}',
+ });
+ expect(merged).not.toHaveProperty('requestHeaders');
+ });
+
+ it('overrides a duplicate name regardless of casing', () => {
+ const merged = applyRequestHeaders({
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { Authorization: 'Bearer stale', 'X-Trace-Id': 'stale-trace' },
+ requestHeaders: { authorization: 'Bearer fresh', 'x-trace-id': 'fresh-trace' },
+ } as ParsedServerConfig) as { headers?: Record<string, string> };
+
+ /** Both spellings surviving would let Undici join them into `stale, fresh`. */
+ expect(merged.headers).toEqual({
+ authorization: 'Bearer fresh',
+ 'x-trace-id': 'fresh-trace',
+ });
+ });
+
+ it('is idempotent, so a config reused across connections cannot merge twice', () => {
+ const config = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { 'X-Trace-Id': 'stale' },
+ requestHeaders: { 'X-Trace-Id': 'fresh' },
+ } as ParsedServerConfig;
+
+ const once = applyRequestHeaders(config);
+ const twice = applyRequestHeaders(once);
+
+ expect(twice).toBe(once);
+ expect((twice as { headers?: Record<string, string> }).headers).toEqual({
+ 'X-Trace-Id': 'fresh',
+ });
+ });
+
+ it('returns the same reference when there is nothing to merge', () => {
+ const config = { type: 'stdio', command: 'node', args: ['server.js'] } as ParsedServerConfig;
+
+ expect(applyRequestHeaders(config)).toBe(config);
+ });
+
+ it('brings a request-header Authorization under direct-bearer recovery', () => {
+ const config = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ source: 'yaml',
+ requiresOAuth: false,
+ requestHeaders: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
+ } as ParsedServerConfig;
+
+ expect(usesDirectOpenIDBearerRecovery(config)).toBe(false);
+ expect(usesDirectOpenIDBearerRecovery(applyRequestHeaders(config))).toBe(true);
+ });
+});
+
describe('validateMCPServerConfig', () => {
it('preserves server-managed metadata on a valid effective config', () => {
const config = {
@@ -1325,3 +1574,47 @@ describe('waitUntilDeadline', () => {
await new Promise((resolve) => setImmediate(resolve));
});
});
+
+describe('shadowed generated user API keys', () => {
+ const config: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.test/mcp',
+ apiKey: { source: 'user', authorization_type: 'bearer' },
+ headers: { Authorization: 'Bearer {{MCP_API_KEY}}' },
+ requestHeaders: { authorization: 'Bearer request-secret' },
+ customUserVars: { MCP_API_KEY: { title: 'API Key', description: 'Generated key' } },
+ };
+
+ it('removes only the unused generated requirement and preserves the declaration', () => {
+ expect(hasCustomUserVars(config)).toBe(false);
+ expect(getMissingCustomUserVars(config)).toEqual([]);
+ const effective = applyRequestHeaders(config);
+ expect(effective.customUserVars).toEqual({});
+ expect(getMissingCustomUserVars(effective)).toEqual([]);
+ expect(applyRequestHeaders(effective)).toBe(effective);
+ expect(getMissingCustomUserVars(toCatalogConnectionConfig(config))).toEqual(['MCP_API_KEY']);
+ expect(config.customUserVars).toHaveProperty('MCP_API_KEY');
+ });
+
+ it.each([
+ { requestHeaders: { authorization: 'Bearer {{MCP_API_KEY}}' } },
+ { headers: { Authorization: 'Bearer {{MCP_API_KEY}}', 'X-Key': '{{MCP_API_KEY}}' } },
+ { url: 'https://mcp.example.test/{{MCP_API_KEY}}' },
+ { oauth_headers: { 'X-Key': '{{MCP_API_KEY}}' } },
+ { requestHeaders: { 'X-Unrelated': 'value' } },
+ ])('retains a key referenced by the effective configuration: %j', (fields) => {
+ expect(getMissingCustomUserVars({ ...config, ...fields })).toEqual(['MCP_API_KEY']);
+ });
+
+ it('retains explicitly declared variables', () => {
+ const declared = {
+ ...config,
+ customUserVars: {
+ ...config.customUserVars,
+ REGION: { title: 'Region', description: 'Required region' },
+ },
+ };
+ expect(getMissingCustomUserVars(declared)).toEqual(['REGION']);
+ expect(hasCustomUserVars(declared)).toBe(true);
+ });
+});
diff --git a/packages/api/src/mcp/catalog/recovery.spec.ts b/packages/api/src/mcp/catalog/recovery.spec.ts
index f5206ee836..865796e795 100644
--- a/packages/api/src/mcp/catalog/recovery.spec.ts
+++ b/packages/api/src/mcp/catalog/recovery.spec.ts
@@ -2128,3 +2128,35 @@ describe('recoverMCPServerCatalogs — discovery that outlives its budget', () =
expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('Discovery for closing'));
});
});
+
+it('recovers a catalog without loading an unused shadowed user API key', async () => {
+ const discoverServerTools = jest.fn().mockResolvedValue({ tools: [] });
+ const loadUserMCPAuthMap = jest.fn().mockResolvedValue({});
+ await recoverMCPServerCatalogs(
+ {
+ user,
+ servers: [
+ {
+ serverName: 'shadowed',
+ serverConfig: {
+ type: 'streamable-http',
+ url: 'https://shadowed.example.com/mcp',
+ apiKey: { source: 'user', authorization_type: 'basic' },
+ headers: { Authorization: 'Basic {{MCP_API_KEY}}' },
+ requestHeaders: { authorization: 'Bearer request-secret' },
+ customUserVars: { MCP_API_KEY: { title: 'API Key', description: 'Generated key' } },
+ },
+ },
+ ],
+ },
+ {
+ loadUserMCPAuthMap,
+ discoverServerTools,
+ formatServerTools: jest.fn().mockReturnValue({}),
+ getRecoveryGeneration: jest.fn().mockResolvedValue('generation-1'),
+ recoveryTracker,
+ },
+ );
+ expect(loadUserMCPAuthMap).not.toHaveBeenCalled();
+ expect(discoverServerTools).toHaveBeenCalledTimes(1);
+});
diff --git a/packages/api/src/mcp/headers.ts b/packages/api/src/mcp/headers.ts
new file mode 100644
index 0000000000..63d6af270a
--- /dev/null
+++ b/packages/api/src/mcp/headers.ts
@@ -0,0 +1,38 @@
+import type { MCPOptions } from 'librechat-data-provider';
+
+type ApiKeyConfig = Partial<NonNullable<MCPOptions['apiKey']>> | null | undefined;
+
+function getApiKeyHeaderName(apiKey: ApiKeyConfig): string {
+ return apiKey?.authorization_type === 'custom'
+ ? apiKey.custom_header || 'X-Api-Key'
+ : 'Authorization';
+}
+
+/** The header injected by an operator-provided API key, before placeholder resolution. */
+export function getAdminApiKeyHeader(
+ apiKey: ApiKeyConfig,
+): { name: string; value: string } | undefined {
+ if (apiKey?.source !== 'admin' || !apiKey.key) {
+ return;
+ }
+ const { key, authorization_type } = apiKey;
+ const name = getApiKeyHeaderName(apiKey);
+ const prefixes = { basic: 'Basic ', bearer: 'Bearer ', custom: '' };
+ const prefix = prefixes[authorization_type ?? 'custom'];
+ return { name, value: `${prefix}${key}` };
+}
+
+/** A shadowed catalog credential must not be injected or required by a chat connection. */
+export function isApiKeyHeaderOverridden(
+ apiKey: ApiKeyConfig,
+ requestHeaders?: Record<string, string | undefined>,
+): boolean {
+ const injected = apiKey?.source === 'user' || getAdminApiKeyHeader(apiKey) != null;
+ return (
+ injected &&
+ requestHeaders != null &&
+ Object.keys(requestHeaders).some(
+ (name) => name.toLowerCase() === getApiKeyHeaderName(apiKey).toLowerCase(),
+ )
+ );
+}
diff --git a/packages/api/src/mcp/openid.ts b/packages/api/src/mcp/openid.ts
index 60887f43ef..30063dc2b1 100644
--- a/packages/api/src/mcp/openid.ts
+++ b/packages/api/src/mcp/openid.ts
@@ -4,6 +4,7 @@ import type { MCPOptions } from './types';
import { isRetryableOboExchangeError } from './oauth/obo';
import { MCPAuthenticationRefreshError } from './errors';
import { OpenIDReauthRequiredError } from '~/utils/oidc';
+import { getAdminApiKeyHeader } from './headers';
import { isAbortError } from '~/utils/errors';
const OPENID_ACCESS_TOKEN_PATTERN = /\{\{LIBRECHAT_OPENID_(?:ACCESS_TOKEN|TOKEN)\}\}/;
@@ -35,13 +36,7 @@ function getAuthorizationTemplateValue(value: string): string {
}
function apiKeyOwnsAuthorization(config: DirectBearerConfig): boolean {
- const apiKey = config.apiKey;
- return !!(
- apiKey?.source === 'admin' &&
- apiKey.key &&
- (apiKey.authorization_type !== 'custom' ||
- apiKey.custom_header?.toLowerCase() === 'authorization')
- );
+ return getAdminApiKeyHeader(config.apiKey)?.name.toLowerCase() === 'authorization';
}
function resolveAccessTokenPlaceholders(
diff --git a/packages/api/src/mcp/registry/MCPServerInspector.ts b/packages/api/src/mcp/registry/MCPServerInspector.ts
index 4d3af8fac3..6cb0c05dcf 100644
--- a/packages/api/src/mcp/registry/MCPServerInspector.ts
+++ b/packages/api/src/mcp/registry/MCPServerInspector.ts
@@ -5,8 +5,10 @@ import type { MCPConnection } from '~/mcp/connection';
import type * as t from '~/mcp/types';
import {
hasCustomUserVars,
+ applyRequestHeaders,
hasRuntimeContextPlaceholders,
hasRuntimeUrlPlaceholders,
+ toCatalogConnectionConfig,
isUserSourced,
} from '~/mcp/utils';
import { isMCPDomainAllowed, extractMCPServerDomain } from '~/auth/domain';
@@ -74,6 +76,12 @@ export class MCPServerInspector {
this.warnOnUnrestrictedRuntimeUrl();
await this.detectOAuth();
+ /** Startup inspection is catalog work with no chat request, so the chat-only
+ * headers come off before BOTH the eligibility gate and the probe. Left on,
+ * a `{{LIBRECHAT_BODY_*}}` placeholder there fails
+ * `hasRuntimeContextPlaceholders` and skips inspection altogether — the
+ * very outcome `requestHeaders` exists to avoid. */
+ const catalogConfig = toCatalogConnectionConfig(this.config);
if (
this.config.startup !== false &&
!this.config.requiresOAuth &&
@@ -81,14 +89,15 @@ export class MCPServerInspector {
// user-provided API key is supplied per-user at connect time; an unauthenticated
// probe here would 401 against a bearer server and fail inspection
this.config.apiKey?.source !== 'user' &&
- !hasRuntimeContextPlaceholders(this.config) &&
+ !hasRuntimeContextPlaceholders(catalogConfig) &&
!this.config.obo
) {
let tempConnection = false;
if (!this.connection) {
tempConnection = true;
this.connection = await MCPConnectionFactory.create({
- serverConfig: this.config,
+ serverConfig: catalogConfig,
+ serverDefinition: this.config,
serverName: this.serverName,
dbSourced: isUserSourced(this.config),
useSSRFProtection: this.useSSRFProtection,
@@ -124,7 +133,7 @@ export class MCPServerInspector {
}
private async detectOAuth(): Promise<void> {
- if (isDirectOpenIDBearerRecoveryEnabled(this.config)) {
+ if (isDirectOpenIDBearerRecoveryEnabled(applyRequestHeaders(this.config))) {
this.config.requiresOAuth = false;
this.config.oauthMetadata = null;
return;
diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.ts
index 9e50ae8e7b..ddd6c0d80e 100644
--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts
+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts
@@ -106,6 +106,7 @@ const ADMIN_CONFIGURABLE_FIELDS = [
'stderr',
'url',
'headers',
+ 'requestHeaders',
'proxy',
'requiresOAuth',
'apiKey',
diff --git a/packages/api/src/mcp/registry/__tests__/MCPServerInspector.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServerInspector.test.ts
index b311976af6..b75754c5bd 100644
--- a/packages/api/src/mcp/registry/__tests__/MCPServerInspector.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/MCPServerInspector.test.ts
@@ -97,6 +97,26 @@ describe('MCPServerInspector', () => {
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
+ it('recognizes a chat-only direct bearer before probing OAuth metadata', async () => {
+ const rawConfig: t.ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp-server.example.com/mcp',
+ source: 'yaml',
+ requestHeaders: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
+ };
+ (MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
+ const result = await MCPServerInspector.inspect('test_server', rawConfig);
+ expect(result.requiresOAuth).toBe(false);
+ expect(mockDetectOAuthRequirement).not.toHaveBeenCalled();
+ expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ serverDefinition: rawConfig,
+ serverConfig: expect.not.objectContaining({ requestHeaders: expect.anything() }),
+ }),
+ );
+ expect(result.toolFunctions).toBeDefined();
+ });
+
it('should skip capabilities fetch when startup=false', async () => {
const rawConfig: t.MCPOptions = {
type: 'stdio',
@@ -194,6 +214,31 @@ describe('MCPServerInspector', () => {
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
+ it('should still probe at startup when body placeholders live only in requestHeaders', async () => {
+ mockDetectOAuthRequirement.mockResolvedValue({
+ requiresOAuth: false,
+ method: 'no-metadata-found',
+ });
+
+ const rawConfig: t.MCPOptions = {
+ type: 'streamable-http',
+ url: 'https://mcp-server.example.com/mcp',
+ headers: { 'X-Workspace': 'workspace-1' },
+ requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ };
+
+ const tempMockConnection = createMockConnection('test_server');
+ (MCPConnectionFactory.create as jest.Mock).mockResolvedValue(tempMockConnection);
+
+ await MCPServerInspector.inspect('test_server', rawConfig);
+
+ /** The chat-only map must neither block the probe nor reach it. */
+ expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
+ const probeConfig = (MCPConnectionFactory.create as jest.Mock).mock.calls[0][0].serverConfig;
+ expect(probeConfig.headers).toEqual({ 'X-Workspace': 'workspace-1' });
+ expect(probeConfig).not.toHaveProperty('requestHeaders');
+ });
+
it('should skip OAuth detection when trusted URL needs runtime user context', async () => {
const rawConfig: t.MCPOptions = {
type: 'streamable-http',
diff --git a/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts b/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts
index 31a384d7a2..037dfbf388 100644
--- a/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts
@@ -171,6 +171,27 @@ describe('MCPServersRegistry — ensureConfigServers', () => {
expect(inspectSpy).toHaveBeenCalledTimes(1);
});
+ it('should lazy-init YAML server when admin overrides only the requestHeaders field', async () => {
+ await registry.addServer('yaml_remote', sseConfig, 'CACHE');
+ inspectSpy.mockClear();
+
+ const overrideConfig: t.MCPOptions = {
+ ...sseConfig,
+ requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ };
+ const result = await registry.ensureConfigServers({
+ yaml_remote: overrideConfig,
+ });
+
+ expect(result).toHaveProperty('yaml_remote');
+ expect(
+ (result.yaml_remote as { requestHeaders?: Record<string, string> }).requestHeaders,
+ ).toEqual({
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ });
+ expect(inspectSpy).toHaveBeenCalledTimes(1);
+ });
+
it('should lazy-init YAML server when admin overrides only the OBO field', async () => {
await registry.addServer('yaml_remote', sseConfig, 'CACHE');
inspectSpy.mockClear();
diff --git a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
index d5fd98d0f0..f439eb2186 100644
--- a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
+++ b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
@@ -58,6 +58,26 @@ function sanitizeCredentialPlaceholders(
return sanitized;
}
+/**
+ * Sanitizes every header map a shared config carries. `requestHeaders` is
+ * included because it reaches the upstream server exactly like `headers` does:
+ * left unsanitized, a user-managed config could name a privileged placeholder
+ * there and have the runtime resolve it at chat time.
+ */
+function sanitizeConfigHeaderMaps(config: ParsedServerConfig): {
+ headers?: Record<string, string>;
+ requestHeaders?: Record<string, string>;
+} {
+ const carrier = config as ParsedServerConfig & {
+ headers?: Record<string, string>;
+ requestHeaders?: Record<string, string>;
+ };
+ return {
+ headers: sanitizeCredentialPlaceholders(carrier.headers),
+ requestHeaders: sanitizeCredentialPlaceholders(carrier.requestHeaders),
+ };
+}
+
function stripBlockedOAuthEndpointParams(url?: string): string | undefined {
if (!url) {
return url;
@@ -297,9 +317,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
const sanitizedConfig = sanitizeUserManagedOAuthConfig({
...config,
- headers: sanitizeCredentialPlaceholders(
- (config as ParsedServerConfig & { headers?: Record<string, string> }).headers,
- ),
+ ...sanitizeConfigHeaderMaps(config),
} as ParsedServerConfig);
/** Transformed user-provided API key config (adds customUserVars and headers) */
@@ -346,9 +364,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
let configToSave: ParsedServerConfig = sanitizeUserManagedOAuthConfig({
...config,
- headers: sanitizeCredentialPlaceholders(
- (config as ParsedServerConfig & { headers?: Record<string, string> }).headers,
- ),
+ ...sanitizeConfigHeaderMaps(config),
} as ParsedServerConfig);
/** Transformed user-provided API key config (adds customUserVars and headers) */
diff --git a/packages/api/src/mcp/toolsChanged.spec.ts b/packages/api/src/mcp/toolsChanged.spec.ts
index a3167dceb1..2932a7a2ea 100644
--- a/packages/api/src/mcp/toolsChanged.spec.ts
+++ b/packages/api/src/mcp/toolsChanged.spec.ts
@@ -65,6 +65,75 @@ describe('MCP tools-changed dispatch', () => {
);
});
+ it('keeps catalog headers and request overrides in the server identity', () => {
+ const declared: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { 'X-Workspace': 'catalog-1' },
+ requestHeaders: { 'X-Workspace': 'chat' },
+ };
+ const generation = getMCPAppToolsPublicationGeneration(declared);
+ expect(
+ getMCPAppToolsPublicationGeneration({
+ ...declared,
+ headers: { 'X-Workspace': 'catalog-2' },
+ }),
+ ).not.toBe(generation);
+ expect(
+ getMCPAppToolsPublicationGeneration({
+ ...declared,
+ requestHeaders: { 'X-Workspace': 'chat-2' },
+ }),
+ ).not.toBe(generation);
+ expect(
+ getMCPAppToolsPublicationGeneration({
+ ...declared,
+ headers: { 'X-Workspace': 'chat' },
+ requestHeaders: undefined,
+ }),
+ ).not.toBe(generation);
+ });
+
+ it('rotates the declared identity when a chat override of the catalog API key changes', () => {
+ const config: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ apiKey: { source: 'admin', authorization_type: 'bearer', key: 'catalog' },
+ requestHeaders: { Authorization: 'Bearer chat-one' },
+ };
+ expect(getMCPAppToolsPublicationGeneration(config)).not.toBe(
+ getMCPAppToolsPublicationGeneration({
+ ...config,
+ requestHeaders: { Authorization: 'Bearer chat-two' },
+ }),
+ );
+ });
+
+ it('includes request-header environment changes without mutating the declaration', () => {
+ const variable = 'MCP_REQUEST_HEADER_GENERATION_TEST';
+ const original = process.env[variable];
+ const config: ParsedServerConfig = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com',
+ source: 'yaml',
+ requestHeaders: { 'X-Workspace': `\${${variable}}` },
+ };
+ try {
+ process.env[variable] = 'first';
+ const first = getMCPAppToolsPublicationGeneration(config);
+ process.env[variable] = 'second';
+ expect(getMCPAppToolsPublicationGeneration(config)).not.toBe(first);
+ expect(config.requestHeaders).toEqual({ 'X-Workspace': `\${${variable}}` });
+ } finally {
+ if (original === undefined) {
+ delete process.env[variable];
+ } else {
+ process.env[variable] = original;
+ }
+ }
+ });
+
it('includes the resolved runtime environment in app publication generations', () => {
const variable = 'LIBRECHAT_MCP_CATALOG_ORIGIN_TEST';
const original = process.env[variable];
diff --git a/packages/api/src/mcp/toolsChanged.ts b/packages/api/src/mcp/toolsChanged.ts
index be250889eb..6c8854783d 100644
--- a/packages/api/src/mcp/toolsChanged.ts
+++ b/packages/api/src/mcp/toolsChanged.ts
@@ -36,7 +36,16 @@ export function getMCPAppToolsPublicationGeneration(config: ParsedServerConfig):
* a rolling deployment. Address the catalog by the effective runtime config so an old replica's
* live connection cannot publish into the new replica's slice. DB-sourced configs deliberately
* remain literal because processMCPEnv derives that rule from dbId. */
- const runtimeConfig = processMCPEnv({ options: config });
+ /** Keep both header maps: a request override can hide a catalog-only change. */
+ let runtimeConfig = processMCPEnv({ options: config });
+ if ('requestHeaders' in config && config.requestHeaders != null) {
+ const requestConfig = processMCPEnv({
+ options: { ...config, apiKey: undefined, headers: config.requestHeaders },
+ });
+ if ('headers' in requestConfig && 'requestHeaders' in runtimeConfig) {
+ runtimeConfig = { ...runtimeConfig, requestHeaders: requestConfig.headers };
+ }
+ }
const parsedConfig = MCPOptionsSchema.parse(runtimeConfig) as StableConfigValue;
return createHash('sha256')
.update(JSON.stringify(sortConfigValue(parsedConfig)))
diff --git a/packages/api/src/mcp/utils.ts b/packages/api/src/mcp/utils.ts
index 12edf4aaac..e393651903 100644
--- a/packages/api/src/mcp/utils.ts
+++ b/packages/api/src/mcp/utils.ts
@@ -7,11 +7,12 @@ import {
normalizeMCPToolKey,
buildServerNameAliases,
} from 'librechat-data-provider';
-import type { AgentToolOptions } from 'librechat-data-provider';
+import type { AgentToolOptions, MCPOptions } from 'librechat-data-provider';
import type { ParsedServerConfig } from '~/mcp/types';
import type { RequestBody } from '~/types';
import { isDirectOpenIDBearerRecoveryEnabled } from '~/mcp/openid';
import { ALLOWED_BODY_FIELDS, isPluginSourced } from '~/utils/env';
+import { isApiKeyHeaderOverridden } from './headers';
import { isEnabled } from '~/utils/common';
export const mcpToolPattern: RegExp = new RegExp(`^.+${Constants.mcp_delimiter}.+$`);
@@ -216,7 +217,7 @@ type UserScopedConnectionConfig = Pick<
> & {
/** Loosened like the fields below: raw (pre-inspection) configs carry
* optional API-key fields, and the gating predicates only inspect them. */
- apiKey?: { key?: string; source?: 'user' | 'admin' } | null;
+ apiKey?: Partial<NonNullable<ParsedServerConfig['apiKey']>> | null;
args?: string[];
/** Loosened from the parsed shapes so raw (pre-inspection) configs qualify;
* scoping predicates only check key presence */
@@ -227,17 +228,35 @@ type UserScopedConnectionConfig = Pick<
>;
env?: Record<string, string | undefined>;
headers?: Record<string, string | undefined>;
+ /** Operator-configured headers sent only on chat-time connections. */
+ requestHeaders?: Record<string, string | undefined>;
oauth?: PlaceholderValue;
oauth_headers?: Record<string, string | undefined>;
url?: string;
};
+function mergeHeaderMaps<T extends string | undefined>(
+ headers: Record<string, T> | undefined,
+ requestHeaders: Record<string, T>,
+): Record<string, T> {
+ const overridden = new Set(Object.keys(requestHeaders).map((name) => name.toLowerCase()));
+ const merged: Record<string, T> = {};
+ for (const [name, value] of Object.entries(headers ?? {})) {
+ if (!overridden.has(name.toLowerCase())) {
+ merged[name] = value;
+ }
+ }
+ return { ...merged, ...requestHeaders };
+}
+
function placeholderBearingFields(config: UserScopedConnectionConfig): PlaceholderValue[] {
return [
- config.apiKey?.key,
+ isApiKeyHeaderOverridden(config.apiKey, config.requestHeaders) ? undefined : config.apiKey?.key,
config.args,
config.env,
- config.headers,
+ config.requestHeaders == null
+ ? config.headers
+ : mergeHeaderMaps(config.headers, config.requestHeaders),
config.oauth,
config.oauth_headers,
config.url,
@@ -272,11 +291,22 @@ export function requiresOAuthMachinery(config: ParsedServerConfig): boolean {
return isOAuthServer(config) || config.obo != null;
}
-/** Checks that `customUserVars` is present AND non-empty (guards against truthy `{}`) */
-export function hasCustomUserVars(
- config: Pick<UserScopedConnectionConfig, 'customUserVars'>,
-): boolean {
- return !!config.customUserVars && Object.keys(config.customUserVars).length > 0;
+/** Required chat credentials, retaining explicit variables and any still-used generated key. */
+function requiredCustomUserVars(config: UserScopedConnectionConfig): string[] {
+ const keys = Object.keys(config.customUserVars ?? {});
+ if (
+ config.apiKey?.source !== 'user' ||
+ !isApiKeyHeaderOverridden(config.apiKey, config.requestHeaders) ||
+ placeholderBearingFields(config).some((value) => hasPlaceholder(value, /\{\{MCP_API_KEY\}\}/))
+ ) {
+ return keys;
+ }
+ return keys.filter((key) => key !== 'MCP_API_KEY');
+}
+
+/** Checks the effective chat requirements, without weakening catalog-only credentials. */
+export function hasCustomUserVars(config: UserScopedConnectionConfig): boolean {
+ return requiredCustomUserVars(config).length > 0;
}
function hasRuntimeContextPlaceholder(value: PlaceholderValue): boolean {
@@ -374,6 +404,65 @@ export function getMCPRequestScope(config: UserScopedConnectionConfig): MCPReque
return { requestScoped: fields.length > 0, requiredBodyFields: fields };
}
+/**
+ * Folds the operator's chat-only `requestHeaders` into `headers`, so everything
+ * downstream — direct-bearer detection, Graph preprocessing, `processMCPEnv`,
+ * the transports — keeps reading ONE header map and never has to learn about a
+ * second one. Called at the entry of each resolution pipeline, before any
+ * consumer inspects the config.
+ *
+ * HTTP header names are case-insensitive, so a base `Authorization` is dropped
+ * when the request map declares `authorization`: keeping both would let Undici
+ * join the values (`old, new`) instead of letting `requestHeaders` win.
+ *
+ * The field is consumed as it merges, making this idempotent for a config that
+ * passes through twice (checkout joiners, direct-bearer recovery).
+ */
+export function applyRequestHeaders<T extends MCPOptions>(config: T): T {
+ const carrier = config as T & {
+ headers?: Record<string, string>;
+ requestHeaders?: Record<string, string>;
+ };
+ if (carrier.requestHeaders == null) {
+ return config;
+ }
+
+ const merged = {
+ ...carrier,
+ headers: mergeHeaderMaps(carrier.headers, carrier.requestHeaders),
+ };
+ if (carrier.apiKey && isApiKeyHeaderOverridden(carrier.apiKey, carrier.requestHeaders)) {
+ /** Keep the explicit auth mode, but disarm its lower-priority header injection. */
+ merged.apiKey = { ...carrier.apiKey, key: undefined };
+ }
+ if (carrier.customUserVars) {
+ const required = new Set(requiredCustomUserVars(carrier));
+ merged.customUserVars = Object.fromEntries(
+ Object.entries(carrier.customUserVars).filter(([key]) => required.has(key)),
+ );
+ }
+ delete merged.requestHeaders;
+ return merged;
+}
+
+/**
+ * Strips the operator's chat-only `requestHeaders` for a catalog (discovery)
+ * connection. Discovery has no conversation or message to resolve a
+ * `{{LIBRECHAT_BODY_*}}` placeholder against, so sending the map at all would
+ * either leak a literal placeholder upstream or resolve it to an empty value.
+ *
+ * Returns the same reference when there is nothing to strip.
+ */
+export function toCatalogConnectionConfig<T extends MCPOptions>(config: T): T {
+ const carrier = config as T & { requestHeaders?: Record<string, string> };
+ if (carrier.requestHeaders == null) {
+ return config;
+ }
+ const catalogConfig = { ...carrier };
+ delete catalogConfig.requestHeaders;
+ return catalogConfig;
+}
+
export function getRuntimeBodyPlaceholderFields(
config: UserScopedConnectionConfig,
): Array<keyof RequestBody> {
@@ -511,10 +600,29 @@ export function requiresUserScopedConnection(config: UserScopedConnectionConfig)
);
}
+/**
+ * Whether the config declares chat-only headers. Guards against a truthy `{}`
+ * the way `hasCustomUserVars` does.
+ */
+function hasChatOnlyHeaders(config: UserScopedConnectionConfig): boolean {
+ return !!config.requestHeaders && Object.keys(config.requestHeaders).length > 0;
+}
+
/** Whether a server can share one operator-owned connection across all users. */
export function canUseAppConnection(config: UserScopedConnectionConfig): boolean {
return (
- config.startup !== false && !isUserSourced(config) && !requiresUserScopedConnection(config)
+ config.startup !== false &&
+ !isUserSourced(config) &&
+ !requiresUserScopedConnection(config) &&
+ /**
+ * One session cannot serve both sides of `requestHeaders`: an app-shared
+ * connection's own `initialize` and `tools/list` are catalog requests that
+ * must omit them, while its chat tool calls must send them. Placeholder
+ * values are already excluded through `requiresUserScopedConnection`; STATIC
+ * values reach here, and sharing would bake chat-only headers into the
+ * startup handshake every later catalog read reuses.
+ */
+ !hasChatOnlyHeaders(config)
);
}
@@ -528,6 +636,7 @@ export function canUseAppConnection(config: UserScopedConnectionConfig): boolean
export function canBackfillSharedServerInstructions(config: UserScopedConnectionConfig): boolean {
return (
config.startup === false &&
+ !hasChatOnlyHeaders(config) &&
!requiresUserScopedConnection(config) &&
/** A configured `oauth` block is identity-scoped even when `requiresOAuth`
* is unset or was stamped `false` by the skipped startup inspection —
@@ -550,13 +659,13 @@ export function canBackfillSharedServerInstructions(config: UserScopedConnection
* otherwise every tool call fails authentication. See issue #10969.
*/
export function getMissingCustomUserVars(
- config: Pick<ParsedServerConfig, 'customUserVars'>,
+ config: UserScopedConnectionConfig,
providedVars?: Record<string, string> | null,
): string[] {
if (!hasCustomUserVars(config)) {
return [];
}
- return Object.keys(config.customUserVars ?? {}).filter((key) => {
+ return requiredCustomUserVars(config).filter((key) => {
const value = providedVars?.[key];
return value == null || (typeof value === 'string' && value.trim() === '');
});
diff --git a/packages/api/src/schedules/mcp.spec.ts b/packages/api/src/schedules/mcp.spec.ts
index 35c20b47c1..da647d57af 100644
--- a/packages/api/src/schedules/mcp.spec.ts
+++ b/packages/api/src/schedules/mcp.spec.ts
@@ -1546,3 +1546,18 @@ it('enforces the aggregate deadline while loading the agent graph', async () =>
name: 'TimeoutError',
});
});
+
+it('admits a scheduled connection when request headers shadow an unused generated user key', async () => {
+ const { check, deps } = setup();
+ deps.getServerConfigs = async () => ({
+ docs: {
+ ...server,
+ apiKey: { source: 'user', authorization_type: 'custom', custom_header: 'X-Api-Key' },
+ headers: { 'X-Api-Key': '{{MCP_API_KEY}}' },
+ requestHeaders: { 'x-api-key': 'request-secret' },
+ customUserVars: { MCP_API_KEY: { title: 'API Key', description: 'Generated key' } },
+ },
+ });
+ await check('agent', principal);
+ expect(deps.connect).toHaveBeenCalledTimes(1);
+});
diff --git a/packages/api/src/utils/env.spec.ts b/packages/api/src/utils/env.spec.ts
index 25db696d31..a0f8c43c08 100644
--- a/packages/api/src/utils/env.spec.ts
+++ b/packages/api/src/utils/env.spec.ts
@@ -9,6 +9,7 @@ import {
processMCPEnv,
encodeHeaderValue,
} from './env';
+import { applyRequestHeaders } from '~/mcp/utils';
function isStdioOptions(options: MCPOptions): options is Extract<MCPOptions, { type?: 'stdio' }> {
return !options.type || options.type === 'stdio';
@@ -1189,6 +1190,77 @@ describe('processMCPEnv', () => {
});
});
+ /**
+ * `applyRequestHeaders` runs at each pipeline entry, ahead of `processMCPEnv`,
+ * so the merged map is what env resolution sees. These exercise that order
+ * rather than either half alone.
+ */
+ it('should resolve merged requestHeaders like any other header', () => {
+ const user = createTestUser({ id: 'user-123' });
+ const options: MCPOptions = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/api',
+ headers: { 'X-User-Id': '{{LIBRECHAT_USER_ID}}' },
+ requestHeaders: {
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ 'X-Static': 'static-value',
+ },
+ };
+
+ const result = processMCPEnv({
+ options: applyRequestHeaders(options),
+ user,
+ body: { conversationId: 'conv-1' },
+ });
+
+ expect('headers' in result! && result.headers).toEqual({
+ 'X-User-Id': 'user-123',
+ 'X-Conversation-Id': 'conv-1',
+ 'X-Static': 'static-value',
+ });
+ expect(result).not.toHaveProperty('requestHeaders');
+ });
+
+ it('should NOT resolve merged requestHeaders when dbSourced', () => {
+ const user = createTestUser({ id: 'user-123' });
+ const options: MCPOptions = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/api',
+ requestHeaders: {
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ },
+ };
+
+ const result = processMCPEnv({
+ options: applyRequestHeaders(options),
+ user,
+ body: { conversationId: 'conv-1' },
+ dbSourced: true,
+ });
+
+ expect('headers' in result! && result.headers).toEqual({
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ });
+ });
+
+ it('should keep plugin-sourced requestHeaders verbatim', () => {
+ const user = createTestUser({ id: 'user-123' });
+ const options = {
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/api',
+ source: 'plugin',
+ headers: { 'X-Keep': 'kept' },
+ requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ } as MCPOptions & { source: string };
+
+ const result = processMCPEnv({ options, user, body: { conversationId: 'conv-1' } });
+
+ expect('headers' in result! && result.headers).toEqual({ 'X-Keep': 'kept' });
+ expect((result as { requestHeaders?: Record<string, string> }).requestHeaders).toEqual({
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ });
+ });
+
it('should process user field placeholders in all fields', () => {
const user = createTestUser({
id: 'user-123',
diff --git a/packages/api/src/utils/env.ts b/packages/api/src/utils/env.ts
index 1966a1d984..d880fedfda 100644
--- a/packages/api/src/utils/env.ts
+++ b/packages/api/src/utils/env.ts
@@ -10,6 +10,7 @@ import {
processOpenIDPlaceholders,
OpenIDReauthRequiredError,
} from './oidc';
+import { getAdminApiKeyHeader } from '~/mcp/headers';
/**
* Provenance marker for MCP servers contributed by an Agent Plugins package.
@@ -417,36 +418,13 @@ export function processMCPEnv(params: {
const newObj: MCPOptions = structuredClone(options);
- // Apply admin-provided API key to headers at runtime
- // Note: User-provided keys use {{MCP_API_KEY}} placeholder in headers,
- // which is processed later via customUserVars replacement
- if ('apiKey' in newObj && newObj.apiKey) {
- const apiKeyConfig = newObj.apiKey as {
- key?: string;
- source: 'admin' | 'user';
- authorization_type: 'basic' | 'bearer' | 'custom';
- custom_header?: string;
+ const adminHeader = getAdminApiKeyHeader(newObj.apiKey);
+ if (adminHeader) {
+ const objWithHeaders = newObj as { headers?: Record<string, string> };
+ objWithHeaders.headers = {
+ ...objWithHeaders.headers,
+ [adminHeader.name]: adminHeader.value,
};
-
- if (apiKeyConfig.source === 'admin' && apiKeyConfig.key) {
- const { key, authorization_type, custom_header } = apiKeyConfig;
- const headerName =
- authorization_type === 'custom' ? custom_header || 'X-Api-Key' : 'Authorization';
-
- let headerValue = key;
- if (authorization_type === 'basic') {
- headerValue = `Basic ${key}`;
- } else if (authorization_type === 'bearer') {
- headerValue = `Bearer ${key}`;
- }
-
- // Initialize headers if needed and add the API key header (overwrites if header already exists)
- const objWithHeaders = newObj as { headers?: Record<string, string> };
- if (!objWithHeaders.headers) {
- objWithHeaders.headers = {};
- }
- objWithHeaders.headers[headerName] = headerValue;
- }
}
if ('env' in newObj && newObj.env) {
diff --git a/packages/data-provider/specs/mcp.spec.ts b/packages/data-provider/specs/mcp.spec.ts
index 5c9f756b97..10a73e3ad1 100644
--- a/packages/data-provider/specs/mcp.spec.ts
+++ b/packages/data-provider/specs/mcp.spec.ts
@@ -815,6 +815,47 @@ describe('MCP schemas', () => {
});
});
+describe('requestHeaders', () => {
+ it('accepts the operator map on remote transports', () => {
+ const result = StreamableHTTPOptionsSchema.safeParse({
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ headers: { Authorization: 'Bearer token' },
+ requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
+ });
+
+ expect(result.success).toBe(true);
+ if (result.success) {
+ expect(result.data.requestHeaders).toEqual({
+ 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
+ });
+ expect(result.data.headers).toEqual({ Authorization: 'Bearer token' });
+ }
+ });
+
+ it('rejects non-string header values', () => {
+ const result = StreamableHTTPOptionsSchema.safeParse({
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ requestHeaders: { 'X-Conversation-Id': 42 },
+ });
+
+ expect(result.success).toBe(false);
+ });
+
+ it('is optional, leaving existing configurations unchanged', () => {
+ const result = StreamableHTTPOptionsSchema.safeParse({
+ type: 'streamable-http',
+ url: 'https://mcp.example.com/mcp',
+ });
+
+ expect(result.success).toBe(true);
+ if (result.success) {
+ expect(result.data.requestHeaders).toBeUndefined();
+ }
+ });
+});
+
describe('MCP_USER_INPUT_FIELDS', () => {
it('includes the expected user-input fields and excludes server-managed ones', () => {
// Sanity check on the schema-derived field set. This is the comparison
@@ -831,6 +872,7 @@ describe('MCP_USER_INPUT_FIELDS', () => {
expect(MCP_USER_INPUT_FIELDS.has('obo')).toBe(true);
expect(MCP_USER_INPUT_FIELDS.has('proxy')).toBe(true);
expect(MCP_USER_INPUT_FIELDS.has('headers')).toBe(true);
+ expect(MCP_USER_INPUT_FIELDS.has('requestHeaders')).toBe(true);
// Server-managed fields should NOT be in this set — they're stripped by
// omitServerManagedFields() before MCPServerUserInputSchema is built.
diff --git a/packages/data-provider/src/mcp.ts b/packages/data-provider/src/mcp.ts
index 9072b4a223..c37f9b3cea 100644
--- a/packages/data-provider/src/mcp.ts
+++ b/packages/data-provider/src/mcp.ts
@@ -384,6 +384,13 @@ export const WebSocketOptionsSchema = BaseOptionsSchema.extend({
export const SSEOptionsSchema = BaseOptionsSchema.extend({
type: z.literal('sse').default('sse'),
headers: z.record(z.string(), z.string()).optional(),
+ /**
+ * Headers resolved from the live chat request and merged over `headers`.
+ * Omitted during catalog discovery, which has no request context, so a
+ * `{{LIBRECHAT_BODY_*}}` placeholder here does not block tool listing.
+ * On a duplicate header name the resolved `requestHeaders` value wins.
+ */
+ requestHeaders: z.record(z.string(), z.string()).optional(),
/**
* On-Behalf-Of (OBO) token exchange configuration.
* When configured, LibreChat exchanges the logged-in user's federated access token
@@ -412,6 +419,13 @@ export const SSEOptionsSchema = BaseOptionsSchema.extend({
export const StreamableHTTPOptionsSchema = BaseOptionsSchema.extend({
type: z.union([z.literal('streamable-http'), z.literal('http')]),
headers: z.record(z.string(), z.string()).optional(),
+ /**
+ * Headers resolved from the live chat request and merged over `headers`.
+ * Omitted during catalog discovery, which has no request context, so a
+ * `{{LIBRECHAT_BODY_*}}` placeholder here does not block tool listing.
+ * On a duplicate header name the resolved `requestHeaders` value wins.
+ */
+ requestHeaders: z.record(z.string(), z.string()).optional(),
/**
* On-Behalf-Of (OBO) token exchange configuration.
* When configured, LibreChat exchanges the logged-in user's federated access token