Grist

Servidor MCP de Grist

Model Context Protocol (MCP) es un estándar abierto que permite a los asistentes de IA acceder a datos externos. Cualquier herramienta compatible con MCP (como Claude o ChatGPT) puede usar el servidor MCP de Grist para trabajar con tus sitios de equipo y documentos: listar y buscar tablas, leer y consultar filas, agregar o actualizar filas, y crear nuevos documentos y tablas.

[!note] ¿Quieres agregar un conector de Grist? Conecta Grist a Claude

Para ChatGPT, consulta las instrucciones a continuación.

Para el asistente de IA integrado de Grist, consulta Asistente de IA.

Configuración del servidor MCP

El servidor MCP de Grist está disponible en Grist alojado y en la edición completa de Grist autoalojado.

Grist alojado

En Grist alojado (getgrist.com), el servidor MCP ya está activado y no requiere configuración. Está disponible para todas las cuentas de Grist en todos los planes, aunque esto podría cambiar en el futuro.

Grist autoalojado

En la edición completa de Grist autoalojado, el servidor MCP está desactivado por defecto. Actívalo configurando esta variable de entorno en tu instancia:

GRIST_MCP_ENABLED=true

[!note] ¿Quieres probar la edición completa? Puedes probar la edición completa de Grist gratis durante 30 días. Aprende cómo activarla.

Personas y pequeñas empresas pueden calificar para una clave de activación gratuita de la edición completa. Consulta las preguntas frecuentes sobre claves de activación.

Esto es suficiente para clientes que se autentican con una clave de API de Grist: el usuario proporciona su clave en un encabezado Authorization y se conecta, sin necesidad de configurar nada más por tu parte. Asistentes de IA como Claude.ai, Claude Desktop y ChatGPT inician sesión de forma interactiva en su lugar, y necesitan un par de configuraciones adicionales.

Inicio de sesión interactivo (Claude, ChatGPT y similares)

Asistentes como Claude y ChatGPT te hacen iniciar sesión a través de Grist en lugar de usar una clave de API. Se autentican mediante el servidor OIDC integrado de Grist, que activas con:

GRIST_ENABLE_OIDC_SERVER=true

Estos asistentes se registran automáticamente usando CIMD (Client ID Metadata Documents). Permítelos listando los hosts de los que confías que provengan:

GRIST_OIDC_CIMD_ALLOWED_HOSTS=claude.ai,chatgpt.com

Una vez que configures ambas variables, los usuarios pueden conectar cualquier asistente de tu lista.

[!note] Clientes que no admiten CIMD Algunos asistentes no pueden registrarse mediante CIMD. Para estos, configura una aplicación OAuth en Grist y úsala con un cliente de tu elección.

Conexión de tu cliente MCP

Apunta tu cliente a la URL del servidor MCP de Grist:

• Grist alojado: https://docs.getgrist.com/api/mcp, una URL para cada sitio de equipo y tu sitio personal.
• Grist autoalojado: https://<your-grist-host>/api/mcp, tu propio host; cubre todos los sitios de equipo y sitios personales en esa instancia.

Los clientes pueden autenticarse de varias maneras: claves de API, cuentas de servicio, aplicaciones OAuth registradas y CIMD (Client ID Metadata Documents), el estándar preferido que permite que un cliente se registre automáticamente desde una URL de metadatos en lugar de configurarse de antemano.

Ejemplos de conexión

Estos ejemplos recorren Claude y ChatGPT. Otros clientes siguen el mismo flujo de conector personalizado.

Claude.ai o Claude Desktop

[!warning] Listado de directorio pendiente de revisión El listado de Grist en el directorio de Claude aún está bajo revisión de Anthropic y no está activo todavía. Hasta que esté disponible, usa el enlace especial 'Conecta Grist a Claude'.

El enlace 'Conecta Grist a Claude' abre el diálogo 'Agregar conector personalizado' de Claude con el nombre de Grist y la URL MCP prellenados, por lo que solo necesitas confirmar el diálogo e iniciar sesión:

Conecta Grist a Claude

Después de hacer clic en el enlace:

1. En el diálogo 'Agregar conector personalizado', haz clic en 'Agregar'.
2. Inicia sesión con tus credenciales habituales de Grist (Google o correo electrónico).
3. Revisa los permisos y haz clic en 'Permitir' en la pantalla de consentimiento.

add-connector

ChatGPT

[!note] Modo desarrollador requerido Agregar un servidor MCP personalizado en ChatGPT requiere el modo desarrollador. Actívalo en Configuración > Aplicaciones > Configuración avanzada.

