MCP Tools

MCP (Model Context Protocol) is ThinkWork’s OSS path for external tools. MCP servers expose capabilities that the tenant platform agent can call during work, while ThinkWork controls registration, assignment, auth resolution, and audit.

Use MCP tools when the tenant platform agent needs to call remote capabilities during a turn, such as CRM lookups, ticket updates, internal API operations, search, or database queries exposed by an MCP server.

How it works

Operator or managed app registers MCP server
    -> Server is assigned to an agent, template, or Space
    -> User connects OAuth-protected servers from Settings -> MCP Servers
    -> Invocation resolves tenant or current-user auth
    -> Runtime connects to MCP server
    -> Tools are discovered
    -> Tenant platform agent calls tools during the turn
    -> Calls are logged in the thread timeline

Registration

MCP servers are registered at the tenant level, then assigned to agents, templates, or Spaces depending on the product surface. Most rows are manual operator registrations. Managed applications and application plugins can also reconcile system-managed rows, such as the Twenty CRM MCP server that appears automatically when the Twenty managed application is running.

The MCP Servers page

Settings → MCP Servers organizes the registry into three tabs:

Tab	Contents
MCP Servers	Manually registered servers
Plugin MCPs	Servers installed and managed by plugins and managed applications
Datasource MCPs	Analyst data sources — PostgreSQL databases the agent queries through the read-only broker, each showing its source type (Internal/External), cluster instance, and database. See Analyst Data Sources

The header actions register a new MCP server (plus icon) or a new analyst data source (database icon).

Typical config includes:

Field	Description
Name	Display name for the MCP server
URL	HTTP endpoint for the server
Transport	Streamable HTTP or SSE
Auth	None, tenant API key, per-user OAuth, or plugin-defined per-user headers

URL is read from the record on every call

The MCP endpoint URL lives in tenant_mcp_servers.url. The runtime resolves it on every outbound call. There are no hardcoded defaults and no env-var fallbacks for MCP base URLs. Rename the record in admin and the next request uses the new host.

Managed application MCP rows

System-managed MCP rows carry managed ownership metadata and are not manually removed from the MCP Servers UI. Their lifecycle follows the managed application:

Managed app state	MCP behavior
Running	Managed row is visible, assigned to the tenant platform agent, and available for user OAuth from Settings -> MCP Servers
Parked	Runtime use is disabled; user token continuity is retained
Destroyed	Managed row and stored token material are removed during cleanup

If an already-running Twenty CRM stage is missing the managed row, operators repair it from Settings -> CRM with Install MCP Server. Do not register a duplicate manual Twenty row.

The MCP server detail page imports runtime tools from the assigned agent. For Twenty CRM, the UI expands the MCP server’s get_tool_catalog response so the full CRM tool catalog can be searched and paged instead of only showing the small top-level MCP wrapper tools.

Authentication

MCP tools commonly use these patterns:

None for private-network services or systems with external network controls.
Tenant API key for a shared secret resolved at invocation time.
Per-user OAuth when downstream tools need user-scoped access. Users connect from Spaces/Desktop Settings -> MCP Servers. Mobile retains the same self-service flow for mobile users.
Per-user plugin headers when a plugin needs user-scoped non-OAuth credentials. ThinkWork sends those headers only for the requester whose activation stored them.

Runtime behavior

At runtime, ThinkWork discovers tools from the MCP server and adds them beside built-in tools and skill-provided tools. If an MCP server is unavailable, the worker can continue with its remaining toolset.

For OAuth MCP servers, runtime assembly only includes the server when the current user has an active stored token. There is no tenant-wide fallback for a missing user credential. When the token exists, ThinkWork injects it into the outbound MCP call automatically; the agent does not see or manage the token.

The same fail-closed rule applies to user-provided header servers. If the current user has not activated the server, the runtime does not synthesize a tenant-wide credential and does not reuse another user’s secret.

Record-link hints

Some plugin-owned MCP servers can publish non-secret recordLinkHints runtime metadata. Hints describe supported object types, safe browser route templates, and field names to read from the current MCP tool result. They are not OAuth configuration and they do not change the server’s credential approval hash.

ThinkWork applies these hints only after an MCP tool call has succeeded for the current user. The runtime does not create links from arbitrary ids in a user message, previous conversation text, or unauthenticated tool output. If a result is malformed, unsupported, custom-object-only, or returned as MCP isError, ThinkWork omits generated links.

Twenty CRM currently uses this path for Opportunity records. When an authorized Twenty MCP result includes a supported Opportunity id, the runtime can append a managed Twenty record URL to the agent-visible tool result and preserve the same links in structured recordLinks details for proxy/UI consumers. The generated URLs are thread-visible business data, not credentials; avoid copying raw CRM payloads, ids, names, or generated links into logs outside the intended thread/tool-result evidence.

MCP usage is tracked in the thread timeline, including:

tool name
MCP server attribution
input and output previews
execution status