# Servidor MCP

> Deja que Claude Code, Cursor, VS Code y otros agentes de IA gestionen formularios, envíos y webhooks a través del servidor MCP de Ikiform.

Ikiform ejecuta un servidor remoto de [Model Context Protocol](https://modelcontextprotocol.io). Conéctalo a un agente de IA y el agente podrá crear, conectar y configurar formularios, leer y clasificar envíos, y configurar y depurar webhooks en tu espacio de trabajo, con las mismas claves secretas y permisos que la [API REST](https://ikiform.com/es/docs/api.md).

|   |   |
| --- | --- |
| URL | `https://ikiform.com/mcp` |
| Transporte | Streamable HTTP, sin estado, JSON-RPC sobre `POST` |
| Autenticación | `Authorization: Bearer ik_sk_...` |
| Límite de frecuencia | 100 peticiones por minuto por clave, compartidas con la API REST |

## Crea una clave

En el [panel](https://ikiform.com/dashboard/api-keys), crea una clave **secreta** y dale solo los permisos que necesita el agente. Cada herramienta trabaja sobre el espacio de trabajo al que pertenece la clave. Mantén la clave fuera de tu repositorio: usa una variable de entorno o la solicitud de secretos de tu cliente.

| Permiso | Herramientas |
| --- | --- |
| `forms:read` | `list_forms`, `get_form` y `connect_form` con un `form_id` |
| `forms:write` | `create_form`, `update_form`, `set_form_fields`, `delete_form` |
| `submissions:read` | `list_submissions`, `get_submission` |
| `submissions:write` | `mark_spam`, `mark_not_spam`, `delete_submission` |
| `webhooks:read` | `list_webhook_endpoints`, `list_deliveries` |
| `webhooks:write` | `create_webhook_endpoint` y `update_webhook_endpoint` (con `submissions:read`), `roll_webhook_secret`, `delete_webhook_endpoint`, `send_test_event`, `replay_failed_deliveries` |

> Para conectar formularios en tu código bastan `forms:read` y `forms:write`. Para revisar envíos sin modificar nada, usa `submissions:read`. Una herramienta llamada sin su permiso devuelve un error `forbidden` que indica el permiso que falta.

## Conecta tu cliente

**Claude Code** (`Terminal`)

```bash
claude mcp add --transport http ikiform https://ikiform.com/mcp \
  --header "Authorization: Bearer ik_sk_..."
```

**Cursor** (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ikiform": {
      "url": "https://ikiform.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:IKIFORM_API_KEY}"
      }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "ikiform-api-key",
      "description": "Ikiform secret API key (ik_sk_...)",
      "password": true
    }
  ],
  "servers": {
    "ikiform": {
      "type": "http",
      "url": "https://ikiform.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ikiform-api-key}"
      }
    }
  }
}
```

**Otros clientes** (`mcp.json`)

```json
{
  "mcpServers": {
    "ikiform": {
      "type": "http",
      "url": "https://ikiform.com/mcp",
      "headers": { "Authorization": "Bearer ik_sk_..." }
    }
  }
}
```

En Cursor, define `IKIFORM_API_KEY` en tu entorno. VS Code te pide la clave la primera vez y la guarda de forma segura. Cualquier cliente que admita servidores HTTP remotos con cabeceras personalizadas funciona igual.

Ikiform figura en el [registro oficial de MCP](https://registry.modelcontextprotocol.io/v0/servers?search=ikiform) como `io.github.preetsuthar17/ikiform`. En Claude Code, el [plugin de Ikiform](https://github.com/preetsuthar17/ikiform-plugin) añade el servidor y un skill para conectar formularios: ejecuta `claude plugin marketplace add preetsuthar17/ikiform-plugin` y después `claude plugin install ikiform@ikiform`.

## Herramientas

Los ids tienen la forma `frm_...` para formularios, `sub_...` para envíos, `whk_...` para endpoints de webhook y `dlv_...` para entregas. Las listas devuelven 25 elementos por defecto y 100 como máximo; cuando `has_more` es true, pasa `next_cursor` como `cursor`.

| Herramienta | Qué hace |
| --- | --- |
| `list_forms` | Formularios, del más reciente al más antiguo, con id, nombre, estado, número de envíos y endpoint |
| `get_form` | El endpoint, los campos, el campo honeypot, los dominios permitidos, la URL de redirección, los fragmentos de código y las instrucciones de configuración de un formulario |
| `create_form` | Crea un formulario a partir de un nombre, con dominios permitidos y URL de redirección opcionales |
| `update_form` | Pausa o reanuda un formulario y cambia su nombre, dominios permitidos, URL de redirección, verificación antispam, límites de frecuencia o notificaciones por email |
| `set_form_fields` | Publica un esquema de campos contra el que se validan los envíos, o lo quita |
| `delete_form` | Elimina un formulario. Su endpoint deja de aceptar envíos |
| `list_submissions` | Envíos, del más reciente al más antiguo, filtrados por formulario, estado (`received` o `spam`) o fecha |
| `get_submission` | Un envío con sus campos, metadatos y puntuación de spam |
| `mark_spam`, `mark_not_spam` | Mueve un envío a spam o lo saca de ahí, enviando los webhooks correspondientes |
| `delete_submission` | Elimina un envío de forma permanente. No se puede deshacer |
| `list_webhook_endpoints` | Endpoints con su URL, estado, eventos y estado de fallos. Los secretos nunca se devuelven |
| `create_webhook_endpoint` | Añade un endpoint y devuelve su secreto de firma una sola vez |
| `update_webhook_endpoint` | Cambia la URL, el formulario, los eventos o las cabeceras personalizadas de un endpoint, o lo desactiva y lo activa |
| `roll_webhook_secret` | Devuelve un nuevo secreto de firma. El anterior sigue funcionando durante 24 horas |
| `delete_webhook_endpoint` | Elimina un endpoint y su historial de entregas |
| `list_deliveries` | Entregas recientes de un endpoint, con estado, intentos y el último error |
| `send_test_event` | Envía un evento `endpoint.test` firmado a un endpoint activo |
| `replay_failed_deliveries` | Vuelve a enviar las entregas fallidas de las últimas `24h`, `3d` o `7d` |

El servidor también ofrece un prompt `connect_form`: instrucciones paso a paso para conectar el formulario en tu proyecto, rellenadas con el endpoint y los campos de tu formulario cuando pasas un `form_id`.

## Qué pedir

- «Conecta el formulario de contacto de este proyecto a Ikiform.»
- «Muéstrame el spam de la semana pasada en el formulario de lista de espera y restaura todo lo que parezca real.»
- «¿Por qué falla mi webhook? Arregla el handler, envía una prueba y luego reenvía lo que falló hoy.»
- “Envía los nuevos registros de la lista de espera a mi ruta de API en /api/ikiform y pon el secreto en .env.”
- “Pausa el formulario de contacto antiguo y activa la verificación humana en el nuevo.”

Los agentes deberían confirmarlo contigo antes de eliminar formularios, envíos o endpoints, reenviar entregas, publicar un esquema de campos o cambiar dominios permitidos, ajustes de spam o límites de frecuencia. La skill del plugin de Claude Code se lo indica. Los secretos de firma y de Turnstile van en variables de entorno, nunca en el código.

## Solo en el panel

Las claves de API, los miembros, los destinatarios de notificaciones y la facturación se quedan en el panel, así que una clave filtrada no puede crear claves, invitar a personas, enviar emails a direcciones nuevas ni gastar dinero.