🔌 perf: Look Up MCP Server Catalogs Concurrently for Tool Definitions (#17973)

* perf: Look Up MCP Server Catalogs Concurrently for Tool Definitions
* test: Cover MCP Sign-In Order for Concurrent Catalog Lookups
* docs: Widen the mcpCatalogLookups Comment in the Example Config
* test: Cover the Catalog Lookup Bound Passed to the Definitions Loader
This commit is contained in:
Marco Beretta 2026-11-10 17:33:18 +01:00 • committed by GitHub
parent 0701ce70a7
commit bcbb8290ec
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 1036 additions and 61 deletions

View file

@ -14,6 +14,7 @@ const {
createAuthIdentityContext,
selectMCPUpstreamTokenProvider,
loadToolDefinitions,
orderMCPServerNames,
createMCPToolApprovalMetadata,
GenerationJobManager,
isActionDomainAllowed,
@ -1403,6 +1404,7 @@ async function loadToolDefinitionsWrapper({
mcpToolAliases,
mcpResolution,
oauthActionToolNames,
mcpServerLookupOrder,
} = await loadToolDefinitions(
{
userId: req.user.id,
@ -1420,6 +1422,7 @@ async function loadToolDefinitionsWrapper({
mcpServerNames,
rawServerNames: mcpRawServerNames,
accessibleServerNames: defsAccessibleServerNames,
mcpCatalogLookups: appConfig?.concurrency?.mcpCatalogLookups,
},
{
isBuiltInTool,
@ -1443,7 +1446,7 @@ async function loadToolDefinitionsWrapper({
}
if (pendingOAuthServers.size > 0 && (res || streamId)) {
const serverNames = Array.from(pendingOAuthServers);
const serverNames = orderMCPServerNames(pendingOAuthServers, mcpServerLookupOrder);
logger.info(
`[Tool Definitions] MCP OAuth required for ${serverNames.length} server(s); emitting events and waiting`,
);
@ -1518,6 +1521,7 @@ async function loadToolDefinitionsWrapper({
mcpServerNames,
rawServerNames: mcpRawServerNames,
accessibleServerNames: defsAccessibleServerNames,
mcpCatalogLookups: appConfig?.concurrency?.mcpCatalogLookups,
},
{
isBuiltInTool,

View file

@ -1799,6 +1799,120 @@ describe('ToolService - Action Capability Gating', () => {
]);
});
it('numbers the pending MCP OAuth login steps in the order the loader looked the servers up', async () => {
const req = createMockReq([AgentCapabilities.tools]);
const res = { writableEnded: false };
const servers = ['ELI', 'Vespa'];
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
mockResolveConfigServers.mockResolvedValue(
Object.fromEntries(
servers.map((serverName) => [
serverName,
{
type: 'streamable-http',
url: `https://mcp.example.com/${serverName}`,
requiresOAuth: true,
},
]),
),
);
mockLoadToolDefinitions
.mockImplementationOnce(async (_args, deps) => {
/** Lookups run together, so the second server can be the first to need its sign-in. */
await deps.getOrFetchMCPServerTools(req.user.id, servers[1]);
await deps.getOrFetchMCPServerTools(req.user.id, servers[0]);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
mcpServerLookupOrder: servers,
};
})
.mockResolvedValue({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
});
reinitMCPServer.mockImplementation(
async ({ serverName, returnOnOAuth, oauthStart, oauthEnd }) => {
if (returnOnOAuth === false) {
await oauthStart(`https://auth.example.com/${serverName}`);
await oauthEnd();
return { availableTools: { [`tool_${serverName}`]: {} } };
}
await oauthStart(`https://auth.example.com/${serverName}`);
return { availableTools: null };
},
);
await loadAgentTools({
req,
res,
agent: {
id: 'agent_123',
tools: servers.map((server) => `search${Constants.mcp_delimiter}${server}`),
},
definitionsOnly: true,
});
const stepIndexes = Object.fromEntries(
mockSendEvent.mock.calls
.map(([, event]) => event)
.filter((event) => event.data?.stepDetails?.type === 'tool_calls')
.map((event) => [event.data.id, event.data.index]),
);
expect(stepIndexes).toEqual({ step_oauth_login_ELI: 0, step_oauth_login_Vespa: 1 });
});
it('passes the configured MCP catalog lookup bound to the definitions loader and to its reload after OAuth', async () => {
const req = createMockReq([AgentCapabilities.tools]);
req.config.concurrency = { mcpCatalogLookups: 2 };
const res = { writableEnded: false };
const serverName = 'ELI';
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
mockResolveConfigServers.mockResolvedValue({
[serverName]: {
type: 'streamable-http',
url: `https://mcp.example.com/${serverName}`,
requiresOAuth: true,
},
});
mockLoadToolDefinitions
.mockImplementationOnce(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return { toolDefinitions: [], toolRegistry: new Map(), hasDeferredTools: false };
})
.mockResolvedValue({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
});
reinitMCPServer.mockImplementation(async ({ returnOnOAuth, oauthStart, oauthEnd }) => {
await oauthStart(`https://auth.example.com/${serverName}`);
if (returnOnOAuth === false) {
await oauthEnd();
return { availableTools: { [`tool_${serverName}`]: {} } };
}
return { availableTools: null };
});
await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [`search${Constants.mcp_delimiter}${serverName}`] },
definitionsOnly: true,
});
expect(
mockLoadToolDefinitions.mock.calls.map(([params]) => params.mcpCatalogLookups),
).toEqual([2, 2]);
});
it('does not count an empty post-OAuth catalog as tools available or reload definitions', async () => {
const req = createMockReq([AgentCapabilities.tools]);
const res = { writableEnded: false };

View file

@ -0,0 +1,113 @@
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import type { Agents } from 'librechat-data-provider';
import type { AgentDetail } from '../agents.helpers';
import { cleanupAgent, openAgentBuilder, uniqueAgentName } from '../agents.helpers';
import {
MOCK_ENDPOINTS,
NEW_CHAT_PATH,
fetchJson,
getAccessToken,
requestJson,
sendMessage,
} from '../helpers';
const SERVERS = ['e2e-oauth', 'e2e-oauth-deferred'] as const;
const SIGN_IN_BUTTON = /Sign-in to 127\.0\.0\.1/i;
const SIGN_IN_TOOL_PREFIX = 'oauth_mcp_';
type GenerationStatus = {
resumeState?: {
runSteps?: Agents.RunStep[];
pendingOAuthPrompts?: Agents.PendingMCPOAuthPrompt[];
};
};
/** The agent is picked in the builder side panel, which the mobile layout keeps in a drawer. */
test.use({ viewport: { width: 1280, height: 860 }, hasTouch: false, isMobile: false });
/** The sign-in tool calls of a turn, in the order of the steps that carry them. */
function signInToolNames(runSteps: Agents.RunStep[] = []): string[] {
return [...runSteps]
.sort((a, b) => a.index - b.index)
.flatMap((step) => {
const details = step.stepDetails as { tool_calls?: Array<{ name?: string }> };
return (details.tool_calls ?? []).map((call) => call.name ?? '');
})
.filter((name) => name.startsWith(SIGN_IN_TOOL_PREFIX));
}
/**
* Sends a turn to an agent whose tools come from each protected server in `servers`, in that
* order, and returns the sign-in prompts the turn holds on, once there is one per server.
*/
async function signInsFor(page: Page, servers: readonly string[]) {
await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
const token = await getAccessToken(page);
const agentName = uniqueAgentName('E2E OAuth Order Agent');
const agent = await requestJson<AgentDetail>(page, {
path: '/api/agents',
token,
method: 'POST',
body: {
name: agentName,
description:
'Verifies the order of the sign-in prompts for tools from two protected servers.',
instructions: 'Use the tools of both servers.',
provider: MOCK_ENDPOINTS[0].label,
model: MOCK_ENDPOINTS[0].model,
tools: servers.map((server) => `echo_mcp_${server}`),
},
});
try {
const form = await openAgentBuilder(page);
await form.getByRole('combobox', { name: 'Agent', exact: true }).click();
await page.getByRole('option', { name: agentName }).click();
await expect(form.getByLabel('Agent name')).toHaveValue(agentName);
await form.getByRole('button', { name: 'Select Agent' }).click();
const label = `${Date.now()}-${Math.floor(Math.random() * 1e4)}`;
const admission = await sendMessage(page, `Use both servers ${label}`);
expect(admission.ok()).toBeTruthy();
const { conversationId } = (await admission.json()) as { conversationId?: string };
expect(conversationId).toBeTruthy();
await expect(page.getByRole('button', { name: SIGN_IN_BUTTON })).toHaveCount(servers.length, {
timeout: 30000,
});
const status = await fetchJson<GenerationStatus>(
page,
`/api/agents/chat/status/${encodeURIComponent(conversationId!)}`,
token,
);
return {
steps: signInToolNames(status.resumeState?.runSteps),
prompts: [...(status.resumeState?.pendingOAuthPrompts ?? [])]
.sort((a, b) => a.index - b.index)
.map((prompt) => prompt.toolName),
};
} finally {
const stop = page.getByRole('button', { name: 'Stop generating' });
if (await stop.isVisible({ timeout: 1000 }).catch(() => false)) {
await stop.click();
await expect(stop).toBeHidden({ timeout: 10000 });
}
await cleanupAgent(page, agent.id);
}
}
test('an agent with tools from two protected servers asks to sign in to each, in the order of its tools @scenario:mcp-two-protected-servers-sign-in-in-tool-order', async ({
page,
}) => {
test.setTimeout(240000);
for (const servers of [SERVERS, [...SERVERS].reverse()]) {
const expected = servers.map((server) => `${SIGN_IN_TOOL_PREFIX}${server}`);
const { steps, prompts } = await signInsFor(page, servers);
expect(steps).toEqual(expected);
expect(prompts).toEqual(expected);
}
});

View file

@ -592,7 +592,7 @@ registration:
# Upper bounds on independent lookups a request runs at once (1 to 32). Each omitted key keeps the default shown.
# concurrency:
# connectedAgentLoads: 4 # connected agents initialized together per level of a handoff graph
# mcpCatalogLookups: 4 # MCP tool catalog reads when assembling an ephemeral or added agent
# mcpCatalogLookups: 4 # MCP tool catalog reads when assembling an agent's tools
# skillNameLookups: 8 # model spec skill name resolutions
# skillFileInspections: 4 # bundled skill file inspections before a skill is primed
# resumeAgentLoads: 4 # agent reads while building the resume snapshot of a paused run

View file

@ -1,13 +1,15 @@
import { Providers, WebSearchToolDefinition, GitHubCompareToolDefinition } from '@librechat/agents';
import type {
LoadToolDefinitionsParams,
LoadToolDefinitionsResult,
LoadToolDefinitionsDeps,
ActionToolDefinition,
MCPServerTools,
} from './definitions';
import { loadToolDefinitions, orderMCPServerNames } from './definitions';
import { toolkitExpansion, toolkitParent } from './toolkits/mapping';
import { getToolDefinition } from './registry/definitions';
import { getToolApprovalIdentity } from './approval';
import { loadToolDefinitions } from './definitions';
import { formatMCPServerTools } from '~/mcp/tools';
import { getToolApprovalName } from './approval';
@ -1128,6 +1130,592 @@ describe('definitions.ts', () => {
});
});
describe('concurrent MCP and action resolution', () => {
type Fetched = MCPServerTools | null;
type FetchMock = jest.Mock<Promise<Fetched>, [string, string]>;
const settle = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
function deferred<T>() {
let resolve!: (value: T) => void;
let reject!: (error: Error) => void;
const promise = new Promise<T>((yes, no) => {
resolve = yes;
reject = no;
});
return { promise, resolve, reject };
}
/** One tool per name, keyed the way a server catalog builds its keys. */
function catalogOf(serverName: string, ...names: string[]): MCPServerTools {
const catalog: MCPServerTools = {};
for (const name of names) {
const key = `${name}_mcp_${serverName}`;
catalog[key] = {
function: {
name: key,
description: `${name} on ${serverName}`,
parameters: { type: 'object', properties: {} },
},
};
}
return catalog;
}
const calledServers = (fetch: FetchMock): string[] =>
fetch.mock.calls.map(([, serverName]) => serverName);
const toolNames = (result: Pick<LoadToolDefinitionsResult, 'toolDefinitions'>): string[] =>
result.toolDefinitions.map(({ name }) => name);
const toolServers = (
result: Pick<LoadToolDefinitionsResult, 'toolDefinitions'>,
): [string, string | undefined][] =>
result.toolDefinitions.map((def) => [
def.name,
'serverName' in def ? def.serverName : undefined,
]);
const baseParams = { userId: 'user-123', agentId: 'agent-123' };
it('starts the fetch for every distinct server before any of them resolves', async () => {
const alpha = deferred<Fetched>();
const beta = deferred<Fetched>();
const fetch: FetchMock = jest.fn((_userId, serverName) =>
serverName === 'alpha' ? alpha.promise : beta.promise,
);
const loading = loadToolDefinitions(
{ ...baseParams, tools: ['search_mcp_alpha', 'list_mcp_beta'] },
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
await settle();
try {
expect(calledServers(fetch)).toEqual(['alpha', 'beta']);
} finally {
alpha.resolve(catalogOf('alpha', 'search'));
beta.resolve(catalogOf('beta', 'list'));
}
const result = await loading;
expect(toolNames(result)).toEqual(['search_mcp_alpha', 'list_mcp_beta']);
expect(result.mcpResolution).toEqual({ expectedToolCount: 2, resolvedToolCount: 2 });
});
it('fetches a server once however many of its tools are selected', async () => {
const fetch: FetchMock = jest.fn(async (_userId, serverName) =>
catalogOf(serverName, 'search', 'list'),
);
const result = await loadToolDefinitions(
{ ...baseParams, tools: ['search_mcp_alpha', 'list_mcp_beta', 'list_mcp_alpha'] },
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
expect(calledServers(fetch).sort()).toEqual(['alpha', 'beta']);
expect(toolNames(result)).toEqual(['search_mcp_alpha', 'list_mcp_beta', 'list_mcp_alpha']);
expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 3 });
});
it('keeps tool order in the output whatever order the fetches settle in', async () => {
const gates = new Map([
['alpha', deferred<Fetched>()],
['beta', deferred<Fetched>()],
['gamma', deferred<Fetched>()],
]);
const fetch: FetchMock = jest.fn(
(_userId, serverName) => gates.get(serverName)?.promise ?? Promise.resolve(null),
);
const loading = loadToolDefinitions(
{ ...baseParams, tools: ['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma'] },
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
await settle();
try {
expect(calledServers(fetch)).toEqual(['alpha', 'beta', 'gamma']);
} finally {
gates.get('gamma')?.resolve(catalogOf('gamma', 'c'));
gates.get('alpha')?.resolve(catalogOf('alpha', 'a'));
gates.get('beta')?.resolve(catalogOf('beta', 'b'));
}
const result = await loading;
expect(toolNames(result)).toEqual(['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma']);
});
it('holds a lookup back until one of the allowed number has settled', async () => {
const gates = new Map([
['alpha', deferred<Fetched>()],
['beta', deferred<Fetched>()],
['gamma', deferred<Fetched>()],
]);
const fetch: FetchMock = jest.fn(
(_userId, serverName) => gates.get(serverName)?.promise ?? Promise.resolve(null),
);
const loading = loadToolDefinitions(
{
...baseParams,
tools: ['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma'],
mcpCatalogLookups: 2,
},
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
await settle();
try {
expect(calledServers(fetch)).toEqual(['alpha', 'beta']);
gates.get('beta')?.resolve(catalogOf('beta', 'b'));
await settle();
expect(calledServers(fetch)).toEqual(['alpha', 'beta', 'gamma']);
} finally {
gates.get('alpha')?.resolve(catalogOf('alpha', 'a'));
gates.get('beta')?.resolve(catalogOf('beta', 'b'));
gates.get('gamma')?.resolve(catalogOf('gamma', 'c'));
}
const result = await loading;
expect(toolNames(result)).toEqual(['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma']);
});
it('looks servers up one after another when the bound is 1', async () => {
const alpha = deferred<Fetched>();
const fetch: FetchMock = jest.fn((_userId, serverName) =>
serverName === 'alpha' ? alpha.promise : Promise.resolve(catalogOf('beta', 'list')),
);
const loading = loadToolDefinitions(
{ ...baseParams, tools: ['search_mcp_alpha', 'list_mcp_beta'], mcpCatalogLookups: 1 },
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
await settle();
try {
expect(calledServers(fetch)).toEqual(['alpha']);
} finally {
alpha.resolve(catalogOf('alpha', 'search'));
}
const result = await loading;
expect(calledServers(fetch)).toEqual(['alpha', 'beta']);
expect(toolNames(result)).toEqual(['search_mcp_alpha', 'list_mcp_beta']);
});
it('reports the looked-up servers in tool order whatever order they settle in', async () => {
const gates = new Map([
['alpha', deferred<Fetched>()],
['beta', deferred<Fetched>()],
['gamma', deferred<Fetched>()],
]);
const fetch: FetchMock = jest.fn(
(_userId, serverName) => gates.get(serverName)?.promise ?? Promise.resolve(null),
);
const loading = loadToolDefinitions(
{ ...baseParams, tools: ['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma', 'd_mcp_alpha'] },
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
await settle();
gates.get('gamma')?.resolve(catalogOf('gamma', 'c'));
gates.get('beta')?.resolve(null);
gates.get('alpha')?.resolve(catalogOf('alpha', 'a', 'd'));
const result = await loading;
expect(result.mcpServerLookupOrder).toEqual(['alpha', 'beta', 'gamma']);
});
describe('alias fallback', () => {
const aliasParams = {
...baseParams,
mcpServerNames: ['alpha', 'Connector__Company', 'Other__Server'],
rawServerNames: ['alpha', 'Connector: Company', 'Other: Server'],
accessibleServerNames: ['alpha', 'Other__Server', 'Other: Server'],
};
it('falls back to the raw alias only for a parsed name that is not a known server', async () => {
const fetch: FetchMock = jest.fn(async (_userId, serverName) => {
if (serverName === 'alpha') {
return catalogOf('alpha', 'search');
}
return serverName === 'Connector: Company'
? catalogOf('Connector__Company', 'find')
: null;
});
const result = await loadToolDefinitions(
{
...aliasParams,
tools: ['search_mcp_alpha', 'find_mcp_Connector__Company', 'ping_mcp_Other__Server'],
},
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
expect(calledServers(fetch).sort()).toEqual([
'Connector: Company',
'Connector__Company',
'Other__Server',
'alpha',
]);
expect(toolServers(result)).toEqual([
['search_mcp_alpha', 'alpha'],
['find_mcp_Connector__Company', 'Connector: Company'],
]);
expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 2 });
});
it('shares one in-flight fetch between a direct lookup and an alias fallback to the same server', async () => {
/** `Connector__Company` is not a known server, so it falls back to its raw alias,
* which the second tool key is already looking up directly. */
const normalized = deferred<Fetched>();
const raw = deferred<Fetched>();
const fetch: FetchMock = jest.fn((_userId, serverName) =>
serverName === 'Connector__Company' ? normalized.promise : raw.promise,
);
const loading = loadToolDefinitions(
{
...aliasParams,
tools: ['search_mcp_Connector__Company', 'lookup_mcp_Connector: Company'],
},
{ getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false },
);
await settle();
normalized.resolve(null);
await settle();
raw.resolve({
...catalogOf('Connector__Company', 'search'),
...catalogOf('Connector: Company', 'lookup'),
});
const result = await loading;
expect(calledServers(fetch)).toEqual(['Connector__Company', 'Connector: Company']);
expect(toolServers(result)).toEqual([
['search_mcp_Connector__Company', 'Connector: Company'],
['lookup_mcp_Connector: Company', 'Connector: Company'],
]);
});
});
it('keeps definition order, counts and OAuth action names for a mixed tool list', async () => {
const fetch: FetchMock = jest.fn(async (_userId, serverName) =>
serverName === 'alpha' ? catalogOf('alpha', 'search') : catalogOf('beta', 'list', 'get'),
);
const getActionToolDefinitions = jest.fn<
Promise<ActionToolDefinition[]>,
[string, string[]]
>(async () => [
{ name: 'getWeather_action_weather_com', description: 'Get weather' },
{ name: 'sendMail_action_mail_example_com', description: 'Send an email', oauth: true },
]);
const result = await loadToolDefinitions(
{
...baseParams,
tools: [
'calculator',
'search_mcp_alpha',
'getWeather_action_weather---com',
'sys__all__sys_mcp_beta',
'web_search',
'ghost_mcp_alpha',
'sys__server__sys_mcp_alpha',
'sendMail_action_mail---example---com',
'not_a_builtin',
],
},
{
getOrFetchMCPServerTools: fetch,
getActionToolDefinitions,
isBuiltInTool: (name) => name === 'calculator' || name === 'web_search',
},
);
expect(toolNames(result)).toEqual([
'search_mcp_alpha',
'list_mcp_beta',
'get_mcp_beta',
'getWeather_action_weather_com',
'sendMail_action_mail_example_com',
'calculator',
'web_search',
]);
expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 3 });
expect(result.oauthActionToolNames).toEqual(['sendMail_action_mail_example_com']);
expect(calledServers(fetch).sort()).toEqual(['alpha', 'beta']);
expect(getActionToolDefinitions).toHaveBeenCalledWith('agent-123', [
'getWeather_action_weather---com',
'sendMail_action_mail---example---com',
]);
});
it('starts the action definition fetch while MCP fetches are still pending', async () => {
const alpha = deferred<Fetched>();
const actions = deferred<ActionToolDefinition[]>();
const fetch = jest.fn<Promise<Fetched>, [string, string]>(() => alpha.promise);
const getActionToolDefinitions = jest.fn<
Promise<ActionToolDefinition[]>,
[string, string[]]
>(() => actions.promise);
const loading = loadToolDefinitions(
{ ...baseParams, tools: ['search_mcp_alpha', 'getWeather_action_weather---com'] },
{ getOrFetchMCPServerTools: fetch, getActionToolDefinitions, isBuiltInTool: () => false },
);
await settle();
try {
expect(getActionToolDefinitions).toHaveBeenCalledWith('agent-123', [
'getWeather_action_weather---com',
]);
expect(calledServers(fetch)).toEqual(['alpha']);
} finally {
actions.resolve([{ name: 'getWeather_action_weather_com', description: 'Get weather' }]);
alpha.resolve(catalogOf('alpha', 'search'));
}
const result = await loading;
expect(toolNames(result)).toEqual(['search_mcp_alpha', 'getWeather_action_weather_com']);
});
describe('failures', () => {
const failureTools = ['a_mcp_alpha', 'b_mcp_beta'];
it('rejects with the error of a rejecting fetch, while a null fetch only leaves the server empty', async () => {
const failure = new Error('registry down');
await expect(
loadToolDefinitions(
{ ...baseParams, tools: failureTools },
{
getOrFetchMCPServerTools: async (_userId, serverName) => {
if (serverName === 'alpha') {
throw failure;
}
return catalogOf('beta', 'b');
},
isBuiltInTool: () => false,
},
),
).rejects.toBe(failure);
const unavailable = await loadToolDefinitions(
{ ...baseParams, tools: failureTools },
{ getOrFetchMCPServerTools: async () => null, isBuiltInTool: () => false },
);
expect(unavailable.toolDefinitions).toEqual([]);
expect(unavailable.mcpResolution).toEqual({ expectedToolCount: 2, resolvedToolCount: 0 });
});
it('rejects with the error of the action fetch', async () => {
const failure = new Error('actions unavailable');
await expect(
loadToolDefinitions(
{ ...baseParams, tools: ['a_mcp_alpha', 'getWeather_action_weather---com'] },
{
getOrFetchMCPServerTools: async () => catalogOf('alpha', 'a'),
getActionToolDefinitions: async () => {
throw failure;
},
isBuiltInTool: () => false,
},
),
).rejects.toBe(failure);
});
it('leaves no unhandled rejection when the other fetches fail after the first failure', async () => {
/** jest-circus fails the running test on an unhandled rejection, so finishing this one
* after the late failures have fired is the assertion. */
const failLater: Array<() => void> = [];
const failLate = (label: string): Promise<never> =>
new Promise((_resolve, reject) => {
failLater.push(() => reject(new Error(`${label} failed late`)));
});
const fetch: FetchMock = jest.fn((_userId, serverName) =>
serverName === 'alpha'
? Promise.reject(new Error('alpha failed'))
: failLate(serverName),
);
const getActionToolDefinitions = jest.fn<
Promise<ActionToolDefinition[]>,
[string, string[]]
>(() => failLate('actions'));
await expect(
loadToolDefinitions(
{
...baseParams,
tools: [
'a_mcp_alpha',
'b_mcp_beta',
'c_mcp_gamma',
'getWeather_action_weather---com',
],
},
{
getOrFetchMCPServerTools: fetch,
getActionToolDefinitions,
isBuiltInTool: () => false,
},
),
).rejects.toThrow('alpha failed');
expect(failLater).toHaveLength(3);
failLater.forEach((fail) => fail());
await settle();
await settle();
});
});
describe('refresh', () => {
it('stays serial and happens once per server', async () => {
const staleAlpha = catalogOf('alpha', 'list');
const staleBeta = catalogOf('beta', 'list');
const alphaRefresh = deferred<Fetched>();
const betaRefresh = deferred<Fetched>();
const refresh: FetchMock = jest.fn((_userId, serverName) =>
serverName === 'alpha' ? alphaRefresh.promise : betaRefresh.promise,
);
const loading = loadToolDefinitions(
{ ...baseParams, tools: ['run_mcp_alpha', 'run_mcp_beta', 'other_mcp_alpha'] },
{
getOrFetchMCPServerTools: async (_userId, serverName) =>
serverName === 'alpha' ? staleAlpha : staleBeta,
refreshMCPServerTools: refresh,
isBuiltInTool: () => false,
},
);
await settle();
expect(calledServers(refresh)).toEqual(['alpha']);
alphaRefresh.resolve({ ...staleAlpha, ...catalogOf('alpha', 'run', 'other') });
await settle();
expect(calledServers(refresh)).toEqual(['alpha', 'beta']);
betaRefresh.resolve({ ...staleBeta, ...catalogOf('beta', 'run') });
const result = await loading;
expect(calledServers(refresh)).toEqual(['alpha', 'beta']);
expect(toolNames(result)).toEqual(['run_mcp_alpha', 'run_mcp_beta', 'other_mcp_alpha']);
});
it('resolves a later spelling of a refreshed server against the refreshed catalog', async () => {
/** The refreshed catalog is what a later lookup of the same server returns, as it is
* for the request-scoped tool memory the real loader dependency keeps. */
let current: MCPServerTools = catalogOf('Connector__Company', 'other');
const refreshed: MCPServerTools = {
...current,
...catalogOf('Connector__Company', 'search'),
...catalogOf('Connector: Company', 'lookup'),
};
const result = await loadToolDefinitions(
{
...baseParams,
tools: ['search_mcp_Connector__Company', 'lookup_mcp_Connector: Company'],
mcpServerNames: ['Connector__Company'],
rawServerNames: ['Connector: Company'],
},
{
getOrFetchMCPServerTools: async (_userId, serverName) =>
serverName === 'Connector: Company' ? current : null,
refreshMCPServerTools: async () => {
current = refreshed;
return refreshed;
},
isBuiltInTool: () => false,
},
);
expect(toolNames(result)).toEqual([
'search_mcp_Connector__Company',
'lookup_mcp_Connector: Company',
]);
expect(result.mcpResolution).toEqual({ expectedToolCount: 2, resolvedToolCount: 2 });
});
it('resolves a later spelling again after a refresh made its server available', async () => {
/** `legacy_mcp_Other: Server` names the raw server, unavailable until its refresh;
* `search_mcp_Other__Server` reaches the same server through its alias. */
let available = false;
const catalog: MCPServerTools = {
...catalogOf('Other__Server', 'search'),
...catalogOf('Other: Server', 'legacy'),
};
const refresh: FetchMock = jest.fn(async (_userId, serverName) => {
if (serverName !== 'Other: Server') {
return null;
}
available = true;
return catalog;
});
const result = await loadToolDefinitions(
{
...baseParams,
tools: ['legacy_mcp_Other: Server', 'search_mcp_Other__Server'],
mcpServerNames: ['Other__Server'],
rawServerNames: ['Other: Server'],
},
{
getOrFetchMCPServerTools: async (_userId, serverName) =>
serverName === 'Other: Server' && available ? catalog : null,
refreshMCPServerTools: refresh,
isBuiltInTool: () => false,
},
);
expect(calledServers(refresh)).toEqual(['Other: Server']);
expect(toolServers(result)).toEqual([
['legacy_mcp_Other: Server', 'Other: Server'],
['search_mcp_Other__Server', 'Other: Server'],
]);
});
it('keeps an earlier spelling on the catalog it was resolved with', async () => {
/** A tool only the refreshed catalog holds stays unresolved under the spelling that
* was already resolved: a refresh through the other spelling does not rewrite it. */
let current: MCPServerTools = catalogOf('Connector__Company', 't2');
const refreshed: MCPServerTools = {
...catalogOf('Connector__Company', 't2', 't3'),
...catalogOf('Connector: Company', 't3'),
};
const result = await loadToolDefinitions(
{
...baseParams,
tools: [
't2_mcp_Connector__Company',
't3_mcp_Connector: Company',
't3_mcp_Connector__Company',
],
mcpServerNames: ['Connector__Company'],
rawServerNames: ['Connector: Company'],
},
{
getOrFetchMCPServerTools: async (_userId, serverName) =>
serverName === 'Connector: Company' ? current : null,
refreshMCPServerTools: async () => {
current = refreshed;
return refreshed;
},
isBuiltInTool: () => false,
},
);
expect(toolNames(result)).toEqual([
't2_mcp_Connector__Company',
't3_mcp_Connector: Company',
]);
expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 2 });
});
});
});
describe('toolkit expansion', () => {
it('should expand image_gen_oai to include image_edit_oai', async () => {
mockIsBuiltInTool.mockImplementation((name) => name === 'image_gen_oai');
@ -1345,3 +1933,28 @@ test('live catalog reassignment changes consent while retaining the same display
getToolApprovalIdentity(first.toolDefinitions[0]),
);
});
describe('orderMCPServerNames', () => {
it('puts the names in lookup order', () => {
expect(
orderMCPServerNames(new Set(['gamma', 'alpha', 'beta']), ['alpha', 'beta', 'gamma']),
).toEqual(['alpha', 'beta', 'gamma']);
});
it('keeps names that were never looked up after the rest, in the order given', () => {
expect(orderMCPServerNames(['late', 'beta', 'other', 'alpha'], ['alpha', 'beta'])).toEqual([
'alpha',
'beta',
'late',
'other',
]);
});
it('returns nothing for no names', () => {
expect(orderMCPServerNames([], ['alpha'])).toEqual([]);
});
it('returns the names as given when no lookup order is known', () => {
expect(orderMCPServerNames(new Set(['beta', 'alpha']))).toEqual(['beta', 'alpha']);
});
});

View file

@ -21,6 +21,8 @@ import type { CodeEnvironmentConfig, CodeExecutionContext } from '~/agents/execu
import type { CodeCapabilityConfigLoader } from '~/code/capabilities';
import type { MCPToolAlias, ToolDefinition } from './classification';
import { resolveJsonSchemaRefs, normalizeJsonSchema, sanitizeGeminiSchema } from '~/mcp/zod';
import { DEFAULT_LOOKUP_CONCURRENCY } from '~/utils/concurrency';
import { mapWithConcurrency } from '~/utils/promise';
import { buildToolClassification } from './classification';
import { getToolDefinition } from './registry/definitions';
import { toolkitExpansion } from './toolkits/mapping';
@ -77,6 +79,12 @@ export interface LoadToolDefinitionsParams {
* unavailable server's names.
*/
accessibleServerNames?: readonly string[];
/**
* Upper bound on MCP server catalog lookups in flight at once: the deployment's
* `concurrency.mcpCatalogLookups`. A cold lookup can reconnect a server or spawn its process,
* so one request does not start them all together. `1` looks servers up one after another.
*/
mcpCatalogLookups?: number;
}
export interface ActionToolDefinition {
@ -89,13 +97,15 @@ export interface ActionToolDefinition {
}
export interface LoadToolDefinitionsDeps {
/** Gets MCP server tools - first checks cache, then initializes server if needed */
/** Gets MCP server tools - first checks cache, then initializes server if needed. Called
* concurrently for different servers; a server is looked up again only after its refresh. */
getOrFetchMCPServerTools: (userId: string, serverName: string) => Promise<MCPServerTools | null>;
/** Bypasses a non-empty stale catalog when it does not contain a selected tool. */
refreshMCPServerTools?: (userId: string, serverName: string) => Promise<MCPServerTools | null>;
/** Checks if a tool name is a known built-in tool */
isBuiltInTool: (toolName: string) => boolean;
/** Loads action tool definitions (schemas) from OpenAPI specs */
/** Loads action tool definitions (schemas) from OpenAPI specs. Started together with the
* MCP server lookups. */
getActionToolDefinitions?: (
agentId: string,
actionToolNames: string[],
@ -112,16 +122,105 @@ export interface LoadToolDefinitionsResult {
expectedToolCount: number;
resolvedToolCount: number;
};
/** Action tool names backed by OAuth — excluded from background dispatch. */
/** Action tool names backed by OAuth; excluded from background dispatch. */
oauthActionToolNames: string[];
/**
* Every server name that was looked up, in tool order: each parsed key, then its raw alias
* when that was tried. Lookups settle in any order, so work that follows them and must stay in
* tool order (the OAuth sign-in prompts) takes its order from this list.
*/
mcpServerLookupOrder: string[];
}
/**
* `names` in the order of `lookupOrder`; names it does not list keep their relative order after
* the listed ones, so without a lookup order the names come back as given.
*/
export function orderMCPServerNames(
names: Iterable<string>,
lookupOrder: readonly string[] = [],
): string[] {
const rank = new Map(lookupOrder.map((name, index) => [name, index]));
const listed: string[] = [];
const unlisted: string[] = [];
for (const name of names) {
(rank.has(name) ? listed : unlisted).push(name);
}
listed.sort((a, b) => (rank.get(a) ?? 0) - (rank.get(b) ?? 0));
return [...listed, ...unlisted];
}
const mcpToolPattern = /_mcp_/;
const mcpServerPinPrefix = `${Constants.mcp_server}${Constants.mcp_delimiter}`;
interface ServerCatalog {
serverKey: string;
/** Server names the lookup asked for: the key, then its alias when that was tried. */
lookups: string[];
tools: MCPServerTools;
/** The RAW server name the key resolved to (direct-first). */
resolvedName: string;
}
/**
* Fetches the catalog of every distinct parsed server key, at most `concurrency` keys at a time.
* Each key resolves DIRECT-FIRST: the parsed name as-is, then, only when it is not a known
* accessible server, its raw alias. Within one resolution a fetch is shared by server name, so a
* direct lookup and an alias fallback that land on the same server make one call instead of
* racing two reconnects.
*
* A rejected fetch rejects the whole resolution. The others keep running but stay observed, so
* a later failure cannot surface as an unhandled rejection.
*/
async function resolveServerCatalogs({
userId,
serverKeys,
concurrency,
accessibleServerNames,
serverNameAliases,
getOrFetchMCPServerTools,
}: {
userId: string;
serverKeys: readonly string[];
concurrency: number;
accessibleServerNames?: readonly string[];
serverNameAliases: ReadonlyMap<string, string>;
getOrFetchMCPServerTools: LoadToolDefinitionsDeps['getOrFetchMCPServerTools'];
}): Promise<ServerCatalog[]> {
const inFlight = new Map<string, Promise<MCPServerTools | null>>();
const fetchOnce = (serverName: string): Promise<MCPServerTools | null> => {
const pending = inFlight.get(serverName) ?? getOrFetchMCPServerTools(userId, serverName);
inFlight.set(serverName, pending);
return pending;
};
return mapWithConcurrency(serverKeys, concurrency, async (serverKey): Promise<ServerCatalog> => {
let resolvedName = serverKey;
const lookups = [serverKey];
let fetched = await fetchOnce(serverKey);
if (!fetched) {
/** Alias fallback is for "server not found" ONLY: when the parsed name is a known
* accessible server, a null fetch means it is temporarily unavailable (OAuth pending,
* missing user variables, disconnected) and rerouting to the alias would emit the OTHER
* server's definitions under this server's names. */
const parsedIsKnownServer = accessibleServerNames?.includes(serverKey) === true;
const aliased = serverNameAliases.get(serverKey);
if (!parsedIsKnownServer && aliased != null && aliased !== serverKey) {
lookups.push(aliased);
fetched = await fetchOnce(aliased);
if (fetched) {
resolvedName = aliased;
}
}
}
return { serverKey, lookups, tools: fetched || {}, resolvedName };
});
}
/**
* Loads tool definitions without creating tool instances.
* This is the efficient path for event-driven mode where tools are loaded on-demand.
* MCP servers and action definitions are resolved concurrently.
*/
export async function loadToolDefinitions(
params: LoadToolDefinitionsParams,
@ -142,6 +241,7 @@ export async function loadToolDefinitions(
mcpServerNames,
rawServerNames,
accessibleServerNames,
mcpCatalogLookups = DEFAULT_LOOKUP_CONCURRENCY.mcpCatalogLookups,
} = params;
const {
getOrFetchMCPServerTools,
@ -169,6 +269,7 @@ export async function loadToolDefinitions(
mcpToolAliases: [],
mcpResolution: { expectedToolCount: 0, resolvedToolCount: 0 },
oauthActionToolNames: [],
mcpServerLookupOrder: [],
};
if (!tools || tools.length === 0) {
@ -181,8 +282,11 @@ export async function loadToolDefinitions(
const resolvedServerNames = new Map<string, string>();
const mcpToolDefs: ToolDefinition[] = [];
const builtInToolDefs: ToolDefinition[] = [];
let actionToolDefs: ToolDefinition[] = [];
const actionToolNames: string[] = [];
/** Tools that get a definition built, in selection order; `serverKey` is set for MCP tools. */
const selectedTools: { toolName: string; serverKey?: string }[] = [];
/** Distinct parsed server keys, in first-seen order. */
const serverKeys = new Set<string>();
let expectedMCPToolCount = 0;
let resolvedMCPToolCount = 0;
@ -196,6 +300,66 @@ export async function loadToolDefinitions(
}
if (!mcpToolPattern.test(toolName)) {
selectedTools.push({ toolName });
continue;
}
if (toolName.startsWith(mcpServerPinPrefix)) {
continue;
}
/** Keys carry the normalized server name (raw in pre-normalization data),
* so both spellings resolve the boundary. Resolution is DIRECT-FIRST: a
* server that resolves under the parsed name as-is wins (a user-DB
* server may be named exactly like an operator server's normalized
* form), and only when that yields nothing is the parsed name treated
* as a normalized spelling of a raw config name. The resolved RAW name
* feeds config lookups and definition metadata (`serverName`, then
* `mcpRawServerName`); server instructions are keyed by it. */
const [, parsedServerName] = splitMCPToolKey(toolName, [
...(mcpServerNames ?? []),
...(rawServerNames ?? []),
]);
const serverKey = parsedServerName ?? toolName;
serverKeys.add(serverKey);
selectedTools.push({ toolName, serverKey });
}
const loadActionDefinitions = async (): Promise<ActionToolDefinition[]> =>
actionToolNames.length > 0 && getActionToolDefinitions
? getActionToolDefinitions(agentId, actionToolNames)
: [];
const resolveKeys = (keys: readonly string[]): Promise<ServerCatalog[]> =>
resolveServerCatalogs({
userId,
serverKeys: keys,
concurrency: mcpCatalogLookups,
accessibleServerNames,
serverNameAliases,
getOrFetchMCPServerTools,
});
/** Server names each key asked for, to find the keys a refreshed server concerns. */
const lookedUp = new Map<string, readonly string[]>();
const adopt = (catalogs: ServerCatalog[]): void => {
for (const catalog of catalogs) {
mcpServerToolsCache.set(catalog.serverKey, catalog.tools);
resolvedServerNames.set(catalog.serverKey, catalog.resolvedName);
lookedUp.set(catalog.serverKey, catalog.lookups);
}
};
const [catalogs, fetchedActionDefs] = await Promise.all([
resolveKeys(Array.from(serverKeys)),
loadActionDefinitions(),
]);
adopt(catalogs);
const mcpServerLookupOrder = Array.from(new Set(catalogs.flatMap((catalog) => catalog.lookups)));
/** Keys whose first tool has been handled: their catalog is settled for the rest of the load. */
const builtKeys = new Set<string>();
for (const { toolName, serverKey: parsed } of selectedTools) {
if (parsed == null) {
if (!isBuiltInTool(toolName)) {
continue;
}
@ -225,47 +389,8 @@ export async function loadToolDefinitions(
continue;
}
if (toolName.startsWith(mcpServerPinPrefix)) {
continue;
}
expectedMCPToolCount++;
/** Keys carry the normalized server name (raw in pre-normalization data),
* so both spellings resolve the boundary. Resolution is DIRECT-FIRST: a
* server that resolves under the parsed name as-is wins (a user-DB
* server may be named exactly like an operator server's normalized
* form), and only when that yields nothing is the parsed name treated
* as a normalized spelling of a raw config name. The resolved RAW name
* feeds config lookups and definition metadata (`serverName`, then
* `mcpRawServerName`) — server instructions are keyed by it. */
const [, parsedServerName] = splitMCPToolKey(toolName, [
...(mcpServerNames ?? []),
...(rawServerNames ?? []),
]);
const parsed = parsedServerName ?? toolName;
if (!mcpServerToolsCache.has(parsed)) {
let resolvedName = parsed;
let fetched = await getOrFetchMCPServerTools(userId, parsed);
if (!fetched) {
/** Alias fallback is for "server not found" ONLY: when the parsed
* name is a known accessible server, a null fetch means it is
* temporarily unavailable (OAuth pending, missing user variables,
* disconnected) and rerouting to the alias would emit the OTHER
* server's definitions under this server's names. */
const parsedIsKnownServer = accessibleServerNames?.includes(parsed) === true;
const aliased = serverNameAliases.get(parsed);
if (!parsedIsKnownServer && aliased != null && aliased !== parsed) {
fetched = await getOrFetchMCPServerTools(userId, aliased);
if (fetched) {
resolvedName = aliased;
}
}
}
mcpServerToolsCache.set(parsed, fetched || {});
resolvedServerNames.set(parsed, resolvedName);
}
builtKeys.add(parsed);
const serverName = resolvedServerNames.get(parsed) ?? parsed;
let serverTools = mcpServerToolsCache.get(parsed);
@ -311,6 +436,14 @@ export async function loadToolDefinitions(
if (refreshedTools != null) {
mcpServerToolsCache.set(parsed, refreshedTools);
serverTools = refreshedTools;
/** The normalized and raw spellings of one server are separate keys. A key not handled
* yet that looked this server up resolves again, now that it is refreshed. */
const unbuiltKeys = Array.from(serverKeys).filter(
(key) => !builtKeys.has(key) && lookedUp.get(key)?.includes(serverName),
);
if (unbuiltKeys.length > 0) {
adopt(await resolveKeys(unbuiltKeys));
}
}
}
@ -375,19 +508,16 @@ export async function loadToolDefinitions(
}
const oauthActionToolNames: string[] = [];
if (actionToolNames.length > 0 && getActionToolDefinitions) {
const fetchedActionDefs = await getActionToolDefinitions(agentId, actionToolNames);
actionToolDefs = fetchedActionDefs.map((def) => {
if (def.oauth === true) {
oauthActionToolNames.push(def.name);
}
return {
name: def.name,
description: def.description,
parameters: def.parameters,
};
});
}
const actionToolDefs: ToolDefinition[] = fetchedActionDefs.map((def) => {
if (def.oauth === true) {
oauthActionToolNames.push(def.name);
}
return {
name: def.name,
description: def.description,
parameters: def.parameters,
};
});
const loadedTools = mcpToolDefs.map((def) =>
bindToolApproval(
@ -462,5 +592,6 @@ export async function loadToolDefinitions(
resolvedToolCount: resolvedMCPToolCount,
},
oauthActionToolNames,
mcpServerLookupOrder,
};
}

View file

@ -2790,7 +2790,7 @@ export const lookupConcurrencySchema = z.object({
permissionPrincipalLookups: lookupConcurrency,
/** Connected agents initialized together per level while discovering a handoff graph. */
connectedAgentLoads: lookupConcurrency,
/** MCP tool catalog reads when assembling an ephemeral or added agent. */
/** MCP tool catalog reads when assembling an agent's tools. */
mcpCatalogLookups: lookupConcurrency,
/** Model spec skill name resolutions. */
skillNameLookups: lookupConcurrency,