MCP Server

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.

Option A — OAuth (Recommended)

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.

Add this to your MCP client configuration, replacing {your-workspace-url} with your workspace host (e.g. mycompany.twenty.com):

{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp"
    }
  }
}

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:

{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

To create an API key, go to Settings > APIs & Webhooks > + Create key. See APIs for details.

Quick Start

1. Copy the config

Go to Settings > AI > More > MCP Server 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 exposes tools that mirror the Twenty API. The recommended workflow is:

1. get_tool_catalog — discover all available tools
2. learn_tools — get the input schema for specific tools
3. execute_tool — run a tool

You don't need to remember tool names. Ask your AI assistant what it can do and it will call get_tool_catalog automatically.

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 > 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.

SERVER_URL=https://twenty.yourcompany.com

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.