Skip to main content

​
Resumen

Twenty expone un servidor MCP 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:

​
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.
OAuth requiere un cliente MCP que sea compatible con la especificación de autorización de MCP. 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):
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:
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 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.

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

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