Model Context Protocol (MCP) Server
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Server in Twenty is a system designed to expose CRM data and metadata to Large Language Model (LLM) agents, such as Codex or ChatGPT. It allows these agents to inspect workspace records, objects, and fields through typed tools using a standardized protocol, providing a more robust integration than traditional REST API interactions for AI agents.
The system operates in two primary layers: a public documentation server (twenty-docs) used for searching official documentation, and user-specific workspace servers used for accessing private CRM data. It facilitates tasks such as listing companies, summarizing pipelines, and inspecting schemas while maintaining secure, header-based authentication.
Sources: packages/twenty-codex-plugin/README.md:14-23, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:114-122
Architecture and Components
The MCP architecture consists of the Twenty server acting as the host, a configuration layer for agents, and specific protocol endpoints.
Server Types
Twenty utilizes two distinct types of MCP servers:
- Public Docs Server: A bundled server named
twenty-docslocated athttps://docs.twenty.com/mcp. It allows agents to search public documentation immediately upon plugin installation. - Workspace MCP Server: A per-tenant server endpoint located at
${serverUrl}/mcp. This server provides access to specific workspace data, including records and metadata.
Sources: packages/twenty-codex-plugin/README.md:25-33, packages/twenty-codex-plugin/scripts/validators/metadata.js:15-16, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:121
System Flow
The following diagram illustrates the interaction between an LLM agent and the various MCP components within Twenty:
The diagram shows how the LLM Agent utilizes the Codex plugin to route requests to either the public documentation server or a specific private workspace server.
Sources: packages/twenty-codex-plugin/README.md:14-33, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:114-122
Workspace Data Access
Accessing workspace-specific data requires a user-local configuration to ensure security and multi-tenancy.
Configuration and Setup
Workspace MCP endpoints are not bundled in the plugin source code to avoid exposing private URLs. Instead, users must register their own workspace endpoints.
| Feature | Description | Requirement |
|---|---|---|
| Endpoint URL | ${serverUrl}/mcp | Must use HTTPS (except localhost) |
| Authentication | Header-based (Bearer Token or OAuth) | Never pass tokens in URLs |
| Registration | codex mcp add <name> --url <url> | Unique server name per workspace |
Sources: packages/twenty-codex-plugin/README.md:31-33, packages/twenty-codex-plugin/README.md:52-55, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:114-122
Read-Only Inspection (Postgres MCP)
A specific read-only Postgres MCP server can be configured in .mcp.json for development and debugging. It allows developers to:
- Inspect workspace data, metadata, and object definitions.
- Verify migration results (columns, types, constraints).
- Explore multi-tenant schema structures (core, metadata, and workspace-specific).
- Debug GraphQL schema generation issues by inspecting metadata tables.
Sources: CLAUDE.md:71-77
Data Retrieval and Formatting
When an agent retrieves records via MCP, specific output contracts ensure the data is presented in a human-readable and functional format.
Output Contract for Record References
If the MCP tool output includes recordReferences, the agent must adhere to the following formatting rules:
- Link Display Names: The first record-name column or record heading must link the display name back to the Twenty UI.
- Link Construction: Links are formatted as
{workspaceOrigin}/object/{objectNameSingular}/{recordId}. - Origin Derivation: The workspace origin is derived by removing the trailing
/mcpfrom the MCP server URL. - No Unlinked Names: Agents are forbidden from showing unlinked record names when references and origin are available.
Sources: packages/twenty-codex-plugin/skills/use-twenty-mcp/SKILL.md:43-49, packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js:15-18
Sequence of Data Retrieval
The sequence below shows how an agent retrieves and formats CRM data:
Security and Compliance
The MCP system enforces strict security boundaries to protect workspace data.
- Credential Handling: Bearer tokens, API keys, and OAuth secrets must never be bundled in the source code or committed to version control. They are strictly user-local.
- URL Restrictions: Only specific placeholder hosts (e.g.,
localhost,twenty.com,docs.twenty.com) are allowed in the plugin's documentation and configuration to prevent accidental exposure of production URLs. - Validation: Automated scripts (
assertNoBundledMcpConfig) scan for bundled workspace-specific configurations, bearer tokens, or non-placeholder URLs during the build process.
Sources: packages/twenty-codex-plugin/AGENTS.md:57-61, packages/twenty-codex-plugin/scripts/validators/metadata.js:80-117, packages/twenty-codex-plugin/scripts/validators/lib.js:71-94
Summary
The Twenty MCP Server system provides a standardized interface for LLMs to interact with CRM data. By separating public documentation access from private workspace data and enforcing a strict output contract for record linking, Twenty ensures that AI agents can effectively navigate and present CRM information while maintaining data security and multi-tenant isolation.