Sign in to MCP servers through an oauth-discovery connection provider

Merged
AB
19h ago
+2324-238

What

Second of three PRs split out of #29669, on top of #30153 (oauth-discovery connection provider). Charles' #30070 rebased onto the design that merged.

An MCP server that answers an unauthenticated ping with 401 gets its own oauth-discovery connection provider, generated by Twenty and owned by the server's application:

  • createMcpServer, updateMcpServer and syncMcpServerTools attach the provider when the server asks for a sign-in. A sync also catches servers that were down at creation or started asking later.
  • signInScope (USER: each member signs in, WORKSPACE: one shared account) on the create and update inputs and on McpServer. Provider scopes are immutable, so changing the scope or the URL replaces the generated provider. The old one is deleted once no server uses it. Providers declared by an app are never deleted. Only a server owned by the workspace application gets a generated provider; an app-declared server keeps the provider from its manifest, which an app sync would otherwise delete.
  • A server that cannot be reached is saved without a sign-in and the tool sync records why; the next sync attaches the sign-in once the server answers 401.
  • Calls pick the caller's connected account. A rejected access token is refreshed once before the account is marked signed out.
  • Token refreshes are serialized per account for every caller, in ConnectedAccountRefreshTokensService.refreshAndSaveTokens: app logic, messaging, calendar and MCP calls all go through resolveTokens, and with rotating refresh tokens a lost race used to spend the same token twice and leave an auth-failed account. The loser now reuses the winner's tokens.
  • MCP_SERVER_NAME_MAX_LENGTH moves to twenty-shared/constants for the settings form in PR 3.

Architecture

flowchart LR
  Resolver[McpServerResolver] --> Service[McpServerService<br/>create, update, delete, sync]
  Service --> SignIn[McpServerSignInService<br/>provision the sign-in provider]
  Service --> Migration[McpServerMigrationService<br/>flat maps and migrations]
  SignIn --> Client[McpServerClientService<br/>probe, list tools, call tool]
  Client -->|requiresSignIn: probeProtectedResource| MCP[(MCP server)]
  Client --> Accounts[McpServerConnectedAccountService<br/>pick the caller's account, refresh once, mark signed out]
  Accounts --> Refresh[ConnectedAccountRefreshTokensService<br/>per-account refresh lock]
  SignIn -->|oauth-discovery provider| Provider[connectionProvider row<br/>owned by the server's application]
ServiceOwns
McpServerSignInServiceDecides whether a server needs a generated sign-in provider, builds it, attaches it on create, update or sync, deletes it once unused.
McpServerMigrationServiceFlat maps and the validate-build-run migration for mcpServer and connectionProvider operations.
McpServerClientServiceThe MCP client: sign-in probe (reusing the protected-resource probe from #30153), tool listing, tool calls.
McpServerConnectedAccountServiceFinds the connected account usable by the caller, refreshes a rejected token once, marks the account signed out on an unrecoverable refresh.
ConnectedAccountRefreshTokensServiceShared by every caller; now serializes refreshes per account.

Changes from #30070

  • Rebased onto main after #30153 merged, so the sign-in probe and the MCP client use SecureHttpClientService.createFetchLike and probeProtectedResource as they exist on main.
  • The client metadata document now carries logo_uri (the instance's own /images/icons/ios/192.png, so self-hosted servers show their own instance), software_id and software_version (RFC 7591), answering the review question on #30153.

Known limits

  • syncMcpServerTools attaches a late sign-in with USER scope, because a requested WORKSPACE scope is not stored anywhere when the server did not ask for sign-in at creation. The scope can be changed afterwards on the server.
  • The messages stored in toolsSyncError are raw English server messages, like every other sync error today.
  • Deleting a server and its generated provider are two migrations, because deleting the provider cascades to the servers still on it. If the second one fails, the provider is left without a server.

Stack

  1. #30153: oauth-discovery connection provider (merged)
  2. This PR: MCP server sign-in and refresh serialization
  3. MCP servers settings UI (next)

Test

  • Unit: mcp-server, connected-account, validators, connection-provider.
  • Integration on a reset DB: mcp-server-oauth.integration-spec.ts (sign-in, per-member and shared accounts, refresh after a rejected token, concurrent refreshes), the other MCP server suites and the connection-provider suites.
  • tsgo clean, oxlint and prettier clean.