Add mcpServer syncable metadata entity with GraphQL CRUD

Merged
AB
21d ago
+4341-1842

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.mcpServer syncable entity: name (snake_case slug, max 32 chars, used as the tool-name prefix), label, url, connectionProviderId (nullable metadata relation to connectionProvider; 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 a MCP_SERVER_NAME_MAX_LENGTH constant for the name, and a new isHttpUrl in twenty-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 / 1792916230347 creating the table, generated with TypeORM; the entity is marked @WasIntroducedInUpgrade so a server running ahead of the upgrade still boots.
  • URL normalization goes through getUrlSafely from twenty-shared/utils (plain URL() semantics, same as WebhookService.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: AuthPrincipalGuard with user sessions (standard, impersonated, playground; not workspace-agnostic), apiKey: true, oauthClient: true and application: true. This is a copy of WebhookResolver'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 connectionProviderId names a provider of the server's own application (CONNECTION_PROVIDER_NOT_FOUND / CONNECTION_PROVIDER_NOT_IN_APPLICATION) and rejects a url change 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)

  1. MCP client and tools/list sync (adds the tools / toolsSyncedAt / toolsSyncError columns together with the code that writes them)
  2. McpToolProvider exposing cached tools in chat
  3. Settings > Developers UI
  4. Manifest declaration and the help center app
  5. 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.ts covers the accepted same-application provider and the url-change invariant.
  • test/integration/endpoint-permissions snapshot updated
  • twenty-shared unit test for isHttpUrl
  • tsgo --noEmit on twenty-server and twenty-front, lint:diff-with-main clean