1. En ChatGPT, abre Configuración > Aplicaciones. En Configuración avanzada, haz clic en Crear aplicación. chatgpt-apps
2. Completa el formulario Nueva aplicación:
   • Nombre: Grist. El ícono y la descripción son opcionales.
     • Conexión: mantén seleccionado URL del servidor e ingresa https://docs.getgrist.com/api/mcp, o https://<your-grist-host>/api/mcp para Grist autoalojado.
     • Autenticación: elige OAuth.
     • Marca Entiendo y quiero continuar para aceptar la advertencia de servidor personalizado. chatgpt-new-app
3. Haz clic en Crear. ChatGPT abre una ventana del navegador para que inicies sesión en Grist y apruebes los permisos en la pantalla de consentimiento.

Aplicaciones de terminal (Claude Code, Gemini CLI y similares)

La mayoría de los asistentes basados en terminal agregan un servidor MCP con un solo comando. Para Claude Code:

claude mcp add --transport http grist https://docs.getgrist.com/api/mcp

Otras herramientas, como Gemini CLI, usan un comando similar. Consulta la documentación de tu herramienta para conocer la sintaxis exacta. En el primer uso, la herramienta abre un navegador para que inicies sesión en Grist y apruebes los permisos necesarios.

Resumen de permisos solicitados por Grist

Antes de que puedas usar el conector, tu cliente te envía a Grist para iniciar sesión. Grist muestra qué aplicación está solicitando acceso (Claude en este ejemplo, con su nombre y URL) y te permite elegir la cuenta con la que continuar, o agregar otra cuenta.

grist-account-picker

La pantalla de consentimiento de Grist luego solicita a tu cliente MCP un conjunto de alcances de acceso. Cada alcance tiene una etiqueta, y el nombre subyacente del alcance se muestra entre paréntesis.

• Identificarte (openid, email, profile): confirmar quién eres y pasar tu nombre y correo electrónico al cliente para que pueda mostrar tu cuenta.
• Leer tu perfil (user.profile:read): permitir que la herramienta get_user_profile busque tu nombre y correo electrónico, para que el cliente pueda confirmar con qué cuenta de Grist está conectado.
• Mantener la sesión iniciada (offline_access): mantener la conexión funcionando sin pedirte que inicies sesión nuevamente, incluso cuando el cliente actúa en tu nombre mientras estás ausente, como durante una ejecución programada.
• Leer documentos (doc:read): listar y consultar tablas, registros, columnas y archivos adjuntos.
• Modificar registros (doc:write): agregar, actualizar y eliminar filas.
• Modificar esquema (doc.schema:write): agregar, renombrar o eliminar tablas y columnas.
• Descargar documentos (doc:download): descargar documentos completos. Actualmente no lo usa ninguna herramienta MCP.
• Gestionar webhooks (doc:webhooks): crear, leer, actualizar y eliminar webhooks de documentos.

Un cliente no tiene que solicitar todos los permisos de antemano. Puede solicitar solo lo que necesita al principio, como acceso de solo lectura, y tú lo apruebas en la pantalla de consentimiento. Si una herramienta necesita más permisos más adelante, algunos clientes te piden que apruebes el permiso adicional en ese momento y continúan una vez que lo haces. Si el tuyo no lo hace, vuelve a conectar Grist desde la configuración del conector de tu cliente y aprueba el acceso más amplio.

Elegir qué recursos puede acceder tu cliente MCP

grist-consent

La misma pantalla de consentimiento también pregunta a qué recursos de Grist puede acceder el cliente. Tienes dos opciones:

• Todos los documentos (ahora y en el futuro). El cliente puede ver y actuar en todos los sitios de equipo, espacios de trabajo y documentos a los que tu cuenta tiene acceso, incluidos los que crees más adelante. Esta es la opción predeterminada.
• Recursos seleccionados. Elige sitios de equipo, espacios de trabajo o documentos específicos. Puedes mezclar niveles, por ejemplo, un espacio de trabajo completo más un solo documento de otro lugar.

Seleccionar un elemento principal otorga acceso a todo lo que contiene. Si seleccionas un espacio de trabajo, no necesitas seleccionar también los documentos dentro de él.

Puedes cambiar esta selección más adelante desde la página 'Aplicaciones autorizadas' en la configuración de tu cuenta de Grist, sin desconectar el cliente. Un cambio puede tardar hasta una hora en llegar a los clientes que ya has conectado, como Claude o ChatGPT. Para aplicarlo de inmediato, desconecta y vuelve a conectar Grist desde la configuración del conector de ese cliente.

Aprende más sobre aplicaciones conectadas.

Herramientas disponibles

El servidor MCP de Grist expone un conjunto de herramientas para trabajar con tus documentos, agrupadas en algunas categorías. Las herramientas actúan en tu nombre, por lo que solo pueden acceder a lo que tu cuenta puede acceder. Los permisos que otorgas en la pantalla de consentimiento reducen esto aún más, para que puedas limitar lo que el conector puede hacer.

