Add MCP servers settings under the AI tools tab

Closed
AB
8d ago
+5345-167

What

Adds an MCP servers section to the Tools tab of Settings > AI, gated by IS_MCP_SERVERS_ENABLED, on top of the mcpServer metadata entity and its GraphQL API already on main. Depends on nothing unmerged.

  • SettingsPath.AiNewMcpServer / SettingsPath.AiMcpServerDetail (ai/new-mcp-server, ai/mcp-servers/:mcpServerId), named like the skill paths next to them.
  • GraphQL documents under modules/mcp-servers/graphql/ (list, single, create, update, delete, sync tools) and the codegen glob for them. Every operation selects McpServerFragment.
  • Settings module under modules/settings/mcp-servers/: section and table, new form, detail loader and edit form, danger zone, one hook per mutation, status util, zod schema for the form.
  • MCP_SERVER_NAME_MAX_LENGTH moves to twenty-shared/constants so the form and the server validator read the same limit. This is the only server change.
  • The shared TextInput error helper gets top: 100%. It was absolutely positioned with no offset, so the message was drawn over the field's value. This affects every form using that input and sits in its own commit (2c7f4b5eead) so it can be split out if preferred.
  • Settings > Developers is unchanged from main.

Screens / behavior

  • Tools tab: an "MCP servers" section above the tools list, with label, URL hostname and a status badge (N tools, Sync failed with the error in a tooltip, or Inactive), and an "Add MCP server" button. A failed list query shows a toast instead of an empty table.
  • New (ai/new-mcp-server): two sections with labelled inputs. "About" holds label and name (^[a-z][a-z0-9_]*$, max 32); "Connection" holds the http(s) URL and the optional connection provider. The URL is checked with isHttpUrl, the same rule as the server, so localhost, single-label hosts and IPv6 endpoints are accepted. Field errors show on blur. Creation redirects to the detail page; the server syncs tools on create.
  • Detail (ai/mcp-servers/:mcpServerId): edit label, URL and connection provider (name is read-only after creation). "Tools" section with a Sync tools button, "Last synced …", and the cached tools as a name and description table. A failed sync shows a one-line inline error banner with the full reason on hover. Syncing keeps unsaved edits in the form. An unknown, deleted or malformed (non-UUID) id goes to the not found page.
  • Danger zone: the same pattern as skills. A Deactivate / Activate button and a Delete button behind a confirmation dialog, both returning to the Tools tab. Delete is hidden for servers owned by an installed application. There is no active switch in the form.
  • The connection provider select lists "None" plus the providers of the server's own application (the workspace custom application for a new server), since the backend only accepts providers from that application. With no providers it is disabled.

Notes for review

  • Design feedback from Thomas applied: no Name column in the servers table, no annotations column in the tools table, fields grouped into two sections with input labels and hints, and the sync error moved into an inline banner.

  • Permission: the section and its routes need the API keys & webhooks permission, because that is what the mcpServer resolver checks. The AI settings page itself needs the AI settings permission. A member with AI settings but not API keys & webhooks sees the Tools tab without this section. If MCP servers should follow the AI settings permission instead, that is a resolver change I left out of this PR.

  • Placement: the section sits above the tools list because that list is long and a section below it is easy to miss.

  • The server is loaded in SettingsMcpServerDetail and the edit form mounts with its values as defaults, so there is no effect copying query data into the form.

  • Create and delete evict the cached mcpServers list. The list is not mounted on those pages, so refetchQueries would not reach it.

  • The list query keeps the full fragment, including each tool's inputSchema. tools is a non-normalized array, so a slimmer selection in the list would overwrite the entries the detail page reads from the same cache.

  • #29668 adds its own copy of findManyMcpServers.ts with the fields inline. Whichever merges second takes the fragment version and reruns the metadata codegen.

Test

  • npx jest packages/twenty-front/src/modules/settings/mcp-servers --config=packages/twenty-front/jest.config.mjs: 2 suites, 16 tests (form schema, status label).
  • STORYBOOK_SCOPE=pages npx vitest run --project=storybook SettingsAiMcpServer in twenty-front: 4 stories (new page, invalid name error on blur, detail page, sync keeps unsaved edits).
  • flat-mcp-server-validator.service.spec.ts in twenty-server: 6 tests.
  • npx tsgo -p tsconfig.json --noEmit in twenty-front and twenty-server: clean. twenty-shared builds. oxlint and oxfmt on the changed files: clean.
  • generated-metadata/graphql.ts regenerated from the checked-in metadata schema in twenty-client-sdk; only the new operations differ from main.
  • Run by hand in the browser against a local stack on a freshly reset database, at the new location under Settings > AI > Tools:
    • Create against a public no-auth MCP server (https://mcp.deepwiki.com/mcp): lands on the detail page with its 3 tools. Manual Sync tools shows the count toast.
    • Deactivate returns to the Tools tab with Inactive on the row; the detail page then offers Activate.
    • Delete behind the confirmation returns to the Tools tab with the row gone.
    • Settings > Developers no longer has an MCP servers tab.
    • Before the move, on the same components: client validation (bad name, bad URL), duplicate name rejected with a toast, a blocked internal address showing Sync failed with the reason, editing label and URL with re-sync on save, and unknown or malformed ids reaching the not found page.
  • Not covered by hand: a server linked to a connection provider (the seed workspace has none), and a server that belongs to an installed application.
  • The TextInput change was only looked at on this form.