Skip to navigation

Twenty

Recognize callers and add new leads to Twenty CRM through its MCP server.

Your receptionist can recognize callers who are already in Twenty and add new callers as people, with their name, phone number, and why they called, so your sales team can follow up. Reception connects to Twenty’s built-in MCP server, which works for Twenty Cloud and self-hosted Twenty. You could also build webhook tools for Twenty’s REST API, but the MCP server needs less setup: it gives your receptionist ready-made tools for finding and adding people, already matched to your workspace’s fields, including the call reason field below.

Set up

1

Add a field for the call reason

People in Twenty have no notes field of their own. To keep why the caller called on their record, go to Settings → Data model, open People, and add a Text field named Call reason. Only workspace admins can change the data model.

2

Create a role for Reception.ai

Go to Settings → Members → Roles and create a role that can only read and create People. You’ll assign the API key to it in the next step.

3

Create an API key

Go to Settings → Developers → API and select + Create key. Name it, for example Reception.ai, and copy it right away: Twenty only shows it once. Then open the role you created, go to its Assignment tab, and assign the key to it.

The API key can read and change everything its role allows. Keep it out of shared documents, and delete it in Twenty if it leaks.

4

Add the MCP server

In Reception.ai, go to Integrations, select Add integration, and choose MCP Server.

FieldValue
NameTwenty
Server typeStreamable HTTP
Server URLYour workspace address followed by /mcp, as listed below
Secret TokenYour API key
Where Twenty runsServer URL
Twenty CloudYour workspace URL, for example https://mycompany.twenty.com/mcp
Self-hostedYour instance’s public URL, for example https://crm.example.com/mcp

You can copy the exact address from Settings → AI → MCP in Twenty. Don’t add ?mode=meta to the URL: that mode gives your receptionist a single tool that can run any action.

Select Enable. Reception.ai sends the key as a bearer token and lists Twenty’s tools.

5

Assign tools

Twenty lists a tool for every action on every object. Open the Tools tab and assign only these to the Client (receptionist):

  • find_many_people: find the caller by phone number.
  • create_one_person: add a new caller with their name, phone number, and call reason.

Leave the update and delete tools, and the tools for other objects, unassigned.

6

Add a procedure

Add a procedure for new leads: search for the caller by phone number first, create a person only when no match is found, and always fill in the first name, last name, phone number, and call reason. Add a rule that your receptionist never reads CRM records back to callers.

7

Test it

Test your receptionist by calling from a number saved on a Twenty person, then as a new caller who wants a quote. The new person appears under People with the call reason filled in.

Limitations

  • Twenty stores the country calling code apart from the rest of the number. Callers saved without a country code, or in a different format, may not be found, so a returning caller can be added twice.
  • Your receptionist doesn’t create notes, tasks, or opportunities in this setup. Your team picks up new people from the People list, for example with a view filtered on Call reason.
  • Self-hosted instances need a Twenty version that includes the MCP server, and the public URL must be reachable from the internet over HTTPS.
  • Twenty’s API allows 100 requests a minute. Busy workspaces with other integrations may hit the limit.

Troubleshooting

ProblemWhat to check
No tools are listedUse the Streamable HTTP server type, and check the URL ends in /mcp. On self-hosted, the SERVER_URL setting must be your public URL.
A tool returns a permission errorThe key’s role can’t read or create People. Edit the role in Settings → Members → Roles.
Known callers aren’t foundStore phone numbers with their country code and in one format.
The call reason is emptySelect Refresh tools after adding the Call reason field, then select Update on the changed tool.
You changed the keyEdit the integration and use Rotate Secret Token (optional). The saved key is never shown again.