formbase (formbase.so)

formbase.so recopila y verifica información de los clientes para flujos de trabajo y agentes de IA

Servidor MCP alojado

npx add-mcp 'https://api.formbase.so/api/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Servidor MCP de formbase

El servidor MCP alojado para formbase.so. formbase recopila y verifica información de clientes para flujos de trabajo y agentes de IA.

Tu agente crea una solicitud para una persona. Esa persona, el destinatario, recibe un formulario con marca que ya incluye lo que ya sabes. Lo completan en cualquier dispositivo, sin necesidad de cuenta. formbase devuelve las respuestas bajo claves de campo que tu agente puede leer.

El servidor está en:

https://api.formbase.so/api/mcp

Este repositorio contiene documentación, configuraciones de ejemplo y un manifiesto de plugin para Grok Build. No hay nada que instalar ni ejecutar.

Lo que un agente puede hacer
Conecta tu herramienta de IA
Pruébalo
Herramientas
Límites
Detalles del protocolo
Documentación
Reportar un problema

Lo que un agente puede hacer

Enviar solicitudes. Pide información a una persona nombrada, con respuestas prellenadas o bloqueadas, y lee lo que respondió.
Crear formularios. Crea un formulario y añade, edita o elimina sus preguntas, páginas y lógica.
Publicar y compartir. Publica un formulario, crea enlaces de compartir, tradúcelo y configura su tema y ajustes.
Leer resultados. Lista los envíos de un formulario y lee sus análisis.

MCP (el Protocolo de Contexto de Modelo) es el estándar que las herramientas de IA usan para llamar a otras aplicaciones. La mayoría de las herramientas de IA inician sesión en formbase con OAuth: pegas la URL, inicias sesión en formbase en el navegador y eliges un espacio de trabajo. Los scripts y agentes sin interfaz gráfica envían un token de API en su lugar.

Conecta tu herramienta de IA

Deja vacío cualquier campo de ID de cliente, secreto o token. La herramienta de IA encuentra la página de inicio de sesión de formbase desde el servidor y se registra automáticamente.

Claude Code

claude mcp add --transport http formbase https://api.formbase.so/api/mcp

Luego escribe /mcp en Claude Code para iniciar sesión.

Para compartir el servidor con todos los que trabajan en un proyecto, confirma un .mcp.json en el proyecto:

{
  "mcpServers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp"
    }
  }
}

Claude de escritorio y claude.ai

Abre Personalizar › Conectores › + › Añadir conector personalizado y pega la URL. Un conector añadido en claude.ai también funciona en las aplicaciones de escritorio y móvil.

En Team y Enterprise, un propietario añade el conector primero en Configuración de la organización › Conectores. Luego los miembros hacen clic en Conectar sobre él. En Free puedes añadir un conector personalizado. La guía de Claude: Empieza con conectores personalizados.

Cursor

Añade esto a .cursor/mcp.json en tu proyecto, o a ~/.cursor/mcp.json para cada proyecto:

{
  "mcpServers": {
    "formbase": {
      "url": "https://api.formbase.so/api/mcp"
    }
  }
}

VS Code

Añade esto a .vscode/mcp.json en tu proyecto. Ten en cuenta que VS Code nombra la clave de nivel superior servers:

{
  "servers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp"
    }
  }
}

O ejecuta MCP: Añadir servidor desde la Paleta de comandos y pega la URL. Consulta la guía de MCP de VS Code.

Grok Build

Este repositorio también es un plugin de Grok Build: .grok-plugin/plugin.json, la configuración del servidor .mcp.json y una habilidad, formbase-requests. El plugin no ejecuta nada en tu máquina. Llama a un único endpoint de red, https://api.formbase.so/api/mcp, e inicia sesión con OAuth de formbase, o con un token de API que añadas como cabecera.

Otras herramientas

Cualquier herramienta que admita servidores MCP remotos con inicio de sesión funciona igual: busca dónde añade un servidor por URL. La guía de conexión también cubre ChatGPT y Codex.

Inicia sesión y elige un espacio de trabajo

La primera vez que el agente usa formbase, tu herramienta de IA abre una página de formbase en el navegador. Inicia sesión, elige el espacio de trabajo y haz clic en Autorizar.

