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