Add MCP servers settings under the AI tools tab
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 selectsMcpServerFragment. - 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_LENGTHmoves totwenty-shared/constantsso the form and the server validator read the same limit. This is the only server change.- The shared
TextInputerror helper getstop: 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 failedwith the error in a tooltip, orInactive), 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 withisHttpUrl, the same rule as the server, solocalhost, 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
mcpServerresolver 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
SettingsMcpServerDetailand 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
mcpServerslist. The list is not mounted on those pages, sorefetchQuerieswould not reach it. -
The list query keeps the full fragment, including each tool's
inputSchema.toolsis 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.tswith 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 SettingsAiMcpServerintwenty-front: 4 stories (new page, invalid name error on blur, detail page, sync keeps unsaved edits).flat-mcp-server-validator.service.spec.tsintwenty-server: 6 tests.npx tsgo -p tsconfig.json --noEmitintwenty-frontandtwenty-server: clean.twenty-sharedbuilds. oxlint and oxfmt on the changed files: clean.generated-metadata/graphql.tsregenerated from the checked-in metadata schema intwenty-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
Inactiveon 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 failedwith the reason, editing label and URL with re-sync on save, and unknown or malformed ids reaching the not found page.
- Create against a public no-auth MCP server (
- 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
TextInputchange was only looked at on this form.