Una conexión llega solo a ese espacio de trabajo. Para usar otro espacio de trabajo, añade formbase una segunda vez y elige el otro.

Para comprobar que funciona, pregunta:

List my formbase forms and whether each one is published.

Para eliminar la conexión, abre OAuth y claves de API en la barra lateral del espacio de trabajo de formbase. En Aplicaciones conectadas, haz clic en el icono de papelera junto a la conexión y confirma con Desconectar.

Scripts y agentes sin interfaz gráfica: usa un token de API

Cualquier cosa que no pueda abrir un navegador, como un script, un trabajo de CI o un agente sin interfaz gráfica, envía un token de API como cabecera en su lugar.

Abre OAuth y claves de API en la barra lateral de tu espacio de trabajo y haz clic en Crear token (tokens de API).
Copia el token. Empieza con fb_.
Envíalo como cabecera Authorization: Bearer.

Un token llega exactamente a un espacio de trabajo, como una conexión OAuth. Caduca 30 días después de crearlo y no se puede extender, así que planifica reemplazarlo. Mantenlo fuera de git.

Claude Code, desde la línea de comandos:

claude mcp add --transport http formbase https://api.formbase.so/api/mcp \
  --header "Authorization: Bearer fb_YOUR_TOKEN"

O en un archivo de configuración. Esto es .mcp.json para Claude Code; Cursor toma el mismo objeto headers en su mcp.json:

{
  "mcpServers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_TOKEN"
      }
    }
  }
}

Otras herramientas toman la misma URL y cabecera. Consulta su documentación para saber dónde.

Pruébalo

Envía una solicitud a una persona. Usa el nombre de uno de tus formularios publicados:

Send a formbase request with the "Supplier onboarding" form to Ada Lovelace (ada@acme.example). Fill in the company name "Analytical Engines Ltd" and lock it so she cannot change it. Use supplier-2041 as the external ID. Don't email her; give me the link and I will send it myself.

El agente lee las claves de campo del formulario con fields_list, crea la solicitud con request_create y te da el enlace de la solicitud.

Si el formulario tiene Enviar recordatorios activado, formbase igualmente envía al destinatario sus recordatorios programados. Para evitarlo, también di sin recordatorios.

El agente no sabe cuándo envía el destinatario, así que pregúntale más tarde:

Has the formbase request supplier-2041 been answered? Show me the answers.

El agente encuentra la solicitud por su ID externo con request_list, y luego la lee con request_get. Una vez completada la solicitud, las respuestas llegan con claves por campo.

Paso a paso: Envía una solicitud con un agente de IA y Crea un formulario con un agente de IA.

Herramientas

Cada herramienta está en tools/list con su esquema de entrada completo en cuanto una herramienta de IA se conecta. La referencia del servidor MCP las describe en detalle.

Solicitudes

Pide información a una persona nombrada y lee el resultado.

fields_list: lista las claves de campo a las que una solicitud puede dirigirse en un formulario publicado. Llámala antes de request_create.
request_create: asigna un formulario publicado a un destinatario, con prellenado, campos bloqueados, contexto, entrega, caducidad y un callback opcional.
request_get: lee una solicitud por su ID. Devuelve el estado, la línea de tiempo y, una vez completada, las respuestas con claves por campo.
request_list: lista solicitudes para un formulario o un espacio de trabajo, filtradas por estado, resultado o tu propio ID externo.
request_cancel: retira una solicitud pendiente.
request_remind: envía al destinatario un correo de recordatorio ahora.
request_replayCallback: envía un callback de nuevo cuando nunca llegó a tu endpoint.
document_create: reserva una subida para un archivo que una solicitud entrega a su destinatario. Una subida puede servir a cualquier número de solicitudes.

Formularios

form_list, form_get, form_create, form_update: encuentra, lee, crea y renombra formularios, y configura la carpeta, el emoji, la portada y el logotipo.
form_publish, form_unpublish: inicia y detiene la aceptación de envíos. form_publish es seguro llamarla dos veces.
form_delete, form_restore: mueve un formulario a la papelera, lo que también revoca sus enlaces de compartir, y lo restaura.

