Skip to main content

​
Overview

Twenty exposes an MCP server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language. Use your workspace URL (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be https://{mycompany}.twenty.com or a custom domain. The server is available at:

​
Authentication Methods

You have two ways to authenticate your MCP client: OAuth (recommended) or API Key. With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
OAuth requires an MCP client that supports the MCP Authorization specification. Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
Add this to your MCP client configuration, replacing {your-workspace-url} with your workspace host (e.g. mycompany.twenty.com):
That’s it — no API key needed. When the client connects for the first time it will:
  1. Discover Twenty’s OAuth metadata via /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server
  2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
  3. Open your browser to authorize access
  4. Receive tokens and connect to the MCP server
Subsequent connections reuse the stored tokens and refresh them automatically.

​
Option B — API Key

If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the Authorization header:
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
To create an API key, go to Settings → Developers → API → + Create key. See APIs for details.

​
Quick Start

​
1. Copy the config

Go to Settings → AI → MCP in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client’s config file.

​
2. Connect

Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.

​
3. Start using it

Ask your AI assistant to interact with your CRM:
  • “Show me the 5 most recently created companies”
  • “Create a new person named Jane Doe at Acme Corp”
  • “Find all open opportunities worth more than $10k”

​
Available Tools

Once connected, the MCP server lists the same tools in every workspace:
  • Record tools take the object as an argument: find_records, group_records, create_records, update_record, update_records, upsert_records, delete_records and merge_records. For example, find_records({ objectName: "company", select: ["name"] }).
  • Discovery tools tell the assistant what your workspace contains: list_object_metadata_names for objects and get_field_metadata for the fields of an object.
  • Metadata tools to read and change the data model, such as get_object_metadata or create_field_metadata.
  • Meta-tools reach everything else, including workflows, views, dashboards, email and the functions of your installed apps: get_tool_catalog to browse a category, learn_tools for input schemas and execute_tool to run a tool.
Because the list does not depend on your objects, it stays valid for clients that store it, such as apps published in a directory.

​
Direct mode

Connect to /mcp?mode=direct to list one tool per object and operation instead, each with the exact input schema of that object: find_many_companies, create_one_person, and several hundred more. Tools for objects created while you are connected appear after reconnecting. This needs a client that loads tools on demand, as Claude, Claude Code, Codex and OpenCode do by default. A client that loads every tool definition up front, including Claude Code with tool search turned off, can run out of context.

​
Meta mode

Connect to /mcp?mode=meta to list only a few meta-tools:
  1. learn_tools — get the input schema for specific tools
  2. execute_tool — run a tool
Record operation names follow a grammar, so an assistant can build them without a discovery call: find_many_companies, find_one_person, update_one_opportunity. If a name is wrong, learn_tools reports it under notFound along with the closest matching names. For anything else, get_tool_catalog browses the remaining tools one category at a time. It is a fallback: an unfiltered call returns hundreds of operations and most assistants will truncate the response.

​
Permissions

MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
  • OAuth: The user’s workspace role applies.
  • API Key: Assign a role to the API key under Settings → Members → Roles. See Permissions.

​
Self-Hosted Configuration

For self-hosted instances, replace {your-workspace-url} with your server URL. Make sure SERVER_URL in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.

​
Troubleshooting

“Unauthorized” or 401 errors
  • OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
  • API Key: verify the key is valid and hasn’t expired. Regenerate it if needed.
OAuth flow doesn’t open a browser
  • Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn’t.
Connection timeout
  • Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and SERVER_URL is set correctly.