> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor MCP

> Conecta asistentes de IA a tu espacio de trabajo de Twenty mediante el Model Context Protocol.

## Resumen

Twenty expone un servidor [MCP](https://modelcontextprotocol.io/) para que los asistentes de IA — Claude Desktop, Claude Code, Cursor, ChatGPT y otros — puedan leer y escribir tus datos de CRM mediante lenguaje natural.

Usa tu **URL del espacio de trabajo** (la URL que utilizas para acceder a Twenty) como el punto de acceso MCP. En Twenty Cloud, la URL de tu espacio de trabajo puede ser `https://{mycompany}.twenty.com` o un dominio personalizado. El servidor está disponible en:

| Entorno | Punto de acceso MCP |
| - | - |
| **Nube** | `https://{your-workspace-url}/mcp` (p. ej., `https://mycompany.twenty.com/mcp`) |
| **Autoalojamiento** | `https://{your-domain}/mcp` |

## Métodos de autenticación

Tienes dos formas de autenticar tu cliente MCP: **OAuth** (recomendado) o **API Key**.

### Opción A — OAuth (recomendado)

Con OAuth, tu cliente MCP abre una ventana del navegador para que inicies sesión. No se guardan secretos en archivos de configuración y los tokens se actualizan automáticamente.

> [!NOTE]
>
> OAuth requiere un cliente MCP que sea compatible con la [especificación de autorización de MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor y ChatGPT lo admiten.

Agrega esto a la configuración de tu cliente MCP, reemplazando `{your-workspace-url}` por el host de tu espacio de trabajo (p. ej., `mycompany.twenty.com`):

```json theme={null}
{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp"
    }
  }
}
```

Eso es todo: no se necesita clave de API. Cuando el cliente se conecte por primera vez, hará lo siguiente:

1. Descubrir los metadatos de OAuth de Twenty a través de `/.well-known/oauth-protected-resource` y `/.well-known/oauth-authorization-server`
2. Registrarse como cliente OAuth mediante registro dinámico de clientes (RFC 7591)
3. Abrir tu navegador para autorizar el acceso
4. Recibir tokens y conectarse al servidor MCP

Las conexiones posteriores reutilizan los tokens almacenados y los actualizan automáticamente.

### Opción B — API Key

Si tu cliente MCP no es compatible con OAuth o prefieres credenciales estáticas, pasa una clave de API en el encabezado `Authorization`:

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

> [!WARNING]
>
> Tu clave de API concede acceso a los datos del espacio de trabajo. Manténla fuera del control de versiones y de dotfiles compartidos.

Para crear una clave de API, ve a **Settings → Developers → API → + Create key**. Consulta [APIs](https://docs.twenty.com/es/developers/extend/api.md#create-an-api-key) para más detalles.

## Inicio rápido

### 1. Copia la configuración

Ve a **Settings → AI → MCP** en Twenty. Elige tu método de autenticación (OAuth o API Key), copia el fragmento JSON (ya usará la URL de tu espacio de trabajo) y pégalo en el archivo de configuración de tu cliente MCP.

| Cliente | Ubicación del archivo de configuración |
| - | - |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Claude Code** | `~/.claude.json` (usuario) o `.mcp.json` (proyecto) |
| **Cursor** | `.cursor/mcp.json` en tu proyecto, o `~/.cursor/mcp.json` de forma global |
| **ChatGPT** | Activa Developer Mode en **Settings → Apps & Connectors → Advanced settings**, luego usa **Create** en **Settings → Apps & Connectors** para añadir el servidor MCP |

### 2. Conectar

Reinicia tu cliente MCP (o recarga la configuración). Si usas OAuth, se te redirigirá a Twenty para autorizar el acceso. Si usas una clave de API, la conexión es inmediata.

### 3. Empieza a usarlo

Pídele a tu asistente de IA que interactúe con tu CRM:

* *"Muéstrame las 5 empresas creadas más recientemente"*
* *"Crea una nueva persona llamada Jane Doe en Acme Corp"*
* *"Encuentra todas las oportunidades abiertas con un valor superior a \$10k"*

## Herramientas disponibles

Una vez conectado, el servidor MCP expone herramientas que reflejan la API de Twenty. El flujo de trabajo recomendado es:

1. **`learn_tools`** — obtener el esquema de entrada para herramientas específicas
2. **`execute_tool`** — ejecutar una herramienta

No necesitas recordar los nombres de las herramientas. Pregúntale a tu asistente de IA qué puede hacer y llamará a `learn_tools` automáticamente.

Los nombres de las operaciones de registros siguen una gramática, por lo que un asistente puede crearlos sin una llamada de descubrimiento: `find_many_companies`, `find_one_person`, `update_one_opportunity`. Si un nombre es incorrecto, `learn_tools` lo informa en `notFound` junto con los nombres más parecidos.

Para cualquier otra cosa, `get_tool_catalog` explora las herramientas restantes, una categoría a la vez. Es una alternativa: una llamada sin filtrar devuelve cientos de operaciones y la mayoría de los asistentes truncarán la respuesta.

`/mcp?mode=direct` enumera cada herramienta directamente y necesita un cliente que cargue herramientas bajo demanda.

## Permisos

Las conexiones MCP heredan los permisos del usuario autenticado (OAuth) o del rol asignado a la clave de API. Para restringir lo que puede hacer el servidor MCP:

* **OAuth**: Se aplica el rol del espacio de trabajo del usuario.
* **API Key**: Asigna un rol a la clave de API en **Settings → Members → Roles**. Consulta [Permisos](https://docs.twenty.com/es/user-guide/permissions-access/capabilities/permissions.md).

## Configuración autohospedada

Para instancias autohospedadas, reemplaza `{your-workspace-url}` por la URL de tu servidor. Asegúrate de que `SERVER_URL` en tu entorno coincida con la URL pública de tu instancia de Twenty — se utiliza para generar los metadatos de descubrimiento de OAuth.

```bash theme={null}
SERVER_URL=https://twenty.yourcompany.com
```

El punto de acceso MCP, los puntos de acceso de OAuth y los metadatos de descubrimiento se derivan de este valor.

## Solución de Problemas

**Errores "Unauthorized" o 401**

* OAuth: vuelve a autorizar limpiando los tokens almacenados en tu cliente MCP y reconectando.
* API Key: verifica que la clave sea válida y no haya caducado. Vuelve a generarla si es necesario.

**El flujo de OAuth no abre un navegador**

* Asegúrate de que tu cliente MCP sea compatible con MCP Authorization. Si no lo es, recurre al método de clave de API.

**Tiempo de espera de la conexión**

* Confirma que la URL del punto de acceso MCP sea accesible desde tu equipo. Para instancias autohospedadas, comprueba que el servidor esté en ejecución y que `SERVER_URL` esté configurado correctamente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.