Add mcpServer syncable metadata entity with GraphQL CRUD
Merged
AB
21d ago+4341+4341+0123456789012345678901234567890123456789-1842-1842-0123456789012345678901234567890123456789
First step of exposing external MCP servers to the AI chat: a workspace can register an MCP server as metadata, and apps will be able to ship one later.
What
- New
core.mcpServersyncable entity:name(snake_case slug, max 32 chars, used as the tool-name prefix),label,url,connectionProviderId(nullable metadata relation toconnectionProvider; null means a public server),isActive(same flag name as skills, objects and fields). - Authentication links the server to a connection provider, not to an account. The account is resolved when a tool is called, from the provider's scope (
WORKSPACE: the shared account,USER: the caller's own, no fallback between the two), so a manifest can declare server and provider together and nothing on the server goes stale when accounts are archived or transferred. Until the DCR follow-up lands, API-created servers are public or app-shipped. - Flat cache (
flatMcpServerMaps), migration builder, validator, runner handlers and the central registrations, following the webhook pattern. - Validation reuses what exists:
isSnakeCaseToolName(the tool registry's own rule, since the name prefixes tool names) plus aMCP_SERVER_NAME_MAX_LENGTHconstant for the name, and a newisHttpUrlintwenty-shared/utils/url(unit-tested) for the URL. Unique name per workspace is checked against the optimistic flat maps and backed by a unique index. McpServerService+ resolver:mcpServers,mcpServer,createMcpServer,updateMcpServer,deleteMcpServer.- Fast instance command
2.52.0 / 1792916230347creating the table, generated with TypeORM; the entity is marked@WasIntroducedInUpgradeso a server running ahead of the upgrade still boots. - URL normalization goes through
getUrlSafelyfromtwenty-shared/utils(plainURL()semantics, same asWebhookService.normalizeTargetUrl). Webhook code is untouched by this PR. - Feature flag
IS_MCP_SERVERS_ENABLED, seeded on in dev.
Endpoint permissions
McpServerResolver is new. All five endpoints (mcpServers, mcpServer, createMcpServer, updateMcpServer, deleteMcpServer) share the class-level guards:
- Principals:
AuthPrincipalGuardwith user sessions (standard, impersonated, playground; not workspace-agnostic),apiKey: true,oauthClient: trueandapplication: true. This is a copy ofWebhookResolver's configuration: MCP servers are Developers-settings configuration, exactly like webhooks and API keys, and the same integrations that provision webhooks over the API need to provision MCP servers. Nothing here acts as a workspace member, so no user is required. SettingsPermissionGuard(PermissionFlagType.API_KEYS_AND_WEBHOOKS)on every endpoint, the same settings permission that gates webhooks and API keys (its label already reads "MCP & APIs").FeatureFlagGuard(FeatureFlagKey.IS_MCP_SERVERS_ENABLED)on every endpoint, so nothing is reachable until the flag is on for the workspace.- The validator enforces that
connectionProviderIdnames a provider of the server's own application (CONNECTION_PROVIDER_NOT_FOUND/CONNECTION_PROVIDER_NOT_IN_APPLICATION) and rejects aurlchange while a provider is linked (MCP_SERVER_URL_CHANGE_WHILE_CONNECTED), so tokens minted for one host are never sent to another.
Why metadata, not a record object
MCP servers are workspace configuration. Record objects carry readability and row-level sharing semantics that do not apply here, and a syncable metadata entity is what lets an application declare one in its manifest.
Out of scope (follow-ups)
- MCP client and
tools/listsync (adds thetools/toolsSyncedAt/toolsSyncErrorcolumns together with the code that writes them) McpToolProviderexposing cached tools in chat- Settings > Developers UI
- Manifest declaration and the help center app
- Per-user authentication (a USER-scoped account resolved per caller through the connection provider), if a use case needs it.
Test
test/integration/metadata/suites/developers/mcp-servers.integration-spec.ts(asserts the validation error codes: invalid name, non-http URL, blank label, duplicate name, unknown id; an unknown provider and a provider synced from another application are rejected).flat-mcp-server-validator.service.spec.tscovers the accepted same-application provider and the url-change invariant.test/integration/endpoint-permissionssnapshot updatedtwenty-sharedunit test forisHttpUrltsgo --noEmiton twenty-server and twenty-front,lint:diff-with-mainclean