Skip to content

The open alternative to Salesforce, designed for AI.

feat(mcp): log the JSON-RPC method and tool name and trace tool generation (#27160)

Charles Bochet00bb86761075
diff --git a/packages/twenty-server/@types/express.d.ts b/packages/twenty-server/@types/express.d.ts
index a074781fea3..d03132f22d9 100644
--- a/packages/twenty-server/@types/express.d.ts
+++ b/packages/twenty-server/@types/express.d.ts
@@ -28,5 +28,7 @@ declare module 'express-serve-static-core' {
tokenType?: JwtTokenTypeEnum;
authenticatedAt?: Date;
executedRootResolvers?: string[];
+ mcpMethod?: string;
+ mcpToolName?: string;
}
}
diff --git a/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts b/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts
index f92e9c51944..83252a1acc5 100644
--- a/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts
+++ b/packages/twenty-server/src/engine/api/mcp/controllers/__tests__/mcp-core.controller.spec.ts
@@ -72,6 +72,8 @@ describe('McpCoreController', () => {
const mockUser = { id: 'user-1' } as UserEntity;
const mockUserWorkspaceId = 'user-workspace-1';
const mockApiKey = { id: 'api-key-1' } as FlatApiKey;
+ const mockHttpRequest = {} as import('express').Request;
+
const mockRes = {
status: jest.fn().mockReturnThis(),
setHeader: jest.fn(),
@@ -113,6 +115,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
undefined,
+ mockHttpRequest,
mockRes,
);
@@ -128,6 +131,10 @@ describe('McpCoreController', () => {
},
);
expect(result).toEqual(mockResponse);
+ expect(mockHttpRequest).toMatchObject({
+ mcpMethod: 'tools/call',
+ mcpToolName: 'testTool',
+ });
});
it('should handle initialize method', async () => {
@@ -162,6 +169,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
undefined,
+ mockHttpRequest,
mockRes,
);
@@ -210,6 +218,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
undefined,
+ mockHttpRequest,
mockRes,
);
@@ -243,6 +252,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
undefined,
+ mockHttpRequest,
mockRes,
);
@@ -277,6 +287,7 @@ describe('McpCoreController', () => {
undefined,
undefined,
undefined,
+ mockHttpRequest,
mockRes,
);
@@ -320,6 +331,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
'application/json, text/event-stream',
+ mockHttpRequest,
mockRes,
);
@@ -381,6 +393,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
'application/json',
+ mockHttpRequest,
mockRes,
);
@@ -406,6 +419,7 @@ describe('McpCoreController', () => {
mockUserWorkspaceId,
undefined,
'application/json, text/event-stream',
+ mockHttpRequest,
mockRes,
);
diff --git a/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts b/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts
index 77fc0fc6e6d..f8d1df71d08 100644
--- a/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts
+++ b/packages/twenty-server/src/engine/api/mcp/controllers/mcp-core.controller.ts
@@ -6,6 +6,7 @@ import {
HttpStatus,
Post,
Query,
+ Req,
Res,
UseFilters,
UseGuards,
@@ -13,13 +14,15 @@ import {
ValidationPipe,
} from '@nestjs/common';
-import { type Response } from 'express';
+import * as Sentry from '@sentry/node';
+import { type Request, type Response } from 'express';
import { ApiPath } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
import { JsonRpc } from 'src/engine/api/mcp/dtos/json-rpc';
import { McpAuthGuard } from 'src/engine/api/mcp/guards/mcp-auth.guard';
import { McpProtocolService } from 'src/engine/api/mcp/services/mcp-protocol.service';
+import { getMcpRequestLogFields } from 'src/engine/api/mcp/utils/get-mcp-request-log-fields.util';
import { writeSseEvent } from 'src/engine/api/mcp/utils/write-sse-event.util';
import { RestApiExceptionFilter } from 'src/engine/api/rest/rest-api-exception.filter';
import { AuthRestApiExceptionFilter } from 'src/engine/core-modules/auth/filters/auth-rest-api-exception.filter';
@@ -76,9 +79,21 @@ export class McpCoreController {
@AuthApplication({ allowUndefined: true })
application: FlatApplication | undefined,
@Headers('accept') acceptHeader: string | undefined,
+ @Req() request: Request,
@Res({ passthrough: true }) res: Response,
@Query('mode') mode?: string,
) {
+ const { method: mcpMethod, toolName: mcpToolName } =
+ getMcpRequestLogFields(body);
+
+ request.mcpMethod = mcpMethod;
+ request.mcpToolName = mcpToolName;
+
+ Sentry.getActiveSpan()?.setAttributes({
+ ...(isDefined(mcpMethod) && { 'mcp.method': mcpMethod }),
+ ...(isDefined(mcpToolName) && { 'mcp.tool_name': mcpToolName }),
+ });
+
const authContext = {
workspace,
userId: user?.id,
diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts
index b66aa69d4a0..a7eb5a514f0 100644
--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts
+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts
@@ -1,5 +1,6 @@
import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
+import * as Sentry from '@sentry/node';
import { isNonEmptyString } from '@sniptt/guards';
import { type ToolSet, zodSchema } from 'ai';
import { type ActorMetadata, FieldActorSource } from 'twenty-shared/types';
@@ -401,17 +402,16 @@ export class McpProtocolService {
? buildApiKeyAuthContext({ workspace, apiKey })
: undefined;
- const { toolSet, toolContext } = await this.buildMcpToolSet(
- workspace,
- roleId,
- rolePermissionConfig,
- {
- authContext,
- application,
- userId,
- userWorkspaceId,
- apiKey,
- },
+ const { toolSet, toolContext } = await Sentry.startSpan(
+ { name: 'mcp build tool set', op: 'mcp.tools', onlyIfParent: true },
+ () =>
+ this.buildMcpToolSet(workspace, roleId, rolePermissionConfig, {
+ authContext,
+ application,
+ userId,
+ userWorkspaceId,
+ apiKey,
+ }),
);
if (method === 'tools/call') {
@@ -454,9 +454,16 @@ export class McpProtocolService {
...nativeTools
} = toolSet;
- const registryTools = await this.toolRegistry.getToolsByCategories(
- toolContext,
- { excludeTools: [...MCP_EXCLUDED_TOOL_NAMES] },
+ const registryTools = await Sentry.startSpan(
+ {
+ name: 'mcp list registry tools',
+ op: 'mcp.tools',
+ onlyIfParent: true,
+ },
+ () =>
+ this.toolRegistry.getToolsByCategories(toolContext, {
+ excludeTools: [...MCP_EXCLUDED_TOOL_NAMES],
+ }),
);
const annotatedRegistryTools = Object.fromEntries(
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-request-log-fields.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-request-log-fields.util.spec.ts
new file mode 100644
index 00000000000..623ba3092f2
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-request-log-fields.util.spec.ts
@@ -0,0 +1,49 @@
+import { getMcpRequestLogFields } from 'src/engine/api/mcp/utils/get-mcp-request-log-fields.util';
+
+describe('getMcpRequestLogFields', () => {
+ it('should return the method and the called tool name', () => {
+ expect(
+ getMcpRequestLogFields({
+ method: 'tools/call',
+ params: { name: 'find_many_people', arguments: {} },
+ }),
+ ).toEqual({ method: 'tools/call', toolName: 'find_many_people' });
+ });
+
+ it('should return the tool executed through execute_tool', () => {
+ expect(
+ getMcpRequestLogFields({
+ method: 'tools/call',
+ params: {
+ name: 'execute_tool',
+ arguments: { toolName: 'create_one_company', arguments: {} },
+ },
+ }).toolName,
+ ).toBe('create_one_company');
+ });
+
+ it('should not return a tool name for other methods', () => {
+ expect(getMcpRequestLogFields({ method: 'tools/list' })).toEqual({
+ method: 'tools/list',
+ toolName: undefined,
+ });
+ });
+
+ it('should drop values that do not look like a method or tool name', () => {
+ expect(
+ getMcpRequestLogFields({
+ method: 'tools/call',
+ params: { name: 'find_many_people\nfake=line', arguments: {} },
+ }).toolName,
+ ).toBeUndefined();
+ expect(
+ getMcpRequestLogFields({ method: 'x'.repeat(129) }).method,
+ ).toBeUndefined();
+ });
+
+ it('should keep values at the length limit', () => {
+ expect(getMcpRequestLogFields({ method: 'x'.repeat(128) }).method).toBe(
+ 'x'.repeat(128),
+ );
+ });
+});
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/get-mcp-request-log-fields.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/get-mcp-request-log-fields.util.ts
new file mode 100644
index 00000000000..d7649ab16c7
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/utils/get-mcp-request-log-fields.util.ts
@@ -0,0 +1,30 @@
+import { isNonEmptyString } from '@sniptt/guards';
+
+import { type JsonRpc } from 'src/engine/api/mcp/dtos/json-rpc';
+import { resolveToolName } from 'src/engine/core-modules/tool-provider/utils/resolve-tool-name.util';
+
+const MAX_MCP_LOG_FIELD_LENGTH = 128;
+const MCP_LOG_FIELD_PATTERN = /^[A-Za-z0-9_.:/-]+$/;
+
+const toLoggableValue = (value: string | undefined) =>
+ isNonEmptyString(value) &&
+ value.length <= MAX_MCP_LOG_FIELD_LENGTH &&
+ MCP_LOG_FIELD_PATTERN.test(value)
+ ? value
+ : undefined;
+
+export const getMcpRequestLogFields = ({
+ method,
+ params,
+}: Pick<JsonRpc, 'method' | 'params'>): {
+ method?: string;
+ toolName?: string;
+} => ({
+ method: toLoggableValue(method),
+ toolName:
+ method === 'tools/call' && isNonEmptyString(params?.name)
+ ? toLoggableValue(
+ resolveToolName({ toolName: params.name, input: params.arguments }),
+ )
+ : undefined,
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts
index 15576f53f17..7b7a2b5ff0e 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts
@@ -1,11 +1,14 @@
import { Inject, Injectable, Logger } from '@nestjs/common';
+import * as Sentry from '@sentry/node';
import { type ToolSet, jsonSchema } from 'ai';
import { type ToolCategory } from 'twenty-shared/ai';
import { type APP_LOCALES } from 'twenty-shared/translations';
+import { isDefined } from 'twenty-shared/utils';
import { type FlatApplication } from 'src/engine/core-modules/application/types/flat-application.type';
import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type GenerateDescriptorOptions } from 'src/engine/core-modules/tool-provider/interfaces/generate-descriptor-options.type';
import { type ToolProvider } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider.interface';
import { type ToolRetrievalOptions } from 'src/engine/core-modules/tool-provider/interfaces/tool-retrieval-options.type';
@@ -53,7 +56,7 @@ export class ToolRegistryService {
}
if (await provider.isAvailable(executionContext)) {
- return provider.generateDescriptors(executionContext, {
+ return this.generateProviderDescriptors(provider, executionContext, {
includeSchemas: false,
});
}
@@ -105,10 +108,11 @@ export class ToolRegistryService {
const entryNameSet = new Set(entries.map((entry) => entry.name));
- const descriptors = await provider.generateDescriptors(executionContext, {
- includeSchemas: true,
- toolNames: entryNameSet,
- });
+ const descriptors = await this.generateProviderDescriptors(
+ provider,
+ executionContext,
+ { includeSchemas: true, toolNames: entryNameSet },
+ );
for (const descriptor of descriptors) {
if (
@@ -402,7 +406,7 @@ export class ToolRegistryService {
)
.map(async (provider) => {
if (await provider.isAvailable(context)) {
- return provider.generateDescriptors(context, {
+ return this.generateProviderDescriptors(provider, context, {
includeSchemas: true,
});
}
@@ -435,6 +439,37 @@ export class ToolRegistryService {
return toolSet;
}
+ private generateProviderDescriptors(
+ provider: ToolProvider,
+ context: ToolProviderContext,
+ options: GenerateDescriptorOptions,
+ ): Promise<(ToolIndexEntry | ToolDescriptor)[]> {
+ return Sentry.startSpan(
+ {
+ name: `tool provider ${provider.category} descriptors`,
+ op: 'tool.descriptors',
+ onlyIfParent: true,
+ attributes: {
+ 'tool.category': provider.category,
+ 'tool.include_schemas': options.includeSchemas ?? false,
+ ...(isDefined(options.toolNames) && {
+ 'tool.requested_count': options.toolNames.size,
+ }),
+ },
+ },
+ async (span) => {
+ const descriptors = await provider.generateDescriptors(
+ context,
+ options,
+ );
+
+ span.setAttribute('tool.descriptor_count', descriptors.length);
+
+ return descriptors;
+ },
+ );
+ }
+
private buildContextFromToolContext(
context: ToolContext,
): ToolProviderContext {
diff --git a/packages/twenty-server/src/engine/middlewares/utils/__tests__/build-api-access-log-line.util.spec.ts b/packages/twenty-server/src/engine/middlewares/utils/__tests__/build-api-access-log-line.util.spec.ts
index 6ab4c3dbf75..94d33a7b259 100644
--- a/packages/twenty-server/src/engine/middlewares/utils/__tests__/build-api-access-log-line.util.spec.ts
+++ b/packages/twenty-server/src/engine/middlewares/utils/__tests__/build-api-access-log-line.util.spec.ts
@@ -127,6 +127,26 @@ describe('buildApiAccessLogLine', () => {
expect(line).not.toContain('actor_id=');
});
+ it('should log the MCP method and tool name', () => {
+ const line = build({
+ request: {
+ originalUrl: '/mcp',
+ mcpMethod: 'tools/call',
+ mcpToolName: 'find_many_people',
+ },
+ });
+
+ expect(line).toContain('mcp_method=tools/call');
+ expect(line).toContain('mcp_tool=find_many_people');
+ });
+
+ it('should omit MCP fields for a non MCP request', () => {
+ const line = build();
+
+ expect(line).not.toContain('mcp_method=');
+ expect(line).not.toContain('mcp_tool=');
+ });
+
it('should log the resolvers captured by the graphql pipelines', () => {
const line = build({
request: {
diff --git a/packages/twenty-server/src/engine/middlewares/utils/build-api-access-log-line.util.ts b/packages/twenty-server/src/engine/middlewares/utils/build-api-access-log-line.util.ts
index f5437709730..f66f1fb111b 100644
--- a/packages/twenty-server/src/engine/middlewares/utils/build-api-access-log-line.util.ts
+++ b/packages/twenty-server/src/engine/middlewares/utils/build-api-access-log-line.util.ts
@@ -27,6 +27,8 @@ export const buildApiAccessLogLine = ({
method: request.method,
url_path: urlPath,
resolvers: formatResolvers(request.executedRootResolvers),
+ mcp_method: request.mcpMethod,
+ mcp_tool: request.mcpToolName,
status: completed ? response.statusCode : undefined,
aborted: completed ? undefined : true,
duration_ms: durationMs,