Formstep

Recopila información verificada del cliente con una sola solicitud

Servidor MCP alojado

npx add-mcp 'https://api.formstep.io/api/mcp'

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

Documentación

Servidor MCP de Formstep

El servidor MCP alojado para Formstep. Recopila información verificada de clientes con una sola solicitud.

Tu agente envía una solicitud a un cliente, el destinatario: un formulario con tu marca y en su idioma, precargado con lo que ya sabes, para que solo confirme o corrija. Suben archivos, firman, reservan o pagan en la misma página, sin necesidad de cuenta. Las respuestas vuelven bajo tus claves de campo, con tu ID externo y, cuando el formulario tiene una pregunta de decisión, un resultado de aprobar, rechazar o cambios. Tu agente las lee con request_get, o Formstep llama a tu URL de callback en el momento en que el destinatario envía.

El servidor está en:

https://api.formstep.io/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 rellenadas o bloqueadas, y lee lo que respondieron.
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 para compartir, tradúcelo y configura su tema y ajustes.
Leer resultados. Lista los envíos de un formulario y lee sus estadísticas.

La mayoría de las herramientas de IA inician sesión en Formstep con OAuth: pegas la URL, inicias sesión en Formstep 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 Formstep desde el servidor y se registra sola.

Claude Code

claude mcp add --transport http formstep https://api.formstep.io/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 en su lugar:

{
  "mcpServers": {
    "formstep": {
      "type": "http",
      "url": "https://api.formstep.io/api/mcp"
    }
  }
}

Claude desktop 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 primero el conector 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 propia de Claude: Empieza con conectores personalizados.

ChatGPT

Activa el modo desarrollador en Configuración › Aplicaciones › Configuración avanzada. Luego abre Configuración › Aplicaciones › Crear, pega la URL, elige OAuth, haz clic en Escanear herramientas, inicia sesión en Formstep y haz clic en Crear.

El modo desarrollador funciona solo en la web. En Pro, ChatGPT solo puede leer: las herramientas que cambian algo, como enviar una solicitud o editar un formulario, necesitan Business, Enterprise o Edu. En Business, solo administradores y propietarios pueden usar el modo desarrollador. La guía propia de OpenAI: Modo desarrollador y aplicaciones MCP en ChatGPT.

Cursor

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

{
  "mcpServers": {
    "formstep": {
      "url": "https://api.formstep.io/api/mcp"
    }
  }
}

Cline

Cline se conecta con un token de API (ver abajo para saber cómo crear uno). Añade esto a cline_mcp_settings.json de Cline:

{
  "mcpServers": {
    "formstep": {
      "type": "streamableHttp",
      "url": "https://api.formstep.io/api/mcp",
      "headers": {
        "Authorization": "Bearer fs_YOUR_TOKEN"
      }
    }
  }
}

O pide a Cline que lo instale: llms-install.md tiene los pasos que sigue.

Grok Build

Este repositorio también es un plugin de Grok Build: .grok-plugin/plugin.json, la .mcp.json configuración del servidor y una habilidad, formstep-requests. El plugin no ejecuta nada en tu máquina. Llama a un endpoint de red, https://api.formstep.io/api/mcp, e inicia sesión con OAuth de Formstep, 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 enlaza las instrucciones propias de cada herramienta.

Inicia sesión y elige un espacio de trabajo

La primera vez que el agente usa Formstep, tu herramienta de IA abre una página de Formstep 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 Formstep una segunda vez y elige el otro.

Para comprobar que funciona, pregunta:

List my Formstep 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 Formstep. 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 fs_.
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 formstep https://api.formstep.io/api/mcp \
  --header "Authorization: Bearer fs_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": {
    "formstep": {
      "type": "http",
      "url": "https://api.formstep.io/api/mcp",
      "headers": {
        "Authorization": "Bearer fs_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 Formstep request with the "Supplier onboarding" form to Ada Lovelace (ada@acme.example). Fill in the company name "Analytical Engines Ltd" and lock it so it cannot be changed. Use supplier-2041 as the external ID. Don't send the invitation email; 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, Formstep igualmente envía al destinatario sus recordatorios programados. Para evitarlo, di también sin recordatorios.

El agente no se entera cuando el destinatario envía, así que pregúntale más tarde:

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

El agente encuentra la solicitud por su ID externo con request_list, luego la lee con request_get. Una vez completada la solicitud, las respuestas vuelven con clave 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 precarga, 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 clave 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: empieza y deja de aceptar 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 para compartir, y lo recupera.

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 múltiple 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 para compartir, también en un dominio personalizado.
formSubmission_list: lista los envíos completados de un formulario, y borradores si se piden.
formAnalytics_get: vistas, envíos, tasa de finalización y visitantes únicos 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 es también 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 viene 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 para 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 Formstep 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 Formstep solo funcionan en el chat de IA integrado de Formstep. 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 transmisible, 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>, incluido initialize. Sin uno, el servidor responde 401 con un encabezado WWW-Authenticate que apunta a https://api.formstep.io/.well-known/oauth-protected-resource. Desde allí, un cliente encuentra el servidor OAuth 2.1, que requiere PKCE (S256) y admite el 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 fs_ y dura 30 días desde su creación.
- Un token de acceso OAuth comienza con fso_ 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 Formstep, 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@formstep.io.
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 (fs_... o fso_...) 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 Formstep está cubierto por los términos de servicio.