Skip to content

The open alternative to Salesforce, designed for AI.

Fix MCP tool calls reporting structured failures as success (#24280)

Etiennebcde5259f8da
diff --git a/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts
new file mode 100644
index 00000000000..042437cb467
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/services/__tests__/mcp-tool-executor.service.spec.ts
@@ -0,0 +1,123 @@
+import { Test, type TestingModule } from '@nestjs/testing';
+
+import { type ToolSet } from 'ai';
+
+import { McpToolExecutorService } from 'src/engine/api/mcp/services/mcp-tool-executor.service';
+import { MetricsService } from 'src/engine/core-modules/metrics/metrics.service';
+import { MetricsKeys } from 'src/engine/core-modules/metrics/types/metrics-keys.type';
+
+describe('McpToolExecutorService', () => {
+ let service: McpToolExecutorService;
+ let metricsService: jest.Mocked<MetricsService>;
+
+ const buildToolSet = (execute: jest.Mock): ToolSet =>
+ ({
+ create_person: {
+ description: 'Create a person',
+ inputSchema: {},
+ execute,
+ },
+ }) as unknown as ToolSet;
+
+ beforeEach(async () => {
+ metricsService = {
+ incrementCounterBy: jest.fn(),
+ recordHistogram: jest.fn(),
+ } as unknown as jest.Mocked<MetricsService>;
+
+ const module: TestingModule = await Test.createTestingModule({
+ providers: [
+ McpToolExecutorService,
+ {
+ provide: MetricsService,
+ useValue: metricsService,
+ },
+ ],
+ }).compile();
+
+ service = module.get(McpToolExecutorService);
+ });
+
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ describe('handleToolCall', () => {
+ it('should return isError false and count a success when the tool output succeeds', async () => {
+ const toolOutput = { success: true, message: 'Created' };
+ const toolSet = buildToolSet(jest.fn().mockResolvedValue(toolOutput));
+
+ const response = await service.handleToolCall(1, toolSet, {
+ name: 'create_person',
+ arguments: {},
+ });
+
+ expect(response).toEqual({
+ id: 1,
+ jsonrpc: '2.0',
+ result: {
+ content: [{ type: 'text', text: JSON.stringify(toolOutput) }],
+ isError: false,
+ },
+ });
+ expect(metricsService.incrementCounterBy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ key: MetricsKeys.McpToolExecutionSucceeded,
+ }),
+ );
+ });
+
+ it('should return isError true and count a failure when the tool output resolves with success false', async () => {
+ const toolOutput = {
+ success: false,
+ message: 'Validation failed',
+ error: 'Missing required field',
+ };
+ const toolSet = buildToolSet(jest.fn().mockResolvedValue(toolOutput));
+
+ const response = await service.handleToolCall(1, toolSet, {
+ name: 'create_person',
+ arguments: {},
+ });
+
+ expect(response).toEqual({
+ id: 1,
+ jsonrpc: '2.0',
+ result: {
+ content: [{ type: 'text', text: JSON.stringify(toolOutput) }],
+ isError: true,
+ },
+ });
+ expect(metricsService.incrementCounterBy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ key: MetricsKeys.McpToolExecutionFailed,
+ }),
+ );
+ });
+
+ it('should return isError true and count a failure when the tool throws', async () => {
+ const toolSet = buildToolSet(
+ jest.fn().mockRejectedValue(new Error('Database unavailable')),
+ );
+
+ const response = await service.handleToolCall(1, toolSet, {
+ name: 'create_person',
+ arguments: {},
+ });
+
+ expect(response).toEqual({
+ id: 1,
+ jsonrpc: '2.0',
+ result: {
+ content: [{ type: 'text', text: 'Database unavailable' }],
+ isError: true,
+ },
+ });
+ expect(metricsService.incrementCounterBy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ key: MetricsKeys.McpToolExecutionFailed,
+ }),
+ );
+ });
+ });
+});
diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts
index c8ac97bb4fc..777891d8da2 100644
--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts
+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-tool-executor.service.ts
@@ -117,7 +117,7 @@ export class McpToolExecutorService {
return wrapJsonRpcResponse(id, {
result: {
content: [{ type: 'text', text: JSON.stringify(result) }],
- isError: false,
+ isError: !succeeded,
},
});
} catch (executionError) {
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-tool-catalog.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-tool-catalog.integration-spec.ts
index 7ffd3aa252e..b54e58c9371 100644
--- a/packages/twenty-server/test/integration/ai/suites/mcp-tool-catalog.integration-spec.ts
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-tool-catalog.integration-spec.ts
@@ -11,8 +11,11 @@ import { ToolCategory } from 'twenty-shared/ai';
* Contract tests for the MCP tool catalog.
*
* 1. Catalog contract: every category advertised by get_tool_catalog must be
- * dispatchable end to end through execute_tool. Scales automatically: a
- * newly registered provider is covered the moment it appears in the
+ * dispatchable end to end through execute_tool. Dispatchable means the
+ * registry resolves and executes the tool: a structured business failure
+ * (e.g. a search tool rejecting empty arguments) still proves dispatch,
+ * only "not found" / "not available" outputs do not. Scales automatically:
+ * a newly registered provider is covered the moment it appears in the
* catalog, with no new test code.
* 2. Permission gating: the catalog is role-dependent. An API key bound to a
* role without settings permissions must not see settings-gated tools
@@ -62,6 +65,31 @@ const getToolCatalog = async (
const READ_ONLY_TOOL_NAME_PATTERN = /^(find_|list_|get_|search_)/;
+// Dispatch-layer failures come from execute_tool gating or the registry
+// (unknown or unavailable tool), not from the executed tool itself. Their
+// exact wording is pinned by the "should report unknown tools as dispatch
+// failures" control test below, so drift fails loudly instead of silently
+// weakening the catalog contract.
+const DISPATCH_FAILURE_MESSAGE_PATTERN =
+ /^Tool ".+" (not found|is not available)$/;
+
+const isDispatchFailure = (result: {
+ content: { type: string; text: string }[];
+}): boolean => {
+ let output: { success?: boolean; message?: string };
+
+ try {
+ output = JSON.parse(result.content[0].text);
+ } catch {
+ return false;
+ }
+
+ return (
+ output.success === false &&
+ DISPATCH_FAILURE_MESSAGE_PATTERN.test(output.message ?? '')
+ );
+};
+
// Deliberate exceptions to the "every advertised category is dispatchable
// through a read-only tool" contract. Currently none: every category the MCP
// catalog advertises ships at least one read-only tool. Adding a category
@@ -197,7 +225,11 @@ describe('MCP tool catalog (integration)', () => {
arguments: {},
});
- if (!result.isError) {
+ // Called with empty arguments, a resolved tool may legitimately
+ // return a structured failure (isError true since the MCP layer
+ // surfaces success: false); only a dispatch-layer failure means the
+ // category is advertised but not actually wired up.
+ if (!isDispatchFailure(result)) {
dispatched = true;
break;
}
@@ -215,6 +247,16 @@ describe('MCP tool catalog (integration)', () => {
EXPECTED_CATEGORIES_WITHOUT_READ_ONLY_TOOLS,
);
});
+
+ it('should report unknown tools as dispatch failures', async () => {
+ const result = await callMcpTool(adminApiKeyToken, 'execute_tool', {
+ toolName: 'definitely_not_a_registered_tool',
+ arguments: {},
+ });
+
+ expect(result.isError).toBe(true);
+ expect(isDispatchFailure(result)).toBe(true);
+ });
});
describe('permission gating', () => {