Add MCP servers settings under the AI tools tab

Merged
AB
15h ago
+1585-27

What

Adds the settings UI for external MCP servers, behind the IS_MCP_SERVERS_ENABLED feature flag and the API_KEYS_AND_WEBHOOKS permission.

  • Settings > AI > Tools gets an "MCP servers" section: a table with the label, URL hostname and a status badge (N tools, Sync failed with the reason in a tooltip, or Inactive), plus an "Add MCP server" button under the table.
  • ai/new-mcp-server: About (label, name) and Connection (URL) sections. The name must match ^[a-z][a-z0-9_]*$ and stay under MCP_SERVER_NAME_MAX_LENGTH; the URL is validated with the same isHttpUrl the server uses. Errors show on blur. Creating redirects to the detail page.
  • ai/mcp-servers/:mcpServerId: edit the label and URL (the name is read only), a Tools section with "Sync tools", "Last synced …" and the cached tools table, an inline banner when the last sync failed, and a not-found page for unknown ids.
  • Danger zone: Deactivate / Activate, and Delete behind a confirmation. Delete is hidden for servers owned by an installed application.

MCP_SERVER_NAME_MAX_LENGTH moves from the server to twenty-shared/constants so both sides validate against the same limit.

This is the settings half of #29669, re-extracted without sign-in. The sign-in scope select, the connections section and the URL lock tied to a provider come in a follow-up on top of #30356.

Notes for review

  • The list query now spreads McpServerFragment so the settings pages and the workflow step picker share one cache entry; tools is a non-normalized array, so a partial selection in one place would overwrite the other's.
  • Mutations evict ROOT_QUERY.mcpServers instead of appending to it, since the server orders the list.
  • Update sends only the fields that changed; saving an unchanged form resets it without a request.
  • New components: none from twenty-ui. Reuses Section, Table, Status, InlineBanner, SettingsTextInput, ConfirmationDialog.

Screenshots

Tools tab

01-tools-tab-list

New MCP server

02-new-mcp-server

Validation errors on blur

03-new-mcp-server-errors

Detail page with synced tools

04-detail-synced

Delete confirmation

05-delete-dialog

Detail page after a failed sync

06-detail-sync-failed

Test

  • Unit: getMcpServerStatus, mcpServerFormSchema (jest).
  • Stories: SettingsMcpServersTable, SettingsAiMcpServerNew (default, invalid name), SettingsAiMcpServerDetail (default, sync keeps unsaved edits).
  • Manual, with the flag on: add a server, sync its tools, edit the label, deactivate and reactivate, delete; open ai/mcp-servers/<random uuid> and check the not-found page.