form_get devuelve las preguntas de la última versión publicada. Para un borrador, lee el contenido con editor_getDocument.

Editor

editor_getDocument: lee la estructura completa de un formulario.
editor_updateElement, editor_deleteElement: edita, mueve o elimina un bloque.
editor_formatText: formatea texto dentro de un bloque.
editor_setLogic, editor_testLogic: cambia la regla de un bloque de lógica y pruébala. Crea el bloque con editor_insertLogic.

Cada tipo de bloque tiene su propia herramienta de inserción con un esquema preciso:

Preguntas: editor_insertTextQuestion, editor_insertContactQuestion, editor_insertNumberQuestion, editor_insertDateQuestion, editor_insertTimeQuestion, editor_insertRadioQuestion, editor_insertCheckboxQuestion, editor_insertSelectQuestion, editor_insertPictureChoiceQuestion, editor_insertSwitchQuestion, editor_insertRatingQuestion, editor_insertLinearScaleQuestion, editor_insertRankingQuestion, editor_insertMatrixQuestion, editor_insertFileQuestion, editor_insertSignatureQuestion, editor_insertPaymentQuestion, editor_insertScheduleAppointmentQuestion
Decisión: editor_insertDecisionQuestion inserta la elección aprobar / rechazar / cambios cuya respuesta se convierte en el resultado de la solicitud. Una pregunta de opción única construida a mano nunca produce uno.
Contenido: editor_insertHeader, editor_insertParagraph, editor_insertImage, editor_insertList, editor_insertTable, editor_insertRow, editor_insertEmbedded, editor_insertPageDivider, editor_insertDocumentsBlock
Datos y lógica: editor_insertHiddenField, editor_insertCalculatedField, editor_insertVariable, editor_insertRepeatingGroup, editor_insertLogic

Compartir y resultados

formShareLink_list, formShareLink_create, formShareLink_update: gestiona enlaces de compartir, también en un dominio personalizado.
formSubmission_list: lista los envíos de un formulario, parciales y completados.
formAnalytics_get: vistas, envíos, tasa de finalización y desgloses por dispositivo, país, navegador y fuente.

Apariencia, ajustes y traducciones

formTheme_get, formTheme_set: temas claro y oscuro.
formSettings_get, formSettings_update: correos de notificación, redirección al completar, contraseña, retención e idioma.
translationLanguage_list, translationDraft_get, translationDraft_update, translationDraft_publish, translationLanguage_delete: traduce un formulario como borrador y luego publícalo.

Espacio de trabajo

workspace_list: el único espacio de trabajo al que llega tu conexión, con su ID.
workspaceFolder_list, workspaceFolder_create, workspaceFolder_update, workspaceFolder_delete: gestiona carpetas.

Guías integradas

Dos herramientas devuelven documentación en lugar de hacer trabajo:

load_skill carga una guía sobre un tema: requests, question-types, logic-rules, editing-flows, form-best-practices, form-themes, form-settings, analytics o toon-format.
load_tools carga notas de uso para un grupo de herramientas, llamado catálogo: request-lifecycle, editor-inserts, editor-actions, form-lifecycle, form-appearance, form-behavior, form-sharing, form-translations, form-data o workspace-management.

Cada guía y catálogo también es un recurso MCP en skill://<name>, como skill://requests. El servidor también sirve cuatro prompts: identity, capabilities, data_tools y editor_tools.

Herramientas que preguntan primero

Seis herramientas están marcadas como destructivas, porque deshacerlas requiere otra llamada o no es posible: form_delete, form_unpublish, workspaceFolder_delete, editor_deleteElement, translationLanguage_delete y request_cancel. La mayoría de las herramientas de IA te preguntan antes de ejecutarlas. El aviso proviene de tu herramienta de IA, así que revisa su configuración de aprobación si necesitas una parada firme.

Dos acciones no se pueden deshacer:

workspaceFolder_delete elimina permanentemente la carpeta, sus subcarpetas y todos los formularios dentro.
formShareLink_update con revoked: true desactiva permanentemente un enlace de compartir. Esta herramienta no está marcada como destructiva, así que tu herramienta de IA puede no preguntar primero.

Límites

