From a26a6709ff30ee0925d9ed7fa370d96ada4e417b Mon Sep 17 00:00:00 2001 From: "lia-by-librechat[bot]" <328778573+lia-by-librechat[bot]@users.noreply.github.com> Date: Wed, 16 Sep 2026 15:16:40 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=AA=20feat:=20Send=20Per-Request=20MCP?= =?UTF-8?q?=20Headers=20Without=20Hiding=20the=20Tool=20Catalog=20(#15988)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📪 feat: Send Per-Request MCP Headers Without Hiding the Tool Catalog A `{{LIBRECHAT_BODY_*}}` placeholder in an MCP server's `headers` marks the server request-scoped, and catalog discovery has no conversation to resolve it against, so LibreChat skipped tool discovery and the server appeared with no individual tools. Operators can now declare those headers separately in `requestHeaders`, which discovery omits and chat turns resolve and merge over `headers`. * fix: normalize requestHeaders at each resolution entry point Registering the new field in every consumer that enumerates header-bearing config fields left five gaps: startup inspection, case-insensitive override, the admin-configurable comparison surface, Graph token preprocessing, and direct-bearer recovery. Fold `requestHeaders` into `headers` at the entry of each resolution pipeline instead, so Graph preprocessing, direct-bearer detection, `processMCPEnv` and the transports keep reading one header map and never learn a second exists. Catalog paths strip it at the same boundary, startup inspection included. * fix: keep servers with chat-only headers off the shared app connection A static `requestHeaders` map left a server eligible for app-level sharing, and `ConnectionsRepository.loadConnection` handed the raw config to the factory, so the shared session's own `initialize` and `tools/list` carried headers documented as chat-only — and every later catalog read reused that session. One session cannot serve both sides of the field. Exclude such configs from `canUseAppConnection`, the single predicate both `connectAppServers` and the repository's own app-level gate already consult, so the chat turn keeps its headers on a user-scoped connection while catalog work never sees them. * fix: normalize requestHeaders before the manager's bearer decisions `createUserConnectionInternal` reads `usesDirectOpenIDBearerRecovery` and `resolveDirectOpenIDBearerConfig` on the config it receives, while the merge sat in `resolveRuntimeConfig`, a leaf helper below those calls. An `Authorization` template declared in `requestHeaders` therefore never entered direct-bearer mode: a `tools/list` 401 skipped the force-refresh and the connection was returned with a stale bearer. Normalize at the birth of that pipeline's config instead, ahead of all four decisions, and make `getMCPAppToolsPublicationGeneration` normalize before hashing. Connection paths hold a merged config while cache paths hold the declared one, so without a canonical hash the two would address different catalog slices. * fix: Preserve MCP request header ownership across lifecycle boundaries * fix: Narrow remote header identity before rebuilding config * fix: Preserve request header precedence over catalog API keys * docs: Synchronize generated agent API schemas * fix: Ignore shadowed generated MCP user key requirements --------- Co-authored-by: Lia Co-authored-by: Danny Avila --- librechat.example.yaml | 5 + packages/api/src/mcp/MCPConnectionFactory.ts | 47 +- packages/api/src/mcp/MCPManager.ts | 32 +- packages/api/src/mcp/UserConnectionManager.ts | 41 +- .../__tests__/ConnectionsRepository.test.ts | 27 ++ .../__tests__/MCPConnectionFactory.test.ts | 74 ++++ .../api/src/mcp/__tests__/MCPManager.test.ts | 402 ++++++++++++------ .../mcp/__tests__/scope.integration.test.ts | 267 ++++++++++++ packages/api/src/mcp/__tests__/utils.test.ts | 293 +++++++++++++ packages/api/src/mcp/catalog/recovery.spec.ts | 32 ++ packages/api/src/mcp/headers.ts | 38 ++ packages/api/src/mcp/openid.ts | 9 +- .../src/mcp/registry/MCPServerInspector.ts | 15 +- .../src/mcp/registry/MCPServersRegistry.ts | 1 + .../__tests__/MCPServerInspector.test.ts | 45 ++ .../__tests__/ensureConfigServers.test.ts | 21 + .../src/mcp/registry/db/ServerConfigsDB.ts | 28 +- packages/api/src/mcp/toolsChanged.spec.ts | 69 +++ packages/api/src/mcp/toolsChanged.ts | 11 +- packages/api/src/mcp/utils.ts | 133 +++++- packages/api/src/schedules/mcp.spec.ts | 15 + packages/api/src/utils/env.spec.ts | 72 ++++ packages/api/src/utils/env.ts | 36 +- packages/data-provider/specs/mcp.spec.ts | 42 ++ packages/data-provider/src/mcp.ts | 14 + 25 files changed, 1547 insertions(+), 222 deletions(-) create mode 100644 packages/api/src/mcp/headers.ts 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 { - 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 => { 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 => { 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 { 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 { - 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; + requestHeaders?: Record; + }; + 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 { + 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[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((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); - - await expect( - manager.callTool({ - user, - serverName, - toolName: 'mutating_tool', - provider: 'openai', - flowManager: {} as Parameters[0]['flowManager'], - upstreamTokenProvider, - }), - ).rejects.toMatchObject({ - code: 'MCP_AUTHENTICATION_REJECTED', - connectionRefreshed: true, - } satisfies Partial); - - 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' }, + 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' }); + + (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); + + await expect( + manager.callTool({ + user, + serverName, + toolName: 'mutating_tool', + provider: 'openai', + flowManager: {} as Parameters[0]['flowManager'], + upstreamTokenProvider, + }), + ).rejects.toMatchObject({ + code: 'MCP_AUTHENTICATION_REJECTED', + connectionRefreshed: true, + } satisfies Partial); + + 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[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); - - 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' }), + 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', + }, }), - }), - expect.any(Object), - ); - }); + [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); + + 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); + + 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[]; } function trackSockets(httpServer: http.Server): () => Promise { @@ -74,6 +75,7 @@ async function createRequestScopedTestServer(): Promise const sessions = new Map(); const runIds: string[] = []; const parentMessageIds: string[] = []; + const postHeaders: Record[] = []; let created = 0; let deletes = 0; let toolCalls = 0; @@ -85,6 +87,14 @@ async function createRequestScopedTestServer(): Promise } 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 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(); + + /** + * `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; + value: string; + }) { + return manager.callTool({ + user, + serverName, + serverConfig: createRequestHeadersConfig(server.url), + toolName: 'echo', + provider: 'openai', + toolArguments: { value }, + requestBody, + requestScopedConnections, + flowManager, + }); + } + + function conversationIdsSeen(): Set { + 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 }).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 }; + + 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 }; + + /** 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 }).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> | 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, +): 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 { - 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 }).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; + requestHeaders?: Record; +} { + const carrier = config as ParsedServerConfig & { + headers?: Record; + requestHeaders?: Record; + }; + 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 }).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 }).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> | 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; headers?: Record; + /** Operator-configured headers sent only on chat-time connections. */ + requestHeaders?: Record; oauth?: PlaceholderValue; oauth_headers?: Record; url?: string; }; +function mergeHeaderMaps( + headers: Record | undefined, + requestHeaders: Record, +): Record { + const overridden = new Set(Object.keys(requestHeaders).map((name) => name.toLowerCase())); + const merged: Record = {}; + 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, -): 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(config: T): T { + const carrier = config as T & { + headers?: Record; + requestHeaders?: Record; + }; + 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(config: T): T { + const carrier = config as T & { requestHeaders?: Record }; + if (carrier.requestHeaders == null) { + return config; + } + const catalogConfig = { ...carrier }; + delete catalogConfig.requestHeaders; + return catalogConfig; +} + export function getRuntimeBodyPlaceholderFields( config: UserScopedConnectionConfig, ): Array { @@ -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, + config: UserScopedConnectionConfig, providedVars?: Record | 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 { 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 }).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 }; + 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 }; - 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