[!note] Nota Cada nombre de herramienta tiene el prefijo grist_ cuando se llama (por lo que list_docs es grist_list_docs). El prefijo se omite en esta lista para facilitar la lectura.

Descubrimiento

Encuentra a qué tienes acceso.

• list_orgs lista tus sitios de equipo.
• list_workspaces lista los espacios de trabajo dentro de un sitio de equipo.
• list_docs lista los documentos dentro de un espacio de trabajo.
• get_doc_info devuelve metadatos sobre un solo documento.
• get_user_profile devuelve el nombre y correo electrónico de la cuenta con la que estás conectado.
• help devuelve una breve descripción general de lo que el servidor puede hacer.

Prueba preguntando:

• "¿Qué documentos de Grist tengo?"
• "Muéstrame todo en mi sitio de equipo de Marketing."

Lectura de datos

Consulta e inspecciona el contenido de los documentos.

• query_document ejecuta una consulta en lenguaje natural o estilo SQL en las tablas de un documento.
• list_records devuelve filas de una sola tabla.
• get_tables y get_table_columns describen la estructura de un documento.
• list_snapshots lista versiones guardadas anteriores de un documento.
• get_grist_access_rules_reference explica cómo funcionan las reglas de acceso de un documento.

Prueba preguntando:

• "¿Cuántos acuerdos abiertos hay en mi CRM?"
• "Lista los contactos con los que no he hablado en 90 días."
• "¿Cuál es el ingreso total por cliente este trimestre en mi documento de Facturas?"

Escritura de datos

Modifica registros.

• add_records agrega nuevas filas.
• update_records modifica filas existentes por ID de fila.
• remove_records elimina filas.

Prueba preguntando:

• "Agrega un nuevo cliente llamado Acme Corp a mi CRM con el correo ops@acme.com."
• "Marca la tarea #42 como completada en mi Seguimiento de Proyectos."
• "Elimina todas las filas en Tickets donde Estado sea 'Archivado'."

Gestión de documentos y esquema

Crea y remodela documentos.

• create_doc crea un nuevo documento en un espacio de trabajo.
• create_table y add_table_column amplían el esquema.
• update_table_column cambia el tipo de columna, fórmula o etiqueta.

Otras herramientas: rename_table, remove_table, remove_table_column.

Prueba preguntando:

• "Inicia un nuevo documento para rastrear mis gastos."
• "Agrega una columna Prioridad a Tareas con opciones Baja, Media, Alta."
• "Renombra la columna Notas a Comentarios en mi CRM."

Páginas y widgets

Gestiona las páginas y widgets de un documento.

• get_pages lista las páginas en un documento.
• add_page_widget agrega un widget a una página (Tabla, Tarjeta, Lista de Tarjetas, Gráfico, Calendario, Personalizado, etc.).
• update_page_widget cambia el título, la tabla, la configuración de vista o el diseño de un widget.

Otras herramientas: update_page, remove_page, get_page_widgets, remove_page_widget, get_page_widget_select_by_options, set_page_widget_select_by, get_available_custom_widgets.

Prueba preguntando:

• "Agrega una página de gráfico a mi documento de Ventas que muestre ingresos por mes."
• "Pon una Vista de Tarjeta de Contactos en la página de Resumen."
• "Elimina la página Notas Internas de mi Seguimiento de Proyectos."

Archivos adjuntos

Trabaja con archivos almacenados en un documento.

• list_attachments lista los archivos en un documento, con su nombre, tamaño y tipo.
• get_attachment_url proporciona un enlace de corta duración para descargar un archivo.

Prueba preguntando:

• "¿Qué archivos están adjuntos en mi documento de Gastos?"
• "Dame un enlace de descarga para el recibo en mi documento de Gastos."

Ejemplos de indicaciones

Estos ejemplos usan Claude.ai. La primera vez que Claude llama a una herramienta de Grist, solicita tu aprobación. Puedes elegir 'Permitir siempre' para omitir la indicación de esa herramienta en llamadas futuras.

tool-call-approval

Puedes usar el servidor MCP de Grist para:

• Consulta datos estructurados en lenguaje natural: «En mi documento de CRM, ¿quién tiene una tarea abierta que venza en los próximos 7 días?»
• Actualiza registros en masa: «En mi documento de Entregas, actualiza todas las fechas para que sigan el formato ISO 8601.»
• Crea un documento desde cero: «Crea un nuevo documento llamado “Reviewer Sandbox” con una tabla Sample que tenga las columnas correctamente tipadas: Name, Value, Created.»

