> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Twenty

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](/docs/reception-ai/integrations/mcp-server), which works for Twenty Cloud and self-hosted Twenty. You could also build [webhook tools](/docs/reception-ai/integrations/webhooks) 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

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

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

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

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

### Add the MCP server

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

| Field            | Value                                                      |
| ---------------- | ---------------------------------------------------------- |
| **Name**         | Twenty                                                     |
| **Server type**  | Streamable HTTP                                            |
| **Server URL**   | Your workspace address followed by `/mcp`, as listed below |
| **Secret Token** | Your API key                                               |

| Where Twenty runs | Server URL                                                            |
| ----------------- | --------------------------------------------------------------------- |
| Twenty Cloud      | Your workspace URL, for example `https://mycompany.twenty.com/mcp`    |
| Self-hosted       | Your 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.

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

### Add a procedure

Add a [procedure](/docs/reception-ai/receptionist/rules-and-procedures) 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.

### Test it

[Test your receptionist](/docs/reception-ai/receptionist/testing) 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

| Problem                           | What to check                                                                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| No tools are listed               | Use 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 error | The key's role can't read or create People. Edit the role in **Settings** → **Members** → **Roles**.                                         |
| Known callers aren't found        | Store phone numbers with their country code and in one format.                                                                               |
| The call reason is empty          | Select **Refresh tools** after adding the `Call reason` field, then select **Update** on the changed tool.                                   |
| You changed the key               | Edit the integration and use **Rotate Secret Token (optional)**. The saved key is never shown again.                                         |