Límite de velocidad. 120 llamadas de herramientas por minuto por token, compartido con la API REST. Solo tools/call cuenta. Si se supera el límite, la llamada devuelve un resultado de herramienta fallido con RATE_LIMITED y un retryAfterMs. request_create y document_create también comparten un segundo límite de 60 llamadas por minuto por token.
Asignación mensual. Cada request_create gasta una unidad de la asignación mensual del plan del propietario del espacio de trabajo, tanto si el destinatario responde como si no. Una solicitud de prueba (test: true) no gasta nada. Cuando la asignación se agota, request_create falla con MONTHLY_ALLOWANCE_REACHED.
Planes de pago. Enviar un correo a un destinatario (la invitación y los recordatorios) y formAnalytics_get requieren el plan Pro o Business. Consulta planes y precios.
Sin notificación cuando un destinatario envía. El servidor nunca llama a tu agente. Pregunta de nuevo más tarde, o pasa un callbackUrl a request_create para que formbase llame a tu endpoint (callbacks).
Sin subida de archivos mediante una llamada de herramienta. Las imágenes se establecen por URL: una URL http(s):// o un URI data:image. Un documento para una solicitud es la excepción: document_create devuelve una URL de subida a la que PUT el archivo dentro de una hora. Solo PDF e imágenes, 25 MB por archivo.
Sin habilidades de IA del espacio de trabajo. Las habilidades que escribas en formbase solo funcionan en el chat de IA integrado de formbase. Las guías propias del servidor (load_skill) funcionan a través de MCP.

Detalles del protocolo

Para cualquiera que escriba su propio cliente MCP o depure una conexión.

Transporte. HTTP de flujo continuo, solo POST. Cada respuesta es JSON. No hay flujo de eventos ni ID de sesión, por lo que cada llamada es independiente. Como exige la especificación MCP, envía Content-Type: application/json y Accept: application/json, text/event-stream.
Versión del protocolo. 2025-11-25.
Inicio de sesión. Cada llamada necesita Authorization: Bearer <token>, con initialize incluido. Sin uno, el servidor responde 401 con un encabezado WWW-Authenticate que apunta a https://api.formbase.so/.well-known/oauth-protected-resource. Desde allí, un cliente encuentra el servidor OAuth 2.1, que requiere PKCE (S256) y admite registro dinámico de clientes. La referencia enumera cada paso.
Tokens. Ambos tipos llegan a un espacio de trabajo y a las mismas herramientas.
- Un token de API comienza con fb_ y dura 30 días desde su creación.
- Un token de acceso OAuth comienza con fbo_ y dura 1 hora. Tu herramienta de IA lo renueva con un token de actualización, que dura 30 días y se reemplaza en cada uso.
Resultados. Un resultado de herramienta es un elemento de texto que contiene JSON. Un fallo tiene success: false y un mensaje error. Las herramientas de solicitud añaden un código de motivo como UNKNOWN_FIELD_KEY bajo details, y un suggestion que indica cómo corregir la llamada. Solución de problemas de solicitudes explica los más comunes.
Navegadores. El servidor solo permite llamadas de origen cruzado desde los sitios propios de formbase, por lo que una página web en otro origen no puede llamarlo directamente.

Documentación

Referencia del servidor MCP: cada herramienta, OAuth para tu propio cliente y límites
Conectar un agente de IA
Crear un formulario con un agente de IA
Enviar una solicitud con un agente de IA
Resumen de solicitudes, claves de campo y callbacks
Tokens de API y la API REST
Política de privacidad y términos de servicio

Reportar un problema

Envía un correo a support@formbase.so.
O abre un issue en este repositorio. Indica qué herramienta de IA usas, cómo inicia sesión, la herramienta que llamó y el error que recibió.

Los issues son públicos. Nunca pegues un token (fb_... o fbo_...) ni las respuestas de un destinatario en uno; en su lugar, envíanos un correo. Para reportar un problema de seguridad, consulta SECURITY.md.

Las correcciones a estos documentos son bienvenidas como pull requests.

Licencia

Los archivos de este repositorio tienen licencia MIT; consulta LICENSE. El uso del servicio formbase está cubierto por los términos de servicio.