Skip to content

The open alternative to Salesforce, designed for AI.

fix(mcp): mark database read tools read-only in direct mode (#27310)

UDIT_SINGH@076526f87f1796
diff --git a/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.const.ts b/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.const.ts
new file mode 100644
index 00000000000..cb51e9c9c88
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.const.ts
@@ -0,0 +1,20 @@
+import { MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const';
+import { MCP_EXECUTE_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-execute-tool-annotations.const';
+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';
+import { type DatabaseCrudOperation } from 'src/engine/core-modules/tool-provider/constants/database-crud-operation.const';
+
+export const MCP_DATABASE_CRUD_TOOL_ANNOTATIONS: Record<
+ DatabaseCrudOperation,
+ McpToolAnnotations
+> = {
+ find_many: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,
+ find_one: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,
+ group_by: MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS,
+ create_one: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ create_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ update_one: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ update_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ upsert_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ delete_one: MCP_EXECUTE_TOOL_ANNOTATIONS,
+ delete_many: MCP_EXECUTE_TOOL_ANNOTATIONS,
+};
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 a7eb5a514f0..f3e69185bfe 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
@@ -27,6 +27,7 @@ import {
listSkillsInputSchema,
} from 'src/engine/api/mcp/tools/list-skills.tool';
import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';
+import { getMcpRegistryToolAnnotations } from 'src/engine/api/mcp/utils/get-mcp-registry-tool-annotations.util';
import { wrapJsonRpcResponse } from 'src/engine/api/mcp/utils/wrap-jsonrpc-response.util';
import { ApiKeyRoleService } from 'src/engine/core-modules/api-key/services/api-key-role.service';
import { type FlatApiKey } from 'src/engine/core-modules/api-key/types/flat-api-key.type';
@@ -454,25 +455,35 @@ export class McpProtocolService {
...nativeTools
} = toolSet;
- const registryTools = await Sentry.startSpan(
+ const annotatedRegistryTools = await Sentry.startSpan(
{
name: 'mcp list registry tools',
op: 'mcp.tools',
onlyIfParent: true,
},
- () =>
- this.toolRegistry.getToolsByCategories(toolContext, {
- excludeTools: [...MCP_EXCLUDED_TOOL_NAMES],
- }),
- );
+ async () => {
+ const descriptors =
+ await this.toolRegistry.getDescriptorsByCategories(toolContext, {
+ excludeTools: [...MCP_EXCLUDED_TOOL_NAMES],
+ });
+
+ const registryTools = this.toolRegistry.hydrateToolSet(
+ descriptors,
+ toolContext,
+ );
- const annotatedRegistryTools = Object.fromEntries(
- Object.entries(registryTools).map(
- ([toolName, registryTool]): [string, McpAnnotatedTool] => [
- toolName,
- { ...registryTool, annotations: MCP_EXECUTE_TOOL_ANNOTATIONS },
- ],
- ),
+ return Object.fromEntries(
+ descriptors.map((descriptor): [string, McpAnnotatedTool] => [
+ descriptor.name,
+ {
+ ...registryTools[descriptor.name],
+ annotations: getMcpRegistryToolAnnotations(
+ descriptor.executionRef,
+ ),
+ },
+ ]),
+ );
+ },
);
return this.mcpToolExecutorService.handleToolsListing(id, {
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts
new file mode 100644
index 00000000000..22621dafe96
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/get-mcp-registry-tool-annotations.util.spec.ts
@@ -0,0 +1,55 @@
+import { MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const';
+import { MCP_EXECUTE_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-execute-tool-annotations.const';
+import { getMcpRegistryToolAnnotations } from 'src/engine/api/mcp/utils/get-mcp-registry-tool-annotations.util';
+import { type DatabaseCrudOperation } from 'src/engine/core-modules/tool-provider/constants/database-crud-operation.const';
+import { type ToolExecutionRef } from 'src/engine/core-modules/tool-provider/types/tool-execution-ref.type';
+
+describe('getMcpRegistryToolAnnotations', () => {
+ it.each<[DatabaseCrudOperation]>([['find_many'], ['find_one'], ['group_by']])(
+ 'should return closed world read-only annotations for the database read operation %p',
+ (operation) => {
+ expect(
+ getMcpRegistryToolAnnotations({
+ kind: 'database_crud',
+ objectNameSingular: 'person',
+ operation,
+ }),
+ ).toEqual(MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS);
+ },
+ );
+
+ it.each<[DatabaseCrudOperation]>([
+ ['create_one'],
+ ['create_many'],
+ ['update_one'],
+ ['update_many'],
+ ['upsert_many'],
+ ['delete_one'],
+ ['delete_many'],
+ ])(
+ 'should return execute annotations for the database write operation %p',
+ (operation) => {
+ expect(
+ getMcpRegistryToolAnnotations({
+ kind: 'database_crud',
+ objectNameSingular: 'person',
+ operation,
+ }),
+ ).toEqual(MCP_EXECUTE_TOOL_ANNOTATIONS);
+ },
+ );
+
+ it.each<[ToolExecutionRef]>([
+ [{ kind: 'static', toolId: 'get_view_fields' }],
+ [
+ {
+ kind: 'logic_function',
+ logicFunctionId: '20202020-0000-4000-8000-000000000001',
+ },
+ ],
+ ])('should return execute annotations for %p', (executionRef) => {
+ expect(getMcpRegistryToolAnnotations(executionRef)).toEqual(
+ MCP_EXECUTE_TOOL_ANNOTATIONS,
+ );
+ });
+});
diff --git a/packages/twenty-server/src/engine/api/mcp/utils/get-mcp-registry-tool-annotations.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/get-mcp-registry-tool-annotations.util.ts
new file mode 100644
index 00000000000..44384ef5711
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/mcp/utils/get-mcp-registry-tool-annotations.util.ts
@@ -0,0 +1,11 @@
+import { MCP_DATABASE_CRUD_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-database-crud-tool-annotations.const';
+import { MCP_EXECUTE_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-execute-tool-annotations.const';
+import { type McpToolAnnotations } from 'src/engine/api/mcp/types/mcp-tool-annotations.type';
+import { type ToolExecutionRef } from 'src/engine/core-modules/tool-provider/types/tool-execution-ref.type';
+
+export const getMcpRegistryToolAnnotations = (
+ executionRef: ToolExecutionRef,
+): McpToolAnnotations =>
+ executionRef.kind === 'database_crud'
+ ? MCP_DATABASE_CRUD_TOOL_ANNOTATIONS[executionRef.operation]
+ : MCP_EXECUTE_TOOL_ANNOTATIONS;
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 3bdeaf2fb24..e0c34f25583 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
@@ -401,13 +401,36 @@ export class ToolRegistryService {
);
}
- // MCP and the workflow agent need full schemas.
async getToolsByCategories(
context: ToolProviderContext,
options: ToolRetrievalOptions = {},
): Promise<ToolSet> {
const { categories, excludeTools, compactOutput, spillLargeOutput } =
options;
+
+ const descriptors = await this.getDescriptorsByCategories(context, {
+ categories,
+ excludeTools,
+ });
+
+ const toolSet = this.hydrateToolSet(descriptors, context, {
+ compactOutput,
+ spillLargeOutput,
+ });
+
+ this.logger.log(
+ `Generated ${Object.keys(toolSet).length} tools for categories: [${categories?.join(', ') ?? 'all'}]`,
+ );
+
+ return toolSet;
+ }
+
+ // MCP and the workflow agent need full schemas.
+ async getDescriptorsByCategories(
+ context: ToolProviderContext,
+ options: Pick<ToolRetrievalOptions, 'categories' | 'excludeTools'> = {},
+ ): Promise<ToolDescriptor[]> {
+ const { categories, excludeTools } = options;
const categorySet = categories ? new Set(categories) : undefined;
const results = await Promise.all(
@@ -438,16 +461,7 @@ export class ToolRegistryService {
);
}
- const toolSet = this.hydrateToolSet(filteredDescriptors, context, {
- compactOutput,
- spillLargeOutput,
- });
-
- this.logger.log(
- `Generated ${Object.keys(toolSet).length} tools for categories: [${categories?.join(', ') ?? 'all'}]`,
- );
-
- return toolSet;
+ return filteredDescriptors;
}
private generateProviderDescriptors(
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 c625b748097..fae35ecc998 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
@@ -80,7 +80,17 @@ const EXPECTED_CATEGORIES_WITHOUT_READ_ONLY_TOOLS: string[] = [];
const listMcpTools = async (
bearer: string,
path: string,
-): Promise<{ name: string; inputSchema: { type?: string } }[]> => {
+): Promise<
+ {
+ name: string;
+ inputSchema: { type?: string };
+ annotations?: {
+ readOnlyHint: boolean;
+ openWorldHint: boolean;
+ destructiveHint: boolean;
+ };
+ }[]
+> => {
const response = await postMcp(
{ jsonrpc: '2.0', method: 'tools/list', id: '1' },
bearer,
@@ -346,6 +356,26 @@ describe('MCP tool catalog (integration)', () => {
expect(isDispatchFailure(result)).toBe(true);
});
+ it('should mark database read tools read-only and keep execute hints on writes', async () => {
+ const annotationsByToolName = Object.fromEntries(
+ (await listMcpTools(adminApiKeyToken, DIRECT_MODE_PATH)).map((tool) => [
+ tool.name,
+ tool.annotations,
+ ]),
+ );
+
+ expect(annotationsByToolName.find_many_people).toEqual({
+ readOnlyHint: true,
+ openWorldHint: false,
+ destructiveHint: false,
+ });
+ expect(annotationsByToolName.create_one_person).toEqual({
+ readOnlyHint: false,
+ openWorldHint: true,
+ destructiveHint: false,
+ });
+ });
+
it('should keep plain /mcp on the meta-tools', async () => {
const toolNames = (await listMcpTools(adminApiKeyToken, '/mcp')).map(
(tool) => tool.name,