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

* 📪 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 <lia@librechat.ai>
Co-authored-by: Danny Avila <danny@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-16 15:16:40 -04:00 • committed by GitHub
parent 96eae2b5c1
commit a26a6709ff
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
25 changed files with 1547 additions and 222 deletions

View file

@ -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

View file

@ -31,6 +31,14 @@ import {
ReauthenticationRequiredError,
resolveOboToken,
} from '~/mcp/oauth';
import {
isOAuthServer,
waitUntilDeadline,
applyRequestHeaders,
isClientRejectionMessage,
createDeadlineAbortSignal,
toCatalogConnectionConfig,
} from './utils';
import {
isDirectOpenIDBearerRecoveryEnabled,
resolveDirectOpenIDBearerConfig,
@ -41,12 +49,6 @@ import {
isMCPTransportAuthenticationError,
MCPAuthenticationRejectedError,
} from './errors';
import {
isOAuthServer,
waitUntilDeadline,
isClientRejectionMessage,
createDeadlineAbortSignal,
} from './utils';
import { PENDING_STALE_MS, FlowStateNotFoundError, normalizeExpiresAt } from '~/flow/manager';
import { createLazyOboUpstreamTokenProvider, awaitOboOperation } from '~/mcp/oauth/obo';
import { preProcessGraphTokens } from '~/utils/graph';
@ -153,11 +155,20 @@ export class MCPConnectionFactory {
basic: t.BasicConnectionOptions,
oauth?: t.OAuthConnectionOptions | t.UserConnectionContext,
): Promise<MCPConnection> {
const directBearerRecoveryState = basic.directBearerRecoveryState ?? { attempted: false };
/** Chat-time entry point: the operator's `requestHeaders` join `headers`
* here, ahead of direct-bearer detection and Graph preprocessing, so an
* `Authorization` or `{{LIBRECHAT_GRAPH_*}}` template declared there gets
* exactly the handling it would get in `headers`. */
const runtime: t.BasicConnectionOptions = {
...basic,
serverConfig: applyRequestHeaders(basic.serverConfig),
serverDefinition: basic.serverDefinition ?? basic.serverConfig,
};
const directBearerRecoveryState = runtime.directBearerRecoveryState ?? { attempted: false };
const directBearerSourceConfig =
basic.directBearerSourceConfig ??
(isDirectOpenIDBearerRecoveryEnabled(basic.serverConfig)
? (basic.serverConfig as t.ParsedServerConfig)
runtime.directBearerSourceConfig ??
(isDirectOpenIDBearerRecoveryEnabled(runtime.serverConfig)
? (runtime.serverConfig as t.ParsedServerConfig)
: undefined);
const create = async (candidate: t.BasicConnectionOptions): Promise<MCPConnection> => {
const prepared = await this.prepareBasicConnectionOptions(
@ -171,11 +182,11 @@ export class MCPConnectionFactory {
return factory.createConnection();
};
if (!directBearerSourceConfig) {
return create(basic);
return create(runtime);
}
try {
return await create(basic);
return await create(runtime);
} catch (error) {
if (!isMCPTransportAuthenticationError(error) || this.isRequestCancelled(oauth)) {
throw error;
@ -192,7 +203,7 @@ export class MCPConnectionFactory {
});
directBearerRecoveryState.resolvedConfig = refreshedConfig;
try {
return await create({ ...basic, serverConfig: refreshedConfig });
return await create({ ...runtime, serverConfig: refreshedConfig });
} catch (refreshedError) {
if (isMCPTransportAuthenticationError(refreshedError)) {
throw new MCPAuthenticationRejectedError(basic.serverName, false, refreshedError);
@ -233,7 +244,15 @@ export class MCPConnectionFactory {
: undefined);
const discover = async (candidate: t.BasicConnectionOptions): Promise<ToolDiscoveryResult> => {
const prepared = await this.prepareBasicConnectionOptions(
{ ...candidate, directBearerSourceConfig },
{
...candidate,
/** Applied to every discovery attempt, not just the first: a config
* refreshed for direct-bearer recovery comes from the untouched
* definition and would otherwise carry the chat-only map back in. */
serverConfig: toCatalogConnectionConfig(candidate.serverConfig),
serverDefinition: basic.serverDefinition ?? basic.serverConfig,
directBearerSourceConfig,
},
options,
);
if (options != null && 'useOAuth' in options) {

View file

@ -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,

View file

@ -2,6 +2,8 @@ import { logger } from '@librechat/data-schemas';
import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
import type * as t from './types';
import {
applyRequestHeaders,
canUseAppConnection,
canBackfillSharedServerInstructions,
getMissingRuntimeBodyPlaceholderFields,
hasRuntimeUrlPlaceholders,
@ -602,16 +604,21 @@ export abstract class UserConnectionManager {
): Promise<MCPConnection> {
signal?.throwIfAborted();
this.assertCreationNotCancelled(creationGuard, userId, serverName);
if (await this.appConnections!.has(serverName)) {
const declaredConfig =
providedConfig ??
(await MCPServersRegistry.getInstance().getServerConfig(serverName, userId));
if (
(!declaredConfig || canUseAppConnection(declaredConfig)) &&
(await this.appConnections!.has(serverName))
) {
throw new McpError(
ErrorCode.InvalidRequest,
`[MCP][User: ${userId}] Trying to create user-specific connection for app-level server "${serverName}"`,
);
}
const config =
providedConfig ??
(await MCPServersRegistry.getInstance().getServerConfig(serverName, userId));
/** Resolution uses effective headers; identity and persistence keep the declaration. */
const config = declaredConfig && applyRequestHeaders(declaredConfig);
/** Capture before resolving credentials/creating the connection. If another replica rotates
* the generation while creation is in flight, this connection's publications are fenced. */
@ -641,7 +648,9 @@ export abstract class UserConnectionManager {
const existingPublicationGeneration = connection
? this.toolPublicationGenerations.get(connection)
: undefined;
const configGeneration = config ? getMCPAppToolsPublicationGeneration(config) : undefined;
const configGeneration = declaredConfig
? getMCPAppToolsPublicationGeneration(declaredConfig)
: undefined;
const existingConfigGeneration = connection
? this.toolConfigGenerations.get(connection)
: undefined;
@ -739,7 +748,7 @@ export abstract class UserConnectionManager {
}
// Now check if config exists for new connection creation
if (!config) {
if (!config || !declaredConfig) {
throw new McpError(
ErrorCode.InvalidRequest,
`[MCP][User: ${userId}] Configuration for server "${serverName}" not found.`,
@ -786,7 +795,7 @@ export abstract class UserConnectionManager {
serverConfig: runtimeConfig,
/** Runtime OAuth detection enriches the connection config. Keep the durable definition
* separate so callback liveness compares against the config that actually owns it. */
serverDefinition: config,
serverDefinition: declaredConfig,
...(usesDirectOpenIDBearerRecovery(config) && { directBearerSourceConfig: config }),
directBearerRecoveryState,
serverName: serverName,
@ -903,7 +912,7 @@ export abstract class UserConnectionManager {
tools,
userId,
serverName,
serverConfig: config,
serverConfig: declaredConfig,
...(effectiveGeneration && { publicationGeneration: effectiveGeneration }),
...(publicationRevision && { publicationRevision }),
});
@ -958,7 +967,7 @@ export abstract class UserConnectionManager {
connectionTimeout,
graphTokenResolver,
ephemeralConnection,
serverConfig: config,
serverConfig: declaredConfig,
directBearerRecoveryState,
directBearerResolvedConfig: refreshedConfig,
},
@ -978,7 +987,7 @@ export abstract class UserConnectionManager {
}
logger.info(`[MCP][User: ${userId}][${serverName}] Connection successfully established`);
await this.backfillResolvedInstructions(serverName, config, connection, userId);
await this.backfillResolvedInstructions(serverName, declaredConfig, connection, userId);
signal?.throwIfAborted();
if (!ephemeralConnection) {
await this.updateUserLastActivity(userId);
@ -1079,12 +1088,16 @@ export abstract class UserConnectionManager {
requestBody?: t.UserMCPConnectionOptions['requestBody'];
graphTokenResolver?: t.UserMCPConnectionOptions['graphTokenResolver'];
}): Promise<t.ParsedServerConfig> {
const dbSourced = isUserSourced(config);
/** Mirrors the factory's entry-point normalization; without it this
* validation pass would inspect a different header map than the one the
* connection ends up sending. */
const runtimeConfig = applyRequestHeaders(config);
const dbSourced = isUserSourced(runtimeConfig);
/** Plugin-authored placeholders must never resolve against the user's Graph token. */
const graphProcessedConfig =
dbSourced || isPluginSourced(config)
? config
: await preProcessGraphTokens(config, {
dbSourced || isPluginSourced(runtimeConfig)
? runtimeConfig
: await preProcessGraphTokens(runtimeConfig, {
user,
graphTokenResolver,
scopes: process.env.GRAPH_API_SCOPES,

View file

@ -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'),

View file

@ -12,6 +12,7 @@ import {
import { PENDING_STALE_MS, FlowStateNotFoundError } from '~/flow/manager';
import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';
import { MCPAuthenticationRejectedError } from '~/mcp/errors';
import { getMCPServerGeneration } from '~/mcp/oauth/cleanup';
import { preProcessGraphTokens } from '~/utils/graph';
import { MCPConnection } from '~/mcp/connection';
import { processMCPEnv } from '~/utils';
@ -396,6 +397,42 @@ describe('MCPConnectionFactory', () => {
expect(mockConnectionInstance.connect).toHaveBeenCalled();
});
it('should merge requestHeaders before Graph pre-processing, overriding by case', async () => {
const graphTokenResolver = jest.fn();
const serverConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'yaml',
apiKey: { source: 'admin', authorization_type: 'bearer', key: 'catalog-key' },
headers: { 'X-Workspace': 'workspace-1', Authorization: 'Bearer stale' },
requestHeaders: { authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}' },
} as t.MCPOptions;
mockPreProcessGraphTokens.mockImplementation(async (config) => config as t.MCPOptions);
mockProcessMCPEnv.mockImplementation(
({ options }: { options: t.MCPOptions }) => options as t.MCPOptions,
);
mockConnectionInstance.isConnected.mockResolvedValue(true);
await MCPConnectionFactory.create(
{ serverName: 'test-server', serverConfig },
{ user: mockUser, graphTokenResolver },
);
/** The preprocessor only inspects `headers`, so the chat-only map has to be
* folded in before it runs — and the base `Authorization` must be gone,
* since keeping both spellings would let Undici join the two values. */
const preprocessed = mockPreProcessGraphTokens.mock.calls[0][0] as {
headers?: Record<string, string>;
requestHeaders?: Record<string, string>;
};
expect(preprocessed.headers).toEqual({
'X-Workspace': 'workspace-1',
authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
});
expect(preprocessed).not.toHaveProperty('requestHeaders');
});
it('should pre-process Graph placeholders before connection config resolution', async () => {
const graphTokenResolver = jest.fn();
const serverConfig: t.MCPOptions = {
@ -4288,6 +4325,43 @@ describe('MCPConnectionFactory', () => {
});
});
describe('declared identity across connection transformations', () => {
it.each(['create', 'discoverTools'] as const)(
'%s retains the callback identity while transforming only wire headers',
async (entry) => {
const declared: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
headers: { 'X-Workspace': 'catalog' },
requestHeaders: { 'X-Workspace': 'chat' },
};
let definition: t.MCPOptions | undefined;
let wireConfig: t.MCPOptions | undefined;
class IdentityFactory extends MCPConnectionFactory {
protected async createConnection(): Promise<MCPConnection> {
definition = this.serverDefinition;
wireConfig = this.serverConfig;
return mockConnectionInstance;
}
protected async discoverToolsInternal() {
await this.createConnection();
return { tools: [], connection: null, oauthRequired: false, oauthUrl: null };
}
}
mockProcessMCPEnv.mockImplementation(({ options }) => options);
await IdentityFactory[entry]({ serverName: 'identity', serverConfig: declared });
expect(definition).toBe(declared);
expect(getMCPServerGeneration(definition!)).toBe(getMCPServerGeneration(declared));
expect(wireConfig).not.toHaveProperty('requestHeaders');
expect(wireConfig).toMatchObject({
headers: { 'X-Workspace': entry === 'create' ? 'chat' : 'catalog' },
});
},
);
});
describe('discoverTools static method', () => {
const mockTools = [
{ name: 'tool1', description: 'First tool', inputSchema: { type: 'object' } },

View file

@ -2343,6 +2343,61 @@ describe('MCPManager', () => {
);
});
it('detects direct-bearer mode when the Authorization template lives in requestHeaders', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [] }),
on: jest.fn(),
} as unknown as MCPConnection;
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'live-token' });
await manager.getUserConnection({
serverName,
user: { id: 'direct-user', provider: 'openid', openidId: 'direct-subject' } as IUser,
serverConfig: {
...serverConfig,
source: 'yaml',
requestHeaders: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
} as t.ParsedServerConfig,
flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
upstreamTokenProvider,
});
/** The manager's own bearer decisions read the config directly, so the map
* has to be folded in before them or a 401 never reaches recovery. */
expect(upstreamTokenProvider).toHaveBeenCalled();
const createCalls = (MCPConnectionFactory.create as jest.Mock).mock.calls;
const [basic] = createCalls[createCalls.length - 1];
expect(basic.directBearerSourceConfig).toBeDefined();
expect(basic.serverConfig.headers).toEqual({ Authorization: 'Bearer live-token' });
expect(basic.serverConfig).not.toHaveProperty('requestHeaders');
expect(basic.serverDefinition.requestHeaders).toEqual({
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
});
const published = jest.fn();
toolsChanged.setMCPToolsChangedHandler(published);
try {
const listener = (connection.on as jest.Mock).mock.calls.find(
([event]) => event === 'toolsChanged',
)?.[1];
listener([]);
await new Promise<void>((resolve) => setImmediate(resolve));
expect(published).toHaveBeenCalledWith(
expect.objectContaining({
serverConfig: basic.serverDefinition,
}),
);
} finally {
toolsChanged.setMCPToolsChangedHandler(null);
}
});
it('waits for an active recovery before reusing a cached connection', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
@ -3253,63 +3308,80 @@ describe('MCPManager', () => {
openidId: 'direct-subject',
} as IUser;
it('refreshes and replaces the connection without replaying a rejected tool call', async () => {
const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(rejection) },
} as unknown as MCPConnection;
const replacement = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'current-token' })
.mockResolvedValueOnce({ access_token: 'refreshed-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnection = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValueOnce(connection)
.mockResolvedValueOnce(replacement);
await expect(
manager.callTool({
user,
serverName,
toolName: 'mutating_tool',
provider: 'openai',
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: true,
} satisfies Partial<MCPAuthenticationRejectedError>);
expect(connection.client.request).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).toHaveBeenNthCalledWith(2, {
forceRefresh: true,
signal: expect.any(AbortSignal),
});
expect(connection.stopReconnecting).toHaveBeenCalled();
expect(getUserConnection).toHaveBeenLastCalledWith(
expect.objectContaining({
forceNew: true,
serverConfig,
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<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: true,
} satisfies Partial<MCPAuthenticationRejectedError>);
expect(connection.client.request).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).toHaveBeenNthCalledWith(2, {
forceRefresh: true,
signal: expect.any(AbortSignal),
});
expect(connection.stopReconnecting).toHaveBeenCalled();
expect(getUserConnection).toHaveBeenLastCalledWith(
expect.objectContaining({
forceNew: true,
serverConfig: declared,
directBearerRecoveryState: expect.objectContaining({ attempted: true }),
directBearerResolvedConfig: expect.objectContaining({
headers: { Authorization: 'Bearer refreshed-token' },
}),
}),
);
},
);
it('preserves a JSON-RPC tool failure that mentions downstream authentication', async () => {
const toolError = new McpError(ErrorCode.InternalError, 'downstream HTTP 401 invalid_token');
@ -3988,6 +4060,43 @@ describe('MCPManager', () => {
expect(getUserConnectionSpy).not.toHaveBeenCalled();
});
it('keeps a static request-header overlay off its same-named shared app connection', async () => {
const appConnections = {
get: jest.fn(),
has: jest.fn().mockResolvedValue(true),
};
mockAppConnections(appConnections);
const candidate = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),
on: jest.fn(),
} as unknown as MCPConnection;
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(candidate);
const declared: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'yaml',
requestHeaders: { 'X-Workspace': 'chat-only' },
};
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getConnection({
serverName,
user: mockUser as IUser,
serverConfig: declared,
}),
).resolves.toBe(candidate);
expect(appConnections.get).not.toHaveBeenCalled();
expect(appConnections.has).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({
serverDefinition: declared,
serverConfig: expect.objectContaining({ headers: { 'X-Workspace': 'chat-only' } }),
}),
expect.any(Object),
);
});
it('should use user-scoped connections for trusted runtime context placeholders', async () => {
const appConnection = {
isConnected: jest.fn().mockResolvedValue(true),
@ -4051,6 +4160,32 @@ describe('MCPManager', () => {
(MCPConnectionFactory.discoverTools as jest.Mock) = jest.fn();
});
it('keeps the declared OAuth identity while stripping discovery headers', async () => {
const declared: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
requiresOAuth: true,
requestHeaders: { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
};
mockRegistryInstance.getServerConfig.mockResolvedValue(declared);
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({
serverName,
user: { id: 'oauth-user' } as IUser,
flowManager: {} as Parameters<typeof manager.discoverServerTools>[0]['flowManager'],
});
const [basic] = (MCPConnectionFactory.discoverTools as jest.Mock).mock.calls[0];
expect(basic.serverDefinition).toBe(declared);
expect(basic.serverConfig).not.toHaveProperty('requestHeaders');
});
it('should return tools from existing app connection when available', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
@ -4625,77 +4760,92 @@ describe('MCPManager', () => {
expect(mockConnection.refreshToolList).toHaveBeenCalledTimes(1);
});
it('recovers an ephemeral initial tools/list rejection once and fences the replacement', async () => {
const authenticationError = Object.assign(new Error('unauthorized'), { status: 401 });
const rejectedConnection = newUserConnection();
const replacementConnection = newUserConnection();
(rejectedConnection.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError,
});
(replacementConnection.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError,
});
const directBearerConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
headers: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
};
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'stale-token' })
.mockResolvedValueOnce({ access_token: 'fresh-token' })
.mockResolvedValueOnce({ access_token: 'fresh-token' });
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directBearerConfig);
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(rejectedConnection)
.mockResolvedValueOnce(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'conversation-1' },
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
} satisfies Partial<MCPAuthenticationRejectedError>);
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<MCPAuthenticationRejectedError>);
expect(rejectedConnection.dispose).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
expect.objectContaining({
ephemeralConnection: true,
directBearerRecoveryState: expect.objectContaining({ attempted: true }),
}),
expect.any(Object),
);
expect(upstreamTokenProvider.mock.calls).toEqual([
[{ forceRefresh: false }],
[{ forceRefresh: true }],
]);
expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
expect.objectContaining({
serverDefinition: directBearerConfig,
directBearerSourceConfig: expect.objectContaining({
headers: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
}),
serverConfig: expect.objectContaining({
headers: expect.objectContaining({ Authorization: 'Bearer fresh-token' }),
}),
}),
expect.any(Object),
);
},
);
it.each([false, true])(
'does not publish a cancelled initial catalog (request-scoped=%s)',

View file

@ -52,6 +52,7 @@ interface RequestScopedTestServer {
toolCallCount: () => number;
observedRunIds: () => string[];
observedParentMessageIds: () => string[];
observedHeaders: () => Record<string, string>[];
}
function trackSockets(httpServer: http.Server): () => Promise<void> {
@ -74,6 +75,7 @@ async function createRequestScopedTestServer(): Promise<RequestScopedTestServer>
const sessions = new Map<string, StreamableHTTPServerTransport>();
const runIds: string[] = [];
const parentMessageIds: string[] = [];
const postHeaders: Record<string, string>[] = [];
let created = 0;
let deletes = 0;
let toolCalls = 0;
@ -85,6 +87,14 @@ async function createRequestScopedTestServer(): Promise<RequestScopedTestServer>
}
if (req.method === 'POST') {
postHeaders.push(
Object.fromEntries(
Object.entries(req.headers).map(([key, value]) => [
key,
Array.isArray(value) ? value.join(',') : (value ?? ''),
]),
),
);
const runId = req.headers['x-run-id'];
if (typeof runId === 'string') {
runIds.push(runId);
@ -134,6 +144,7 @@ async function createRequestScopedTestServer(): Promise<RequestScopedTestServer>
toolCallCount: () => toolCalls,
observedRunIds: () => [...runIds],
observedParentMessageIds: () => [...parentMessageIds],
observedHeaders: () => postHeaders.map((headers) => ({ ...headers })),
close: async () => {
const closing = [...sessions.values()].map((transport) =>
transport.close().catch(() => undefined),
@ -317,3 +328,259 @@ describe('request-scoped MCP lifecycle integration', () => {
expect(new Set(server.observedRunIds())).toEqual(new Set(['recovery-run']));
});
});
describe('operator requestHeaders integration', () => {
const serverName = 'request-headers';
let server: RequestScopedTestServer;
let manager: MCPManager;
const contexts = new Set<MCPRequestContext>();
/**
* `X-Conversation-Id` is declared in BOTH maps so precedence is observable,
* and `X-Trace-Id` only in the chat-only map so its absence proves discovery
* never sent it.
*/
function createRequestHeadersConfig(url: string): ParsedServerConfig {
return {
type: 'streamable-http',
url,
source: 'yaml',
requiresOAuth: false,
initTimeout: 500,
headers: {
'X-Workspace': 'workspace-1',
'X-Conversation-Id': 'from-headers',
},
requestHeaders: {
'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}',
},
} as ParsedServerConfig;
}
beforeEach(async () => {
server = await createRequestScopedTestServer();
manager = createManager();
jest.spyOn(MCPServersRegistry, 'getInstance').mockReturnValue({
resolveAllowlists: jest.fn(async () => ({
allowedDomains: null,
allowedAddresses: null,
useSSRFProtection: false,
})),
getServerConfig: jest.fn(async () => createRequestHeadersConfig(server.url)),
isAppServerConfig: jest.fn(async () => false),
} as unknown as MCPServersRegistry);
});
afterEach(async () => {
await Promise.all([...contexts].map((context) => cleanupMCPRequestContext(context)));
contexts.clear();
MCPConnection.clearCooldown(serverName);
jest.restoreAllMocks();
await server.close();
});
function createContext(): MCPRequestContext {
const context = createMCPRequestContext();
contexts.add(context);
return context;
}
function callEchoWithBody({
requestScopedConnections,
requestBody,
value,
}: {
requestScopedConnections: RequestScopedMCPConnectionStore;
requestBody: Record<string, string>;
value: string;
}) {
return manager.callTool({
user,
serverName,
serverConfig: createRequestHeadersConfig(server.url),
toolName: 'echo',
provider: 'openai',
toolArguments: { value },
requestBody,
requestScopedConnections,
flowManager,
});
}
function conversationIdsSeen(): Set<string> {
return new Set(
server
.observedHeaders()
.map((headers) => headers['x-conversation-id'])
.filter((value): value is string => value != null),
);
}
it('populates the tool catalog and disposes the discovery connection', async () => {
const result = await manager.discoverServerTools({
serverName,
user,
configServers: { [serverName]: createRequestHeadersConfig(server.url) },
});
expect(result.tools?.map((tool) => tool.name)).toContain('echo');
expect(result.oauthRequired).toBe(false);
expect(server.deleteCount()).toBe(1);
expect(server.liveSessionCount()).toBe(0);
});
it('sends the regular headers but not the chat-only ones during discovery', async () => {
await manager.discoverServerTools({
serverName,
user,
configServers: { [serverName]: createRequestHeadersConfig(server.url) },
});
const observed = server.observedHeaders();
expect(observed.length).toBeGreaterThan(0);
for (const headers of observed) {
expect(headers['x-workspace']).toBe('workspace-1');
expect(headers['x-conversation-id']).toBe('from-headers');
expect(headers['x-trace-id']).toBeUndefined();
}
});
it('resolves and merges both maps at chat time, the request map winning', async () => {
await callEchoWithBody({
requestScopedConnections: createContext(),
requestBody: { conversationId: 'conv-1', messageId: 'msg-1' },
value: 'merged',
});
const observed = server.observedHeaders();
expect(observed.length).toBeGreaterThan(0);
for (const headers of observed) {
expect(headers['x-workspace']).toBe('workspace-1');
expect(headers['x-conversation-id']).toBe('conv-1');
expect(headers['x-trace-id']).toBe('msg-1');
}
});
it('isolates two request bodies in separate connections with distinct headers', async () => {
await callEchoWithBody({
requestScopedConnections: createContext(),
requestBody: { conversationId: 'conv-1', messageId: 'msg-1' },
value: 'first',
});
await callEchoWithBody({
requestScopedConnections: createContext(),
requestBody: { conversationId: 'conv-2', messageId: 'msg-2' },
value: 'second',
});
expect(server.sessionsCreated()).toBe(2);
expect(conversationIdsSeen()).toEqual(new Set(['conv-1', 'conv-2']));
expect(server.toolCallCount()).toBe(2);
});
it('admits a chat whose request override removes a catalog body requirement', async () => {
const config = createRequestHeadersConfig(server.url);
await manager.callTool({
user,
serverName,
toolName: 'echo',
provider: 'openai',
toolArguments: { value: 'shadowed' },
serverConfig: {
...config,
headers: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
requestHeaders: {
'x-conversation-id': 'fixed',
'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}',
},
} as ParsedServerConfig,
requestBody: { messageId: 'msg-1' },
requestScopedConnections: createContext(),
flowManager,
});
expect(server.toolCallCount()).toBe(1);
expect(conversationIdsSeen()).toEqual(new Set(['fixed']));
});
it.each([
{
mode: 'bearer' as const,
name: 'Authorization',
chatName: 'Authorization',
catalog: 'Bearer catalog-key',
},
{
mode: 'bearer' as const,
name: 'Authorization',
chatName: 'authorization',
catalog: 'Bearer catalog-key',
},
{
mode: 'basic' as const,
name: 'Authorization',
chatName: 'AUTHORIZATION',
catalog: 'Basic catalog-key',
},
{ mode: 'custom' as const, name: 'X-Api-Key', chatName: 'x-api-key', catalog: 'catalog-key' },
{
mode: 'custom' as const,
name: 'X-Custom-Key',
chatName: 'x-custom-key',
catalog: 'catalog-key',
},
])(
'uses the $mode catalog key only in discovery when chat overrides $chatName',
async ({ mode, name, chatName, catalog }) => {
const config: ParsedServerConfig = {
...createRequestHeadersConfig(server.url),
type: 'streamable-http',
url: server.url,
apiKey: {
source: 'admin',
authorization_type: mode,
key: 'catalog-key',
...(mode === 'custom' && name !== 'X-Api-Key' ? { custom_header: name } : {}),
},
requestHeaders: {
[chatName]: '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
};
jest.spyOn(MCPServersRegistry.getInstance(), 'getServerConfig').mockResolvedValue(config);
await manager.discoverServerTools({ serverName, user });
const discoveryHeaders = server.observedHeaders();
expect(discoveryHeaders.length).toBeGreaterThan(0);
expect(discoveryHeaders.every((headers) => headers[name.toLowerCase()] === catalog)).toBe(
true,
);
await manager.callTool({
user,
serverName,
serverConfig: config,
toolName: 'echo',
provider: 'openai',
toolArguments: { value: 'chat-credential' },
requestBody: { conversationId: 'chat-key' },
requestScopedConnections: createContext(),
flowManager,
});
const chatHeaders = server.observedHeaders().slice(discoveryHeaders.length);
expect(chatHeaders.length).toBeGreaterThan(0);
expect(chatHeaders.every((headers) => headers[name.toLowerCase()] === 'chat-key')).toBe(true);
expect(server.toolCallCount()).toBe(1);
},
);
it('fails closed when a runtime value the request headers need is missing', async () => {
await expect(
callEchoWithBody({
requestScopedConnections: createContext(),
requestBody: { conversationId: 'conv-1' },
value: 'no-message-id',
}),
).rejects.toThrow(/messageId/);
expect(server.sessionsCreated()).toBe(0);
expect(server.toolCallCount()).toBe(0);
});
});

View file

@ -8,12 +8,16 @@ import {
redactAllServerSecrets,
redactServerSecrets,
requiresUserScopedConnection,
canUseAppConnection,
canBackfillSharedServerInstructions,
isInvalidClientMessage,
isClientRejectionMessage,
getMissingCustomUserVars,
hasCustomUserVars,
hasRuntimeUrlPlaceholders,
getMCPRequestScope,
toCatalogConnectionConfig,
applyRequestHeaders,
hasRuntimeContextPlaceholders,
getRuntimeBodyPlaceholderFields,
getMissingRuntimeBodyPlaceholderFields,
@ -25,6 +29,7 @@ import {
filterChatSelectableMCPServers,
waitUntilDeadline,
} from '~/mcp/utils';
import { usesDirectOpenIDBearerRecovery } from '~/mcp/openid';
describe('normalizeServerName', () => {
it('should not modify server names that already match the pattern', () => {
@ -997,6 +1002,250 @@ describe('getMissingRuntimeBodyPlaceholderFields', () => {
});
});
describe('operator requestHeaders', () => {
const config = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
headers: { Authorization: 'Bearer static-token' },
requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
} as ParsedServerConfig;
it('leaves the catalog unscoped while the runtime stays request-scoped', () => {
expect(getMCPRequestScope(config)).toEqual({
requestScoped: true,
requiredBodyFields: ['conversationId'],
});
expect(requiresEphemeralUserConnection(config)).toBe(true);
const catalogConfig = toCatalogConnectionConfig(config);
expect(getMCPRequestScope(catalogConfig)).toEqual({
requestScoped: false,
requiredBodyFields: [],
});
expect(requiresEphemeralUserConnection(catalogConfig)).toBe(false);
expect(getMissingRuntimeBodyPlaceholderFields(catalogConfig)).toEqual([]);
});
it('still blocks the catalog for a body placeholder discovery itself sends', () => {
const urlScoped = toCatalogConnectionConfig({
...config,
url: 'https://mcp.example.com/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
} as ParsedServerConfig);
expect(getMCPRequestScope(urlScoped).requiredBodyFields).toEqual(['messageId']);
expect(getMissingRuntimeBodyPlaceholderFields(urlScoped)).toEqual(['messageId']);
});
it('fails closed when the runtime value the request headers need is absent', () => {
expect(getMissingRuntimeBodyPlaceholderFields(config, { messageId: 'msg-1' })).toEqual([
'conversationId',
]);
expect(getMissingRuntimeBodyPlaceholderFields(config, { conversationId: ' ' })).toEqual([
'conversationId',
]);
expect(getMissingRuntimeBodyPlaceholderFields(config, { conversationId: 'conv-1' })).toEqual(
[],
);
});
it('does not resolve requestHeaders placeholders for untrusted configs', () => {
for (const untrusted of [
{ ...config, source: 'user' as const, dbId: 'server-123' },
{ ...config, source: 'plugin' as const },
]) {
expect(getMCPRequestScope(untrusted).requestScoped).toBe(false);
expect(requiresEphemeralUserConnection(untrusted)).toBe(false);
expect(getMissingRuntimeBodyPlaceholderFields(untrusted)).toEqual([]);
}
});
it('keeps a server with chat-only headers off the shared app connection', () => {
const shareable = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
} as ParsedServerConfig;
expect(canUseAppConnection(shareable)).toBe(true);
/** Static values too: the shared connection's own handshake is catalog work. */
expect(
canUseAppConnection({
...shareable,
requestHeaders: { 'X-Workspace': 'workspace-1' },
} as ParsedServerConfig),
).toBe(false);
expect(canUseAppConnection(config)).toBe(false);
/** An empty map declares nothing, so it must not cost the server its sharing. */
expect(canUseAppConnection({ ...shareable, requestHeaders: {} } as ParsedServerConfig)).toBe(
true,
);
});
it('does not require body values from headers shadowed by the runtime map', () => {
const declared: ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
headers: { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
requestHeaders: { 'x-conversation': 'fixed' },
};
expect(getMissingRuntimeBodyPlaceholderFields(declared)).toEqual([]);
expect(hasRuntimeContextPlaceholders(declared)).toBe(false);
expect(getMissingRuntimeBodyPlaceholderFields(toCatalogConnectionConfig(declared))).toEqual([
'conversationId',
]);
});
it('keeps chat-only instructions out of the shared catalog, including static headers', () => {
const deferred: ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
startup: false,
};
expect(canBackfillSharedServerInstructions(deferred)).toBe(true);
expect(canBackfillSharedServerInstructions({ ...deferred, requestHeaders: {} })).toBe(true);
expect(
canBackfillSharedServerInstructions({
...deferred,
requestHeaders: { 'X-Workspace': 'chat' },
}),
).toBe(false);
});
it('drops a shadowed API-key body requirement while preserving discovery authentication', () => {
const declared: ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
apiKey: {
source: 'admin',
authorization_type: 'bearer',
key: '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
requestHeaders: { authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
};
const runtime = applyRequestHeaders(declared);
expect(getMissingRuntimeBodyPlaceholderFields(declared)).toEqual([]);
expect(usesDirectOpenIDBearerRecovery(runtime)).toBe(true);
expect(runtime.apiKey?.key).toBeUndefined();
expect(declared.apiKey?.key).toBe('{{LIBRECHAT_BODY_CONVERSATIONID}}');
expect(getMissingRuntimeBodyPlaceholderFields(toCatalogConnectionConfig(declared))).toEqual([
'conversationId',
]);
expect(applyRequestHeaders(runtime)).toBe(runtime);
const unshadowed = applyRequestHeaders({ ...declared, requestHeaders: { 'X-Trace': 'trace' } });
expect(unshadowed.apiKey).toBe(declared.apiKey);
});
it('never returns either header map to a client', () => {
const redacted = redactServerSecrets(config, { canEdit: true });
expect(redacted).not.toHaveProperty('requestHeaders');
expect(redacted).not.toHaveProperty('headers');
expect(redacted.requestScoped).toBe(true);
});
});
describe('toCatalogConnectionConfig', () => {
it('strips the chat-only map a discovery connection cannot resolve', () => {
const config = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
headers: { Authorization: 'Bearer static-token' },
requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
} as ParsedServerConfig;
const catalogConfig = toCatalogConnectionConfig(config);
expect(catalogConfig).not.toHaveProperty('requestHeaders');
expect((catalogConfig as { headers?: Record<string, string> }).headers).toEqual({
Authorization: 'Bearer static-token',
});
expect(config).toHaveProperty('requestHeaders');
});
it('returns the same reference when there is nothing to strip', () => {
const config = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
headers: { Authorization: 'Bearer static-token' },
} as ParsedServerConfig;
expect(toCatalogConnectionConfig(config)).toBe(config);
});
});
describe('applyRequestHeaders', () => {
it('merges the request map over headers', () => {
const merged = applyRequestHeaders({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
headers: { Authorization: 'Bearer static', 'X-Keep': 'kept' },
requestHeaders: { 'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}' },
} as ParsedServerConfig) as { headers?: Record<string, string> };
expect(merged.headers).toEqual({
Authorization: 'Bearer static',
'X-Keep': 'kept',
'X-Trace-Id': '{{LIBRECHAT_BODY_MESSAGEID}}',
});
expect(merged).not.toHaveProperty('requestHeaders');
});
it('overrides a duplicate name regardless of casing', () => {
const merged = applyRequestHeaders({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
headers: { Authorization: 'Bearer stale', 'X-Trace-Id': 'stale-trace' },
requestHeaders: { authorization: 'Bearer fresh', 'x-trace-id': 'fresh-trace' },
} as ParsedServerConfig) as { headers?: Record<string, string> };
/** Both spellings surviving would let Undici join them into `stale, fresh`. */
expect(merged.headers).toEqual({
authorization: 'Bearer fresh',
'x-trace-id': 'fresh-trace',
});
});
it('is idempotent, so a config reused across connections cannot merge twice', () => {
const config = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
headers: { 'X-Trace-Id': 'stale' },
requestHeaders: { 'X-Trace-Id': 'fresh' },
} as ParsedServerConfig;
const once = applyRequestHeaders(config);
const twice = applyRequestHeaders(once);
expect(twice).toBe(once);
expect((twice as { headers?: Record<string, string> }).headers).toEqual({
'X-Trace-Id': 'fresh',
});
});
it('returns the same reference when there is nothing to merge', () => {
const config = { type: 'stdio', command: 'node', args: ['server.js'] } as ParsedServerConfig;
expect(applyRequestHeaders(config)).toBe(config);
});
it('brings a request-header Authorization under direct-bearer recovery', () => {
const config = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
requiresOAuth: false,
requestHeaders: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
} as ParsedServerConfig;
expect(usesDirectOpenIDBearerRecovery(config)).toBe(false);
expect(usesDirectOpenIDBearerRecovery(applyRequestHeaders(config))).toBe(true);
});
});
describe('validateMCPServerConfig', () => {
it('preserves server-managed metadata on a valid effective config', () => {
const config = {
@ -1325,3 +1574,47 @@ describe('waitUntilDeadline', () => {
await new Promise((resolve) => setImmediate(resolve));
});
});
describe('shadowed generated user API keys', () => {
const config: ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.test/mcp',
apiKey: { source: 'user', authorization_type: 'bearer' },
headers: { Authorization: 'Bearer {{MCP_API_KEY}}' },
requestHeaders: { authorization: 'Bearer request-secret' },
customUserVars: { MCP_API_KEY: { title: 'API Key', description: 'Generated key' } },
};
it('removes only the unused generated requirement and preserves the declaration', () => {
expect(hasCustomUserVars(config)).toBe(false);
expect(getMissingCustomUserVars(config)).toEqual([]);
const effective = applyRequestHeaders(config);
expect(effective.customUserVars).toEqual({});
expect(getMissingCustomUserVars(effective)).toEqual([]);
expect(applyRequestHeaders(effective)).toBe(effective);
expect(getMissingCustomUserVars(toCatalogConnectionConfig(config))).toEqual(['MCP_API_KEY']);
expect(config.customUserVars).toHaveProperty('MCP_API_KEY');
});
it.each([
{ requestHeaders: { authorization: 'Bearer {{MCP_API_KEY}}' } },
{ headers: { Authorization: 'Bearer {{MCP_API_KEY}}', 'X-Key': '{{MCP_API_KEY}}' } },
{ url: 'https://mcp.example.test/{{MCP_API_KEY}}' },
{ oauth_headers: { 'X-Key': '{{MCP_API_KEY}}' } },
{ requestHeaders: { 'X-Unrelated': 'value' } },
])('retains a key referenced by the effective configuration: %j', (fields) => {
expect(getMissingCustomUserVars({ ...config, ...fields })).toEqual(['MCP_API_KEY']);
});
it('retains explicitly declared variables', () => {
const declared = {
...config,
customUserVars: {
...config.customUserVars,
REGION: { title: 'Region', description: 'Required region' },
},
};
expect(getMissingCustomUserVars(declared)).toEqual(['REGION']);
expect(hasCustomUserVars(declared)).toBe(true);
});
});

View file

@ -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);
});

View file

@ -0,0 +1,38 @@
import type { MCPOptions } from 'librechat-data-provider';
type ApiKeyConfig = Partial<NonNullable<MCPOptions['apiKey']>> | null | undefined;
function getApiKeyHeaderName(apiKey: ApiKeyConfig): string {
return apiKey?.authorization_type === 'custom'
? apiKey.custom_header || 'X-Api-Key'
: 'Authorization';
}
/** The header injected by an operator-provided API key, before placeholder resolution. */
export function getAdminApiKeyHeader(
apiKey: ApiKeyConfig,
): { name: string; value: string } | undefined {
if (apiKey?.source !== 'admin' || !apiKey.key) {
return;
}
const { key, authorization_type } = apiKey;
const name = getApiKeyHeaderName(apiKey);
const prefixes = { basic: 'Basic ', bearer: 'Bearer ', custom: '' };
const prefix = prefixes[authorization_type ?? 'custom'];
return { name, value: `${prefix}${key}` };
}
/** A shadowed catalog credential must not be injected or required by a chat connection. */
export function isApiKeyHeaderOverridden(
apiKey: ApiKeyConfig,
requestHeaders?: Record<string, string | undefined>,
): boolean {
const injected = apiKey?.source === 'user' || getAdminApiKeyHeader(apiKey) != null;
return (
injected &&
requestHeaders != null &&
Object.keys(requestHeaders).some(
(name) => name.toLowerCase() === getApiKeyHeaderName(apiKey).toLowerCase(),
)
);
}

View file

@ -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(

View file

@ -5,8 +5,10 @@ import type { MCPConnection } from '~/mcp/connection';
import type * as t from '~/mcp/types';
import {
hasCustomUserVars,
applyRequestHeaders,
hasRuntimeContextPlaceholders,
hasRuntimeUrlPlaceholders,
toCatalogConnectionConfig,
isUserSourced,
} from '~/mcp/utils';
import { isMCPDomainAllowed, extractMCPServerDomain } from '~/auth/domain';
@ -74,6 +76,12 @@ export class MCPServerInspector {
this.warnOnUnrestrictedRuntimeUrl();
await this.detectOAuth();
/** Startup inspection is catalog work with no chat request, so the chat-only
* headers come off before BOTH the eligibility gate and the probe. Left on,
* a `{{LIBRECHAT_BODY_*}}` placeholder there fails
* `hasRuntimeContextPlaceholders` and skips inspection altogether — the
* very outcome `requestHeaders` exists to avoid. */
const catalogConfig = toCatalogConnectionConfig(this.config);
if (
this.config.startup !== false &&
!this.config.requiresOAuth &&
@ -81,14 +89,15 @@ export class MCPServerInspector {
// user-provided API key is supplied per-user at connect time; an unauthenticated
// probe here would 401 against a bearer server and fail inspection
this.config.apiKey?.source !== 'user' &&
!hasRuntimeContextPlaceholders(this.config) &&
!hasRuntimeContextPlaceholders(catalogConfig) &&
!this.config.obo
) {
let tempConnection = false;
if (!this.connection) {
tempConnection = true;
this.connection = await MCPConnectionFactory.create({
serverConfig: this.config,
serverConfig: catalogConfig,
serverDefinition: this.config,
serverName: this.serverName,
dbSourced: isUserSourced(this.config),
useSSRFProtection: this.useSSRFProtection,
@ -124,7 +133,7 @@ export class MCPServerInspector {
}
private async detectOAuth(): Promise<void> {
if (isDirectOpenIDBearerRecoveryEnabled(this.config)) {
if (isDirectOpenIDBearerRecoveryEnabled(applyRequestHeaders(this.config))) {
this.config.requiresOAuth = false;
this.config.oauthMetadata = null;
return;

View file

@ -106,6 +106,7 @@ const ADMIN_CONFIGURABLE_FIELDS = [
'stderr',
'url',
'headers',
'requestHeaders',
'proxy',
'requiresOAuth',
'apiKey',

View file

@ -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',

View file

@ -171,6 +171,27 @@ describe('MCPServersRegistry — ensureConfigServers', () => {
expect(inspectSpy).toHaveBeenCalledTimes(1);
});
it('should lazy-init YAML server when admin overrides only the requestHeaders field', async () => {
await registry.addServer('yaml_remote', sseConfig, 'CACHE');
inspectSpy.mockClear();
const overrideConfig: t.MCPOptions = {
...sseConfig,
requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
};
const result = await registry.ensureConfigServers({
yaml_remote: overrideConfig,
});
expect(result).toHaveProperty('yaml_remote');
expect(
(result.yaml_remote as { requestHeaders?: Record<string, string> }).requestHeaders,
).toEqual({
'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
});
expect(inspectSpy).toHaveBeenCalledTimes(1);
});
it('should lazy-init YAML server when admin overrides only the OBO field', async () => {
await registry.addServer('yaml_remote', sseConfig, 'CACHE');
inspectSpy.mockClear();

View file

@ -58,6 +58,26 @@ function sanitizeCredentialPlaceholders(
return sanitized;
}
/**
* Sanitizes every header map a shared config carries. `requestHeaders` is
* included because it reaches the upstream server exactly like `headers` does:
* left unsanitized, a user-managed config could name a privileged placeholder
* there and have the runtime resolve it at chat time.
*/
function sanitizeConfigHeaderMaps(config: ParsedServerConfig): {
headers?: Record<string, string>;
requestHeaders?: Record<string, string>;
} {
const carrier = config as ParsedServerConfig & {
headers?: Record<string, string>;
requestHeaders?: Record<string, string>;
};
return {
headers: sanitizeCredentialPlaceholders(carrier.headers),
requestHeaders: sanitizeCredentialPlaceholders(carrier.requestHeaders),
};
}
function stripBlockedOAuthEndpointParams(url?: string): string | undefined {
if (!url) {
return url;
@ -297,9 +317,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
const sanitizedConfig = sanitizeUserManagedOAuthConfig({
...config,
headers: sanitizeCredentialPlaceholders(
(config as ParsedServerConfig & { headers?: Record<string, string> }).headers,
),
...sanitizeConfigHeaderMaps(config),
} as ParsedServerConfig);
/** Transformed user-provided API key config (adds customUserVars and headers) */
@ -346,9 +364,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
let configToSave: ParsedServerConfig = sanitizeUserManagedOAuthConfig({
...config,
headers: sanitizeCredentialPlaceholders(
(config as ParsedServerConfig & { headers?: Record<string, string> }).headers,
),
...sanitizeConfigHeaderMaps(config),
} as ParsedServerConfig);
/** Transformed user-provided API key config (adds customUserVars and headers) */

View file

@ -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];

View file

@ -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)))

View file

@ -7,11 +7,12 @@ import {
normalizeMCPToolKey,
buildServerNameAliases,
} from 'librechat-data-provider';
import type { AgentToolOptions } from 'librechat-data-provider';
import type { AgentToolOptions, MCPOptions } from 'librechat-data-provider';
import type { ParsedServerConfig } from '~/mcp/types';
import type { RequestBody } from '~/types';
import { isDirectOpenIDBearerRecoveryEnabled } from '~/mcp/openid';
import { ALLOWED_BODY_FIELDS, isPluginSourced } from '~/utils/env';
import { isApiKeyHeaderOverridden } from './headers';
import { isEnabled } from '~/utils/common';
export const mcpToolPattern: RegExp = new RegExp(`^.+${Constants.mcp_delimiter}.+$`);
@ -216,7 +217,7 @@ type UserScopedConnectionConfig = Pick<
> & {
/** Loosened like the fields below: raw (pre-inspection) configs carry
* optional API-key fields, and the gating predicates only inspect them. */
apiKey?: { key?: string; source?: 'user' | 'admin' } | null;
apiKey?: Partial<NonNullable<ParsedServerConfig['apiKey']>> | null;
args?: string[];
/** Loosened from the parsed shapes so raw (pre-inspection) configs qualify;
* scoping predicates only check key presence */
@ -227,17 +228,35 @@ type UserScopedConnectionConfig = Pick<
>;
env?: Record<string, string | undefined>;
headers?: Record<string, string | undefined>;
/** Operator-configured headers sent only on chat-time connections. */
requestHeaders?: Record<string, string | undefined>;
oauth?: PlaceholderValue;
oauth_headers?: Record<string, string | undefined>;
url?: string;
};
function mergeHeaderMaps<T extends string | undefined>(
headers: Record<string, T> | undefined,
requestHeaders: Record<string, T>,
): Record<string, T> {
const overridden = new Set(Object.keys(requestHeaders).map((name) => name.toLowerCase()));
const merged: Record<string, T> = {};
for (const [name, value] of Object.entries(headers ?? {})) {
if (!overridden.has(name.toLowerCase())) {
merged[name] = value;
}
}
return { ...merged, ...requestHeaders };
}
function placeholderBearingFields(config: UserScopedConnectionConfig): PlaceholderValue[] {
return [
config.apiKey?.key,
isApiKeyHeaderOverridden(config.apiKey, config.requestHeaders) ? undefined : config.apiKey?.key,
config.args,
config.env,
config.headers,
config.requestHeaders == null
? config.headers
: mergeHeaderMaps(config.headers, config.requestHeaders),
config.oauth,
config.oauth_headers,
config.url,
@ -272,11 +291,22 @@ export function requiresOAuthMachinery(config: ParsedServerConfig): boolean {
return isOAuthServer(config) || config.obo != null;
}
/** Checks that `customUserVars` is present AND non-empty (guards against truthy `{}`) */
export function hasCustomUserVars(
config: Pick<UserScopedConnectionConfig, 'customUserVars'>,
): boolean {
return !!config.customUserVars && Object.keys(config.customUserVars).length > 0;
/** Required chat credentials, retaining explicit variables and any still-used generated key. */
function requiredCustomUserVars(config: UserScopedConnectionConfig): string[] {
const keys = Object.keys(config.customUserVars ?? {});
if (
config.apiKey?.source !== 'user' ||
!isApiKeyHeaderOverridden(config.apiKey, config.requestHeaders) ||
placeholderBearingFields(config).some((value) => hasPlaceholder(value, /\{\{MCP_API_KEY\}\}/))
) {
return keys;
}
return keys.filter((key) => key !== 'MCP_API_KEY');
}
/** Checks the effective chat requirements, without weakening catalog-only credentials. */
export function hasCustomUserVars(config: UserScopedConnectionConfig): boolean {
return requiredCustomUserVars(config).length > 0;
}
function hasRuntimeContextPlaceholder(value: PlaceholderValue): boolean {
@ -374,6 +404,65 @@ export function getMCPRequestScope(config: UserScopedConnectionConfig): MCPReque
return { requestScoped: fields.length > 0, requiredBodyFields: fields };
}
/**
* Folds the operator's chat-only `requestHeaders` into `headers`, so everything
* downstream — direct-bearer detection, Graph preprocessing, `processMCPEnv`,
* the transports — keeps reading ONE header map and never has to learn about a
* second one. Called at the entry of each resolution pipeline, before any
* consumer inspects the config.
*
* HTTP header names are case-insensitive, so a base `Authorization` is dropped
* when the request map declares `authorization`: keeping both would let Undici
* join the values (`old, new`) instead of letting `requestHeaders` win.
*
* The field is consumed as it merges, making this idempotent for a config that
* passes through twice (checkout joiners, direct-bearer recovery).
*/
export function applyRequestHeaders<T extends MCPOptions>(config: T): T {
const carrier = config as T & {
headers?: Record<string, string>;
requestHeaders?: Record<string, string>;
};
if (carrier.requestHeaders == null) {
return config;
}
const merged = {
...carrier,
headers: mergeHeaderMaps(carrier.headers, carrier.requestHeaders),
};
if (carrier.apiKey && isApiKeyHeaderOverridden(carrier.apiKey, carrier.requestHeaders)) {
/** Keep the explicit auth mode, but disarm its lower-priority header injection. */
merged.apiKey = { ...carrier.apiKey, key: undefined };
}
if (carrier.customUserVars) {
const required = new Set(requiredCustomUserVars(carrier));
merged.customUserVars = Object.fromEntries(
Object.entries(carrier.customUserVars).filter(([key]) => required.has(key)),
);
}
delete merged.requestHeaders;
return merged;
}
/**
* Strips the operator's chat-only `requestHeaders` for a catalog (discovery)
* connection. Discovery has no conversation or message to resolve a
* `{{LIBRECHAT_BODY_*}}` placeholder against, so sending the map at all would
* either leak a literal placeholder upstream or resolve it to an empty value.
*
* Returns the same reference when there is nothing to strip.
*/
export function toCatalogConnectionConfig<T extends MCPOptions>(config: T): T {
const carrier = config as T & { requestHeaders?: Record<string, string> };
if (carrier.requestHeaders == null) {
return config;
}
const catalogConfig = { ...carrier };
delete catalogConfig.requestHeaders;
return catalogConfig;
}
export function getRuntimeBodyPlaceholderFields(
config: UserScopedConnectionConfig,
): Array<keyof RequestBody> {
@ -511,10 +600,29 @@ export function requiresUserScopedConnection(config: UserScopedConnectionConfig)
);
}
/**
* Whether the config declares chat-only headers. Guards against a truthy `{}`
* the way `hasCustomUserVars` does.
*/
function hasChatOnlyHeaders(config: UserScopedConnectionConfig): boolean {
return !!config.requestHeaders && Object.keys(config.requestHeaders).length > 0;
}
/** Whether a server can share one operator-owned connection across all users. */
export function canUseAppConnection(config: UserScopedConnectionConfig): boolean {
return (
config.startup !== false && !isUserSourced(config) && !requiresUserScopedConnection(config)
config.startup !== false &&
!isUserSourced(config) &&
!requiresUserScopedConnection(config) &&
/**
* One session cannot serve both sides of `requestHeaders`: an app-shared
* connection's own `initialize` and `tools/list` are catalog requests that
* must omit them, while its chat tool calls must send them. Placeholder
* values are already excluded through `requiresUserScopedConnection`; STATIC
* values reach here, and sharing would bake chat-only headers into the
* startup handshake every later catalog read reuses.
*/
!hasChatOnlyHeaders(config)
);
}
@ -528,6 +636,7 @@ export function canUseAppConnection(config: UserScopedConnectionConfig): boolean
export function canBackfillSharedServerInstructions(config: UserScopedConnectionConfig): boolean {
return (
config.startup === false &&
!hasChatOnlyHeaders(config) &&
!requiresUserScopedConnection(config) &&
/** A configured `oauth` block is identity-scoped even when `requiresOAuth`
* is unset or was stamped `false` by the skipped startup inspection —
@ -550,13 +659,13 @@ export function canBackfillSharedServerInstructions(config: UserScopedConnection
* otherwise every tool call fails authentication. See issue #10969.
*/
export function getMissingCustomUserVars(
config: Pick<ParsedServerConfig, 'customUserVars'>,
config: UserScopedConnectionConfig,
providedVars?: Record<string, string> | null,
): string[] {
if (!hasCustomUserVars(config)) {
return [];
}
return Object.keys(config.customUserVars ?? {}).filter((key) => {
return requiredCustomUserVars(config).filter((key) => {
const value = providedVars?.[key];
return value == null || (typeof value === 'string' && value.trim() === '');
});

View file

@ -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);
});

View file

@ -9,6 +9,7 @@ import {
processMCPEnv,
encodeHeaderValue,
} from './env';
import { applyRequestHeaders } from '~/mcp/utils';
function isStdioOptions(options: MCPOptions): options is Extract<MCPOptions, { type?: 'stdio' }> {
return !options.type || options.type === 'stdio';
@ -1189,6 +1190,77 @@ describe('processMCPEnv', () => {
});
});
/**
* `applyRequestHeaders` runs at each pipeline entry, ahead of `processMCPEnv`,
* so the merged map is what env resolution sees. These exercise that order
* rather than either half alone.
*/
it('should resolve merged requestHeaders like any other header', () => {
const user = createTestUser({ id: 'user-123' });
const options: MCPOptions = {
type: 'streamable-http',
url: 'https://mcp.example.com/api',
headers: { 'X-User-Id': '{{LIBRECHAT_USER_ID}}' },
requestHeaders: {
'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
'X-Static': 'static-value',
},
};
const result = processMCPEnv({
options: applyRequestHeaders(options),
user,
body: { conversationId: 'conv-1' },
});
expect('headers' in result! && result.headers).toEqual({
'X-User-Id': 'user-123',
'X-Conversation-Id': 'conv-1',
'X-Static': 'static-value',
});
expect(result).not.toHaveProperty('requestHeaders');
});
it('should NOT resolve merged requestHeaders when dbSourced', () => {
const user = createTestUser({ id: 'user-123' });
const options: MCPOptions = {
type: 'streamable-http',
url: 'https://mcp.example.com/api',
requestHeaders: {
'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
};
const result = processMCPEnv({
options: applyRequestHeaders(options),
user,
body: { conversationId: 'conv-1' },
dbSourced: true,
});
expect('headers' in result! && result.headers).toEqual({
'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
});
});
it('should keep plugin-sourced requestHeaders verbatim', () => {
const user = createTestUser({ id: 'user-123' });
const options = {
type: 'streamable-http',
url: 'https://mcp.example.com/api',
source: 'plugin',
headers: { 'X-Keep': 'kept' },
requestHeaders: { 'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
} as MCPOptions & { source: string };
const result = processMCPEnv({ options, user, body: { conversationId: 'conv-1' } });
expect('headers' in result! && result.headers).toEqual({ 'X-Keep': 'kept' });
expect((result as { requestHeaders?: Record<string, string> }).requestHeaders).toEqual({
'X-Conversation-Id': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
});
});
it('should process user field placeholders in all fields', () => {
const user = createTestUser({
id: 'user-123',

View file

@ -10,6 +10,7 @@ import {
processOpenIDPlaceholders,
OpenIDReauthRequiredError,
} from './oidc';
import { getAdminApiKeyHeader } from '~/mcp/headers';
/**
* Provenance marker for MCP servers contributed by an Agent Plugins package.
@ -417,36 +418,13 @@ export function processMCPEnv(params: {
const newObj: MCPOptions = structuredClone(options);
// Apply admin-provided API key to headers at runtime
// Note: User-provided keys use {{MCP_API_KEY}} placeholder in headers,
// which is processed later via customUserVars replacement
if ('apiKey' in newObj && newObj.apiKey) {
const apiKeyConfig = newObj.apiKey as {
key?: string;
source: 'admin' | 'user';
authorization_type: 'basic' | 'bearer' | 'custom';
custom_header?: string;
const adminHeader = getAdminApiKeyHeader(newObj.apiKey);
if (adminHeader) {
const objWithHeaders = newObj as { headers?: Record<string, string> };
objWithHeaders.headers = {
...objWithHeaders.headers,
[adminHeader.name]: adminHeader.value,
};
if (apiKeyConfig.source === 'admin' && apiKeyConfig.key) {
const { key, authorization_type, custom_header } = apiKeyConfig;
const headerName =
authorization_type === 'custom' ? custom_header || 'X-Api-Key' : 'Authorization';
let headerValue = key;
if (authorization_type === 'basic') {
headerValue = `Basic ${key}`;
} else if (authorization_type === 'bearer') {
headerValue = `Bearer ${key}`;
}
// Initialize headers if needed and add the API key header (overwrites if header already exists)
const objWithHeaders = newObj as { headers?: Record<string, string> };
if (!objWithHeaders.headers) {
objWithHeaders.headers = {};
}
objWithHeaders.headers[headerName] = headerValue;
}
}
if ('env' in newObj && newObj.env) {

View file

@ -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.

View file

@ -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