Skip to content

The open alternative to Salesforce, designed for AI.

Let applications declare MCP servers in their manifest (#29158)

martmull1b50317c113e
diff --git a/packages/twenty-agent-skills/references/develop-app/logic.md b/packages/twenty-agent-skills/references/develop-app/logic.md
index 26dfa2d1be9..afc2bfb24ef 100644
--- a/packages/twenty-agent-skills/references/develop-app/logic.md
+++ b/packages/twenty-agent-skills/references/develop-app/logic.md
@@ -113,6 +113,16 @@ To let members reply to an app's message channels, declare `defineMessagingProvi
- The send function receives `{ messagingProviderName, connectedAccountId, messageChannelId, threadExternalId, text, idempotencyKey, recipients }` (type `SendAppMessagePayload`; `recipients` are the latest message's participants), must deliver the reply and return `{ externalId, sentAt? }`. Twenty then records it in the thread, and a later ingestion of the same `externalId` is a no-op. Throw on failure so nothing is recorded. A `sendAppChannelMessage` retry with the same `idempotencyKey` records the delivered reply without calling the function again; forward the key to the provider when it supports idempotent sends.
- Declare one messaging provider per kind of messaging (LinkedIn, WhatsApp) even when they share a connection provider. Its connection provider cannot change after the first sync; declare a new one with a new `universalIdentifier` instead. Requires `"engines": { "twenty": ">=2.52.0" }`.
+## MCP Servers
+
+Beta: MCP servers are not live yet. Workspaces cannot use their tools until the feature ships, so do not build a feature that depends on them.
+
+To let the workspace's AI call a remote MCP server (Streamable HTTP) without syncing its data into Twenty, declare `defineMcpServer` with a snake_case `name` (lowercase letters, digits and underscores, starting with a letter, at most 32 characters; it prefixes the server's tool names), a `label` and an HTTP(S) `url`:
+
+- To authenticate, set `connectionProvider: { universalIdentifier }` to a connection provider of the same app; calls send that connection's access token as a Bearer token. Omit it for a public server.
+- The `url` cannot change in a later version while a connection provider is linked; declare a new server with a new `universalIdentifier` instead.
+- Workspaces can deactivate a server and a later app version keeps that choice. Requires `"engines": { "twenty": ">=2.53.0" }`.
+
## Post-Install Hooks
Use `definePostInstallLogicFunction` for records that must exist on install — default workflows, views, roles, or seeded reference data. Do not implement this as runtime first-run code.
diff --git a/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap b/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap
index e30cd11882c..7006c711ca7 100644
--- a/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap
+++ b/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap
@@ -15,6 +15,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"logicFunctions": [
"src/logic-functions/add-numbers.function.ts",
],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [],
"objects": [],
@@ -78,6 +79,7 @@ The scripts invoke that local build directly, so the SDK binary cannot shadow it
"universalIdentifier": "f9e5589c-e951-4d99-85db-0a305ab53502",
},
],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [],
"objects": [],
@@ -148,6 +150,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"logicFunctions": [
"my.function.ts",
],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [],
"objects": [
@@ -212,6 +215,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000010",
},
],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [],
"objects": [
@@ -322,6 +326,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"src/logic-functions/test-function.function.ts",
"src/root.function.ts",
],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [
"src/navigation-menu-items/post-card-recipients.navigation-menu-item.ts",
@@ -880,6 +885,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"universalIdentifier": "f0f1f2f3-f4f5-4000-8000-000000000001",
},
],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [
{
@@ -1424,6 +1430,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
],
"indexes": [],
"logicFunctions": [],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [],
"objects": [],
@@ -1480,6 +1487,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
],
"indexes": [],
"logicFunctions": [],
+ "mcpServers": [],
"messagingProviders": [],
"navigationMenuItems": [],
"objects": [],
diff --git a/packages/twenty-cli/src/app/manifest/__tests__/manifest-validate.spec.ts b/packages/twenty-cli/src/app/manifest/__tests__/manifest-validate.spec.ts
index e1ea158f1ed..098bdbae54f 100644
--- a/packages/twenty-cli/src/app/manifest/__tests__/manifest-validate.spec.ts
+++ b/packages/twenty-cli/src/app/manifest/__tests__/manifest-validate.spec.ts
@@ -423,6 +423,41 @@ describe('manifestValidate', () => {
expect(result.errors).toHaveLength(0);
});
+ it('should not flag an MCP server referencing its connection provider as a duplicate', () => {
+ const connectionProviderId = '550e8400-e29b-41d4-a716-446655440048';
+
+ const result = manifestValidate({
+ ...validManifest,
+ connectionProviders: [
+ {
+ universalIdentifier: connectionProviderId,
+ name: 'github',
+ displayName: 'GitHub',
+ type: 'oauth',
+ oauth: {
+ authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+ tokenEndpoint: 'https://github.com/login/oauth/access_token',
+ scopes: ['repo'],
+ clientIdVariable: 'GITHUB_CLIENT_ID',
+ clientSecretVariable: 'GITHUB_CLIENT_SECRET',
+ },
+ },
+ ],
+ mcpServers: [
+ {
+ universalIdentifier: '550e8400-e29b-41d4-a716-446655440049',
+ name: 'github',
+ label: 'GitHub',
+ url: 'https://api.githubcopilot.com/mcp/',
+ connectionProvider: { universalIdentifier: connectionProviderId },
+ },
+ ],
+ });
+
+ expect(result.isValid).toBe(true);
+ expect(result.errors).toHaveLength(0);
+ });
+
it('should not flag a custom connection provider referencing its authorize and callback logic functions as duplicates', () => {
const authorizeLogicFunctionId = '550e8400-e29b-41d4-a716-446655440042';
const callbackLogicFunctionId = '550e8400-e29b-41d4-a716-446655440043';
diff --git a/packages/twenty-cli/src/app/manifest/manifest-build.ts b/packages/twenty-cli/src/app/manifest/manifest-build.ts
index 9e649b53562..6fcb346a396 100644
--- a/packages/twenty-cli/src/app/manifest/manifest-build.ts
+++ b/packages/twenty-cli/src/app/manifest/manifest-build.ts
@@ -39,6 +39,7 @@ import {
ASSETS_DIR,
type CommandMenuItemManifest,
type ConnectionProviderManifest,
+ type McpServerManifest,
type MessagingProviderManifest,
type FieldManifest,
type FrontComponentManifest,
@@ -114,6 +115,7 @@ export const buildManifest = async (
const workflows: WorkflowManifest[] = [];
const connectionProviders: ConnectionProviderManifest[] = [];
const messagingProviders: MessagingProviderManifest[] = [];
+ const mcpServers: McpServerManifest[] = [];
const logicFunctions: LogicFunctionManifest[] = [];
const frontComponents: FrontComponentManifest[] = [];
const publicAssets: AssetManifest[] = [];
@@ -147,6 +149,7 @@ export const buildManifest = async (
const workflowsFilePaths: string[] = [];
const connectionProvidersFilePaths: string[] = [];
const messagingProvidersFilePaths: string[] = [];
+ const mcpServersFilePaths: string[] = [];
const logicFunctionsFilePaths: string[] = [];
const frontComponentsFilePaths: string[] = [];
const publicAssetsFilePaths: string[] = [];
@@ -300,6 +303,17 @@ export const buildManifest = async (
messagingProvidersFilePaths.push(relativePath);
break;
}
+ case 'mcpServers': {
+ const extract = await extractManifestFromFile<McpServerManifest>({
+ appPath,
+ filePath,
+ });
+ mcpServers.push(extract.config);
+ errors.push(...extract.errors);
+ warnings.push(...(extract.warnings ?? []));
+ mcpServersFilePaths.push(relativePath);
+ break;
+ }
case 'logicFunctions': {
const extract = await extractManifestFromFile<LogicFunctionConfig>({
appPath,
@@ -721,6 +735,7 @@ export const buildManifest = async (
workflows: workflows.sort(byId),
connectionProviders: connectionProviders.sort(byId),
messagingProviders: messagingProviders.sort(byId),
+ mcpServers: mcpServers.sort(byId),
logicFunctions: logicFunctions.sort(byId),
frontComponents: frontComponents.sort(byId),
publicAssets: publicAssets.sort(byPath),
@@ -747,6 +762,7 @@ export const buildManifest = async (
workflows: workflowsFilePaths,
connectionProviders: connectionProvidersFilePaths,
messagingProviders: messagingProvidersFilePaths,
+ mcpServers: mcpServersFilePaths,
logicFunctions: logicFunctionsFilePaths,
frontComponents: frontComponentsFilePaths,
publicAssets: publicAssetsFilePaths,
diff --git a/packages/twenty-cli/src/app/source/extract-define-entity.ts b/packages/twenty-cli/src/app/source/extract-define-entity.ts
index 64edd3cbecb..bc409ff23c8 100644
--- a/packages/twenty-cli/src/app/source/extract-define-entity.ts
+++ b/packages/twenty-cli/src/app/source/extract-define-entity.ts
@@ -18,6 +18,7 @@ export const DEFINE_ENTITY_KEYS = {
defineWorkflow: 'workflows',
defineConnectionProvider: 'connectionProviders',
defineMessagingProvider: 'messagingProviders',
+ defineMcpServer: 'mcpServers',
defineFrontComponent: 'frontComponents',
defineSettingsFrontComponent: 'frontComponents',
defineView: 'views',
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx
index 0f702dc79c5..5d4e3720d19 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx
@@ -22,6 +22,7 @@ your-app/
│ ├── front-components/ ← defineFrontComponent
│ ├── skills/ ← defineSkill
│ ├── agents/ ← defineAgent
+│ ├── mcp-servers/ ← defineMcpServer
│ ├── views/ ← defineView
│ ├── navigation-menu-items/ ← defineNavigationMenuItem
│ ├── settings-menu-items/ ← defineSettingsMenuItem
@@ -51,6 +52,7 @@ your-app/
| **Workflow** | Ready-made workflows with a trigger and steps | [Workflows](/developers/extend/apps/logic/workflows) |
| **Connection Provider** | OAuth or custom sign-in for third-party accounts | [Connections](/developers/extend/apps/logic/connections) |
| **Messaging Provider** | Sends replies from an app's message channels through a connection | [Messaging Channels](/developers/extend/apps/logic/messaging-channels#sending-replies) |
+| **MCP Server** | External MCP server the workspace's AI can call | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
| **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) |
| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |
| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/developers/extend/apps/layout/page-layouts) |
diff --git a/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx b/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx
index 8e08303eaf5..a3952ebd86d 100644
--- a/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx
+++ b/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx
@@ -103,6 +103,39 @@ Schema notes:
- `required` (optional) lists the properties the model must always return.
- `additionalProperties: false` (optional) forbids any property not declared in `properties`.
+</Accordion>
+<Accordion title="defineMcpServer" description="Expose an external MCP server to the workspace's AI (beta)">
+
+<Warning>
+ MCP servers are in beta and not live yet: you can declare them, but workspaces cannot use their tools until the feature ships.
+</Warning>
+
+Use `defineMcpServer()` to ship a remote MCP server (Streamable HTTP) with your app, so the workspace's AI can use its tools without syncing that data into Twenty:
+
+```ts src/mcp-servers/github.ts
+import { defineMcpServer } from 'twenty-sdk/define';
+
+import { GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+
+export default defineMcpServer({
+ universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a01',
+ name: 'github',
+ label: 'GitHub',
+ url: 'https://api.githubcopilot.com/mcp/',
+ connectionProvider: {
+ universalIdentifier: GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER,
+ },
+});
+```
+
+Key points:
+- `name` is snake_case (lowercase letters, digits and underscores, starting with a letter, at most 32 characters) and unique in the workspace. It prefixes the server's tool names.
+- `url` must be an HTTP or HTTPS URL.
+- `connectionProvider` (optional) references a [connection provider](/developers/extend/apps/logic/connections) declared by the same app. Calls send that connection's access token as a Bearer token. Omit it for a public server.
+- The URL cannot change in a later version while a connection provider is linked, so tokens are never sent to another host.
+- Workspaces can deactivate the server; a later app version keeps that choice.
+- Requires `"engines": { "twenty": ">=2.53.0" }`.
+
</Accordion>
<Accordion title="runAgent" description="Run an agent from a logic function">
diff --git a/packages/twenty-sdk/src/sdk/define/common/constants/mcp-server-name-pattern.constant.ts b/packages/twenty-sdk/src/sdk/define/common/constants/mcp-server-name-pattern.constant.ts
new file mode 100644
index 00000000000..03c5c52d30a
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/define/common/constants/mcp-server-name-pattern.constant.ts
@@ -0,0 +1 @@
+export const MCP_SERVER_NAME_PATTERN = /^[a-z][a-z0-9_]{0,31}$/;
diff --git a/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts b/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts
index ff285222ce3..585cdd25a83 100644
--- a/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts
+++ b/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts
@@ -18,6 +18,7 @@ import {
type AgentManifest,
type ConnectionProviderManifest,
type FieldManifest,
+ type McpServerManifest,
type MessagingProviderManifest,
type NavigationMenuItemManifest,
type SkillManifest,
@@ -46,6 +47,7 @@ export type DefinableEntity =
| AgentManifest
| ConnectionProviderManifest
| MessagingProviderManifest
+ | McpServerManifest
| RoleConfig
| SkillManifest
| ViewConfig
diff --git a/packages/twenty-sdk/src/sdk/define/index.ts b/packages/twenty-sdk/src/sdk/define/index.ts
index 06ef1f33adb..d1e5bb76176 100644
--- a/packages/twenty-sdk/src/sdk/define/index.ts
+++ b/packages/twenty-sdk/src/sdk/define/index.ts
@@ -144,6 +144,7 @@ export type { InputJsonSchema } from 'twenty-shared/logic-function';
export { defineConnectionProvider } from '@/sdk/define/connection-providers/define-connection-provider';
export type { ConnectionProviderScope } from 'twenty-shared/application';
export { defineMessagingProvider } from '@/sdk/define/messaging-providers/define-messaging-provider';
+export { defineMcpServer } from '@/sdk/define/mcp-servers/define-mcp-server';
export { defineNavigationMenuItem } from '@/sdk/define/navigation-menu-items/define-navigation-menu-item';
diff --git a/packages/twenty-sdk/src/sdk/define/mcp-servers/__tests__/define-mcp-server.spec.ts b/packages/twenty-sdk/src/sdk/define/mcp-servers/__tests__/define-mcp-server.spec.ts
new file mode 100644
index 00000000000..ac2a6ca5a3a
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/define/mcp-servers/__tests__/define-mcp-server.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+
+import { defineMcpServer } from '@/sdk/define';
+
+const baseValidConfig = {
+ universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a01',
+ name: 'github',
+ label: 'GitHub',
+ url: 'https://api.githubcopilot.com/mcp/',
+ connectionProvider: {
+ universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a02',
+ },
+};
+
+describe('defineMcpServer', () => {
+ it('returns success for a valid config', () => {
+ const result = defineMcpServer(baseValidConfig);
+
+ expect(result.success).toBe(true);
+ expect(result.errors).toEqual([]);
+ });
+
+ it('accepts a public server without connection provider', () => {
+ const { connectionProvider: _, ...publicServerConfig } = baseValidConfig;
+
+ expect(defineMcpServer(publicServerConfig).success).toBe(true);
+ });
+
+ it.each(['GitHub', 'git-hub', '1github', 'a'.repeat(33)])(
+ 'rejects the name "%s"',
+ (name) => {
+ expect(defineMcpServer({ ...baseValidConfig, name }).success).toBe(false);
+ },
+ );
+
+ it('rejects a url that is not http or https', () => {
+ const result = defineMcpServer({
+ ...baseValidConfig,
+ url: 'ftp://example.com/mcp',
+ });
+
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects a connection provider reference that is not a UUID', () => {
+ const result = defineMcpServer({
+ ...baseValidConfig,
+ connectionProvider: { universalIdentifier: 'github-oauth' },
+ });
+
+ expect(result.errors).toHaveLength(1);
+ });
+});
diff --git a/packages/twenty-sdk/src/sdk/define/mcp-servers/define-mcp-server.ts b/packages/twenty-sdk/src/sdk/define/mcp-servers/define-mcp-server.ts
new file mode 100644
index 00000000000..7bba324b352
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/define/mcp-servers/define-mcp-server.ts
@@ -0,0 +1,45 @@
+import { type DefineEntity } from '@/sdk/define/common/types/define-entity.type';
+import { MCP_SERVER_NAME_PATTERN } from '@/sdk/define/common/constants/mcp-server-name-pattern.constant';
+import { createValidationResult } from '@/sdk/define/common/utils/create-validation-result';
+import { isValidPostgresUuid } from '@/sdk/define/common/utils/is-valid-postgres-uuid';
+import { type McpServerManifest } from 'twenty-shared/application';
+import { isDefined, isHttpUrl, isNonEmptyString } from 'twenty-shared/utils';
+
+export const defineMcpServer: DefineEntity<McpServerManifest> = (config) => {
+ const errors: string[] = [];
+
+ if (!isNonEmptyString(config.universalIdentifier)) {
+ errors.push('MCP server must have a universalIdentifier');
+ } else if (!isValidPostgresUuid(config.universalIdentifier)) {
+ errors.push(
+ `MCP server universalIdentifier "${config.universalIdentifier}" must be a UUID. Generate one with \`uuidgen\` or any UUID v4 tool.`,
+ );
+ }
+
+ if (!isNonEmptyString(config.name)) {
+ errors.push('MCP server must have a name');
+ } else if (!MCP_SERVER_NAME_PATTERN.test(config.name)) {
+ errors.push(
+ `MCP server name "${config.name}" must match ${MCP_SERVER_NAME_PATTERN}`,
+ );
+ }
+
+ if (!isNonEmptyString(config.label)) {
+ errors.push('MCP server must have a label');
+ }
+
+ if (!isNonEmptyString(config.url) || !isHttpUrl(config.url)) {
+ errors.push(`MCP server url "${config.url}" must be an HTTP or HTTPS URL`);
+ }
+
+ if (
+ isDefined(config.connectionProvider) &&
+ !isValidPostgresUuid(config.connectionProvider.universalIdentifier)
+ ) {
+ errors.push(
+ `MCP server connectionProvider.universalIdentifier "${config.connectionProvider.universalIdentifier}" must be the UUID universalIdentifier of a connection provider in this app.`,
+ );
+ }
+
+ return createValidationResult({ config, errors });
+};
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-mcp-server-manifest-to-universal-flat-mcp-server.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-mcp-server-manifest-to-universal-flat-mcp-server.util.ts
new file mode 100644
index 00000000000..e75d6c0ca25
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-mcp-server-manifest-to-universal-flat-mcp-server.util.ts
@@ -0,0 +1,24 @@
+import { type McpServerManifest } from 'twenty-shared/application';
+
+import { type UniversalFlatMcpServer } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-mcp-server.type';
+
+export const fromMcpServerManifestToUniversalFlatMcpServer = ({
+ mcpServerManifest,
+ applicationUniversalIdentifier,
+ now,
+}: {
+ mcpServerManifest: McpServerManifest;
+ applicationUniversalIdentifier: string;
+ now: string;
+}): UniversalFlatMcpServer => ({
+ universalIdentifier: mcpServerManifest.universalIdentifier,
+ applicationUniversalIdentifier,
+ name: mcpServerManifest.name,
+ label: mcpServerManifest.label,
+ url: mcpServerManifest.url,
+ connectionProviderUniversalIdentifier:
+ mcpServerManifest.connectionProvider?.universalIdentifier ?? null,
+ isActive: true,
+ createdAt: now,
+ updatedAt: now,
+});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts
index 6973e57b403..ba81d6d9b9d 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts
@@ -16,6 +16,7 @@ import { fromApplicationVariableManifestToUniversalFlatApplicationVariable } fro
import { fromCommandMenuItemManifestToUniversalFlatCommandMenuItem } from 'src/engine/core-modules/application/application-manifest/converters/from-command-menu-item-manifest-to-universal-flat-command-menu-item.util';
import { getConnectionProviderManifestLogicFunctionReferences } from 'src/engine/core-modules/application/application-manifest/utils/get-connection-provider-manifest-logic-function-references.util';
import { fromConnectionProviderManifestToUniversalFlatConnectionProvider } from 'src/engine/core-modules/application/application-manifest/converters/from-connection-provider-manifest-to-universal-flat-connection-provider.util';
+import { fromMcpServerManifestToUniversalFlatMcpServer } from 'src/engine/core-modules/application/application-manifest/converters/from-mcp-server-manifest-to-universal-flat-mcp-server.util';
import { fromMessagingProviderManifestToUniversalFlatMessagingProvider } from 'src/engine/core-modules/application/application-manifest/converters/from-messaging-provider-manifest-to-universal-flat-messaging-provider.util';
import { fromFieldManifestToUniversalFlatFieldMetadata } from 'src/engine/core-modules/application/application-manifest/converters/from-field-manifest-to-universal-flat-field-metadata.util';
import { fromFieldPermissionManifestToUniversalFlatFieldPermission } from 'src/engine/core-modules/application/application-manifest/converters/from-field-permission-manifest-to-universal-flat-field-permission.util';
@@ -291,6 +292,18 @@ export class ComputeApplicationManifestAllUniversalFlatEntityMapsService {
});
}
+ for (const mcpServerManifest of manifest.mcpServers ?? []) {
+ addUniversalFlatEntityToUniversalFlatEntityMapsThroughMutationOrThrow({
+ universalFlatEntity: fromMcpServerManifestToUniversalFlatMcpServer({
+ mcpServerManifest,
+ applicationUniversalIdentifier,
+ now,
+ }),
+ universalFlatEntityMapsToMutate:
+ allUniversalFlatEntityMaps.flatMcpServerMaps,
+ });
+ }
+
for (const permissionFlagManifest of manifest.permissionFlags ?? []) {
addUniversalFlatEntityToUniversalFlatEntityMapsThroughMutationOrThrow({
universalFlatEntity:
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts
index 4c93994c019..a5130d29c2b 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts
@@ -277,7 +277,8 @@ export const MANIFEST_ENTITY_REGISTRY: Record<
},
mcpServer: {
entityKind: 'MCP server',
- getCandidates: () => NO_MANIFEST_CANDIDATES,
+ getCandidates: (manifest) =>
+ toCandidates(manifest.mcpServers, (mcpServer) => mcpServer.label),
},
applicationVariable: {
entityKind: 'application variable',
diff --git a/packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/workspace-owned-properties-by-metadata-name.constant.ts b/packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/workspace-owned-properties-by-metadata-name.constant.ts
index aeb58786a9b..abe76b3ce76 100644
--- a/packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/workspace-owned-properties-by-metadata-name.constant.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/workspace-owned-properties-by-metadata-name.constant.ts
@@ -9,6 +9,7 @@ export const WORKSPACE_OWNED_PROPERTIES_BY_METADATA_NAME: Partial<{
[P in AllMetadataName]: MetadataEntityPropertyName<P>[];
}> = {
agentChatChannel: ['name', 'icon', 'color', 'position'],
+ mcpServer: ['isActive'],
pageLayout: ['isFirstTabPinned'],
view: ['createdByUserWorkspaceId'],
workflow: ['createdByUserWorkspaceId', 'workspaceWorkflowId', 'visibility'],
diff --git a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/services/workspace-migration-build-orchestrator.service.ts b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/services/workspace-migration-build-orchestrator.service.ts
index 4720999a93d..eebe3b13cf8 100644
--- a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/services/workspace-migration-build-orchestrator.service.ts
+++ b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/services/workspace-migration-build-orchestrator.service.ts
@@ -292,10 +292,6 @@ export class WorkspaceMigrationBuildOrchestratorService {
ALL_METADATA_NAME.webhook,
workspaceMigrationWebhookActionsBuilderService,
),
- createEntityActionsBuilderTask(
- ALL_METADATA_NAME.mcpServer,
- workspaceMigrationMcpServerActionsBuilderService,
- ),
createEntityActionsBuilderTask(
ALL_METADATA_NAME.applicationVariable,
workspaceMigrationApplicationVariableActionsBuilderService,
@@ -308,6 +304,10 @@ export class WorkspaceMigrationBuildOrchestratorService {
ALL_METADATA_NAME.messagingProvider,
workspaceMigrationMessagingProviderActionsBuilderService,
),
+ createEntityActionsBuilderTask(
+ ALL_METADATA_NAME.mcpServer,
+ workspaceMigrationMcpServerActionsBuilderService,
+ ),
createEntityActionsBuilderTask(
ALL_METADATA_NAME.timelineActivityType,
workspaceMigrationTimelineActivityTypeActionsBuilderService,
diff --git a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/utils/compute-ordered-migration-actions.util.ts b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/utils/compute-ordered-migration-actions.util.ts
index 230538bd53d..a81bfb54588 100644
--- a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/utils/compute-ordered-migration-actions.util.ts
+++ b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/utils/compute-ordered-migration-actions.util.ts
@@ -149,8 +149,6 @@ export const computeOrderedMigrationActions = (
...aggregatedOrchestratorActionsReport.webhook.update,
...aggregatedOrchestratorActionsReport.mcpServer.delete,
- ...aggregatedOrchestratorActionsReport.mcpServer.create,
- ...aggregatedOrchestratorActionsReport.mcpServer.update,
...aggregatedOrchestratorActionsReport.applicationVariable.delete,
...aggregatedOrchestratorActionsReport.applicationVariable.create,
@@ -162,6 +160,8 @@ export const computeOrderedMigrationActions = (
...aggregatedOrchestratorActionsReport.messagingProvider.delete,
...aggregatedOrchestratorActionsReport.messagingProvider.create,
...aggregatedOrchestratorActionsReport.messagingProvider.update,
+ ...aggregatedOrchestratorActionsReport.mcpServer.create,
+ ...aggregatedOrchestratorActionsReport.mcpServer.update,
...aggregatedOrchestratorActionsReport.timelineActivityType.delete,
...aggregatedOrchestratorActionsReport.timelineActivityType.create,
...aggregatedOrchestratorActionsReport.timelineActivityType.update,
diff --git a/packages/twenty-server/test/integration/metadata/suites/mcp-server/mcp-server-manifest-sync.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/mcp-server/mcp-server-manifest-sync.integration-spec.ts
new file mode 100644
index 00000000000..4ac50fc7d26
--- /dev/null
+++ b/packages/twenty-server/test/integration/metadata/suites/mcp-server/mcp-server-manifest-sync.integration-spec.ts
@@ -0,0 +1,203 @@
+import { buildBaseManifest } from 'test/integration/metadata/suites/application/utils/build-base-manifest.util';
+import { cleanupApplicationAndAppRegistration } from 'test/integration/metadata/suites/application/utils/cleanup-application-and-app-registration.util';
+import { setupApplicationForSync } from 'test/integration/metadata/suites/application/utils/setup-application-for-sync.util';
+import { syncApplication } from 'test/integration/metadata/suites/application/utils/sync-application.util';
+import { updateMcpServer } from 'test/integration/metadata/suites/utils/mcp-server-test.util';
+import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
+import {
+ type ConnectionProviderManifest,
+ type McpServerManifest,
+} from 'twenty-shared/application';
+import { FeatureFlagKey } from 'twenty-shared/types';
+import { v4 as uuidv4 } from 'uuid';
+
+const TEST_APP_ID = uuidv4();
+const TEST_ROLE_ID = uuidv4();
+const CONNECTION_PROVIDER_ID = uuidv4();
+const MCP_SERVER_ID = uuidv4();
+
+const CONNECTION_PROVIDER: ConnectionProviderManifest = {
+ universalIdentifier: CONNECTION_PROVIDER_ID,
+ name: 'github',
+ displayName: 'GitHub',
+ type: 'oauth',
+ oauth: {
+ authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+ tokenEndpoint: 'https://github.com/login/oauth/access_token',
+ scopes: ['repo'],
+ clientIdVariable: 'GITHUB_CLIENT_ID',
+ clientSecretVariable: 'GITHUB_CLIENT_SECRET',
+ },
+};
+
+const buildMcpServer = (
+ overrides: Partial<McpServerManifest> = {},
+): McpServerManifest => ({
+ universalIdentifier: MCP_SERVER_ID,
+ name: 'github',
+ label: 'GitHub',
+ url: 'https://api.githubcopilot.com/mcp/',
+ connectionProvider: { universalIdentifier: CONNECTION_PROVIDER_ID },
+ ...overrides,
+});
+
+const syncMcpServers = ({
+ mcpServers,
+ expectToFail = false,
+}: {
+ mcpServers: McpServerManifest[];
+ expectToFail?: boolean;
+}) =>
+ syncApplication({
+ manifest: buildBaseManifest({
+ appId: TEST_APP_ID,
+ roleId: TEST_ROLE_ID,
+ overrides: {
+ connectionProviders: [CONNECTION_PROVIDER],
+ mcpServers,
+ },
+ }),
+ expectToFail,
+ });
+
+const findMcpServers = async (): Promise<
+ {
+ id: string;
+ name: string;
+ label: string;
+ url: string;
+ isActive: boolean;
+ connectionProviderUniversalIdentifier: string | null;
+ }[]
+> =>
+ globalThis.testDataSource.query(
+ `SELECT ms.id, ms.name, ms.label, ms.url, ms."isActive",
+ cp."universalIdentifier" AS "connectionProviderUniversalIdentifier"
+ FROM core."mcpServer" ms
+ JOIN core."application" app ON app.id = ms."applicationId"
+ LEFT JOIN core."connectionProvider" cp ON cp.id = ms."connectionProviderId"
+ WHERE app."universalIdentifier" = $1
+ ORDER BY ms.name`,
+ [TEST_APP_ID],
+ );
+
+describe('MCP server manifest sync', () => {
+ beforeEach(async () => {
+ await setupApplicationForSync({
+ applicationUniversalIdentifier: TEST_APP_ID,
+ name: 'Test Application',
+ description: 'App for testing MCP servers',
+ sourcePath: 'test-mcp-server-sync',
+ });
+ }, 60000);
+
+ afterEach(async () => {
+ await cleanupApplicationAndAppRegistration({
+ applicationUniversalIdentifier: TEST_APP_ID,
+ });
+ });
+
+ it('stores an MCP server linked to its connection provider', async () => {
+ await syncMcpServers({ mcpServers: [buildMcpServer()] });
+
+ expect(await findMcpServers()).toEqual([
+ {
+ id: expect.any(String),
+ name: 'github',
+ label: 'GitHub',
+ url: 'https://api.githubcopilot.com/mcp/',
+ isActive: true,
+ connectionProviderUniversalIdentifier: CONNECTION_PROVIDER_ID,
+ },
+ ]);
+ }, 60000);
+
+ it('stores a public MCP server without connection provider', async () => {
+ await syncMcpServers({
+ mcpServers: [
+ buildMcpServer({
+ name: 'docs',
+ label: 'Docs',
+ url: 'https://docs.example.com/mcp',
+ connectionProvider: undefined,
+ }),
+ ],
+ });
+
+ expect(await findMcpServers()).toEqual([
+ expect.objectContaining({
+ name: 'docs',
+ connectionProviderUniversalIdentifier: null,
+ }),
+ ]);
+ }, 60000);
+
+ it('refuses a connection provider that is not in the application', async () => {
+ const { errors } = await syncMcpServers({
+ mcpServers: [
+ buildMcpServer({
+ connectionProvider: { universalIdentifier: uuidv4() },
+ }),
+ ],
+ expectToFail: true,
+ });
+
+ expect(JSON.stringify(errors)).toContain('Connection provider not found');
+ expect(await findMcpServers()).toEqual([]);
+ }, 60000);
+
+ it('refuses a name that is not a snake_case tool prefix', async () => {
+ const { errors } = await syncMcpServers({
+ mcpServers: [buildMcpServer({ name: 'Git-Hub' })],
+ expectToFail: true,
+ });
+
+ expect(JSON.stringify(errors)).toContain('Invalid MCP server name');
+ }, 60000);
+
+ it('updates the label of an MCP server on re-sync', async () => {
+ await syncMcpServers({ mcpServers: [buildMcpServer()] });
+ await syncMcpServers({
+ mcpServers: [buildMcpServer({ label: 'GitHub Enterprise' })],
+ });
+
+ expect(await findMcpServers()).toEqual([
+ expect.objectContaining({ label: 'GitHub Enterprise' }),
+ ]);
+ }, 60000);
+
+ it('deletes an MCP server the manifest no longer declares', async () => {
+ await syncMcpServers({ mcpServers: [buildMcpServer()] });
+ await syncMcpServers({ mcpServers: [] });
+
+ expect(await findMcpServers()).toEqual([]);
+ }, 60000);
+
+ it('keeps an MCP server the workspace deactivated on re-sync', async () => {
+ await updateFeatureFlag({
+ featureFlag: FeatureFlagKey.IS_MCP_SERVERS_ENABLED,
+ value: true,
+ expectToFail: false,
+ });
+ await syncMcpServers({ mcpServers: [buildMcpServer()] });
+
+ const [mcpServer] = await findMcpServers();
+ const response = await updateMcpServer({
+ id: mcpServer.id,
+ update: { isActive: false },
+ });
+
+ expect(response.body.errors).toBeUndefined();
+
+ await syncMcpServers({
+ mcpServers: [buildMcpServer({ label: 'GitHub Enterprise' })],
+ });
+
+ expect(await findMcpServers()).toEqual([
+ expect.objectContaining({
+ label: 'GitHub Enterprise',
+ isActive: false,
+ }),
+ ]);
+ }, 60000);
+});
diff --git a/packages/twenty-shared/src/application/enums/syncable-entities.enum.ts b/packages/twenty-shared/src/application/enums/syncable-entities.enum.ts
index 5c392677cc2..bdd4efeb495 100644
--- a/packages/twenty-shared/src/application/enums/syncable-entities.enum.ts
+++ b/packages/twenty-shared/src/application/enums/syncable-entities.enum.ts
@@ -8,6 +8,7 @@ export enum SyncableEntity {
Agent = 'agent',
ConnectionProvider = 'connectionProvider',
MessagingProvider = 'messagingProvider',
+ McpServer = 'mcpServer',
View = 'view',
ViewField = 'viewField',
NavigationMenuItem = 'navigationMenuItem',
diff --git a/packages/twenty-shared/src/application/index.ts b/packages/twenty-shared/src/application/index.ts
index 11be821b9c2..ce83196df65 100644
--- a/packages/twenty-shared/src/application/index.ts
+++ b/packages/twenty-shared/src/application/index.ts
@@ -198,6 +198,7 @@ export type {
HttpRouteTriggerSettings,
} from './logicFunctionManifestType';
export type { TranslationsManifest, Manifest } from './manifestType';
+export type { McpServerManifest } from './mcpServerManifestType';
export type { MessagingProviderManifest } from './messagingProviderManifestType';
export type { NavigationMenuItemManifest } from './navigationMenuItemManifestType';
export type {
diff --git a/packages/twenty-shared/src/application/manifestType.ts b/packages/twenty-shared/src/application/manifestType.ts
index 2b476c97500..cbd72b80bfe 100644
--- a/packages/twenty-shared/src/application/manifestType.ts
+++ b/packages/twenty-shared/src/application/manifestType.ts
@@ -12,6 +12,7 @@ import {
} from './frontComponentManifestType';
import { type IndexManifest } from './indexManifestType';
import { type LogicFunctionManifest } from './logicFunctionManifestType';
+import { type McpServerManifest } from './mcpServerManifestType';
import { type MessagingProviderManifest } from './messagingProviderManifestType';
import { type NavigationMenuItemManifest } from './navigationMenuItemManifestType';
import { type ObjectManifest } from './objectManifestType';
@@ -48,6 +49,7 @@ export type Manifest = {
agents: AgentManifest[];
connectionProviders?: ConnectionProviderManifest[];
messagingProviders?: MessagingProviderManifest[];
+ mcpServers?: McpServerManifest[];
publicAssets: AssetManifest[];
views: ViewManifest[];
viewFields: StandaloneViewFieldManifest[];
diff --git a/packages/twenty-shared/src/application/mcpServerManifestType.ts b/packages/twenty-shared/src/application/mcpServerManifestType.ts
new file mode 100644
index 00000000000..af11a2c2f73
--- /dev/null
+++ b/packages/twenty-shared/src/application/mcpServerManifestType.ts
@@ -0,0 +1,8 @@
+import { type SyncableEntityOptions } from '@/application/syncableEntityOptionsType';
+
+export type McpServerManifest = SyncableEntityOptions & {
+ name: string;
+ label: string;
+ url: string;
+ connectionProvider?: SyncableEntityOptions;
+};