Cuando el asistente termine, el documento nuevo o actualizado estará listo para abrirse en Grist.

Manejo de datos

Cuando llamas a una herramienta de Grist desde tu cliente MCP, los datos que devuelve la herramienta se envían al proveedor de IA de ese cliente para que el modelo pueda usarlos en su respuesta.

• El transporte es HTTPS/TLS de extremo a extremo.
• El servidor MCP no almacena datos propios. Cada solicitud se autentica contra tu cuenta de Grist existente y sus reglas de acceso.
• El token OAuth está limitado a los permisos que otorgaste al conectarte. Puedes revocarlo en cualquier momento desde la configuración de la cuenta de Grist.

[!warning] Advertencia Trata el conector como si compartieras un documento con un colega. Cualquier cosa que le pidas al cliente leer o escribir será visible para su proveedor de IA.

Consulta la Política de privacidad de Grist para más detalles.

Preguntas frecuentes

¿Cuánto cuesta el servidor MCP de Grist?

El servidor MCP de Grist está actualmente disponible para todos los usuarios de Grist sin costo adicional, en Grist alojado y en la edición completa de Grist autoalojado, en todos los planes. Esto puede cambiar en el futuro.

Tu cliente MCP puede tener sus propios requisitos (por ejemplo, algunos clientes solo permiten conectores personalizados en un plan de pago). Esto depende del proveedor, así que consulta su página de precios para más detalles.

¿Cómo maneja mis datos el servidor MCP?

Consulta la sección Manejo de datos.

¿Puedo tener varios conectores de Grist?

Sí. La mayoría de los clientes MCP te permiten agregar el mismo servidor MCP más de una vez con diferentes nombres de conector, para que puedas mantener conexiones separadas (por ejemplo, iniciando sesión con diferentes cuentas de Grist). En Claude, el listado de directorios solo admite una única conexión, pero la ruta de conector personalizado no te impide agregar la misma URL nuevamente con un nombre diferente.

¿Cómo me conecto con una cuenta de Grist diferente?

Dos opciones, disponibles en la mayoría de los clientes:

1. Desconecta Grist desde la configuración del conector de tu cliente y luego vuelve a conectarte. Cuando aparezca la pantalla de consentimiento, inicia sesión con la otra cuenta.
2. Agrega Grist como conector personalizado una segunda vez con un nombre diferente e inicia sesión con la otra cuenta durante el paso de consentimiento. Ambas conexiones coexistirán.

¿Puedo conectar mi Grist autoalojado?

Sí, siempre que estés ejecutando la edición completa de Grist. Grist autoalojado expone el mismo endpoint MCP en tu propio host: https://<your-grist-host>/api/mcp. Agrega esa URL a tu cliente MCP de la misma manera que agregarías cualquier otro servidor MCP y luego inicia sesión con tu cuenta de Grist. Consulta Grist autoalojado para activar el servidor y Conectando tu cliente MCP para los pasos de conexión.

¿Por qué veo un error de «permiso faltante»?

Una herramienta intentó usar un permiso que la conexión no tiene. Por ejemplo, si solo aprobaste acceso de lectura, herramientas de escritura como add_records se negarán a ejecutarse.

Algunos clientes te piden aprobar el permiso faltante de inmediato, tras lo cual la herramienta se ejecuta. Si el tuyo no lo hace, desconecta Grist en la configuración del conector del cliente y vuelve a conectarte, aprobando el acceso que deseas permitir. Desde la página de configuración del conector también puedes ver cada herramienta de Grist a la que el cliente tiene acceso y ajustar cuáles requieren aprobación.

claude-connector-settings

¿Por qué veo un error de «documento no encontrado»?

Generalmente, una de estas razones:

• El documento fue eliminado, movido o renombrado.
• No tienes acceso al documento con la cuenta con la que autorizaste a tu cliente.
• Le estás pidiendo a tu cliente que busque en un sitio de equipo diferente al que contiene el documento.

Primero, verifica qué cuenta de Grist usaste al conectarte. Si no estás seguro, pregúntale a la IA algo como «¿con qué cuenta de Grist estoy conectado?» y te informará el nombre y correo de la cuenta conectada. Si tienes varias cuentas de Grist (por ejemplo, una personal y una de trabajo), el documento podría estar bajo una cuenta diferente. Abre docs.getgrist.com, confirma que el documento existe bajo la cuenta que usaste para conectarte y verifica que tengas al menos acceso de vista.

Si no estás seguro de qué cuenta está conectada, la solución más rápida es desconectar Grist en la configuración del conector de tu cliente y volver a conectarte, iniciando sesión con la cuenta correcta esta vez.

Si el documento está en un sitio de equipo diferente, pídele a la IA que primero liste tus sitios de equipo con list_orgs.