# Servidor MCP

> Deixe Claude Code, Cursor, VS Code e outros agentes de IA gerenciarem formulários, envios e webhooks pelo servidor MCP do Ikiform.

O Ikiform roda um servidor remoto de [Model Context Protocol](https://modelcontextprotocol.io). Conecte-o a um agente de IA e o agente pode criar, conectar e configurar formulários, ler e triar envios, e configurar e depurar webhooks no seu workspace, usando as mesmas chaves secretas e escopos da [API REST](https://ikiform.com/pt-br/docs/api.md).

|   |   |
| --- | --- |
| URL | `https://ikiform.com/mcp` |
| Transporte | Streamable HTTP, sem estado, JSON-RPC via `POST` |
| Autenticação | `Authorization: Bearer ik_sk_...` |
| Limite de taxa | 100 requisições por minuto por chave, compartilhadas com a API REST |

## Crie uma chave

No [painel](https://ikiform.com/dashboard/api-keys), crie uma chave **secreta** e dê a ela só os escopos de que o agente precisa. Toda ferramenta atua no workspace dono da chave. Mantenha a chave fora do seu repositório: use uma variável de ambiente ou o campo de segredo do seu cliente.

| Escopo | Ferramentas |
| --- | --- |
| `forms:read` | `list_forms`, `get_form` e `connect_form` com um `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` e `update_webhook_endpoint` (com `submissions:read`), `roll_webhook_secret`, `delete_webhook_endpoint`, `send_test_event`, `replay_failed_deliveries` |

> Para conectar formulários no seu código, `forms:read` e `forms:write` bastam. Para triagem só de leitura, use `submissions:read`. Uma ferramenta chamada sem o escopo dela retorna um erro `forbidden` que indica o escopo que falta.

## Conecte seu 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}"
      }
    }
  }
}
```

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

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

No Cursor, defina `IKIFORM_API_KEY` no seu ambiente. O VS Code pede a chave na primeira vez e a guarda com segurança. Qualquer cliente que suporte servidores HTTP remotos com headers personalizados funciona do mesmo jeito.

O Ikiform está listado no [registro oficial do MCP](https://registry.modelcontextprotocol.io/v0/servers?search=ikiform) como `io.github.preetsuthar17/ikiform`. No Claude Code, o [plugin do Ikiform](https://github.com/preetsuthar17/ikiform-plugin) adiciona o servidor e uma skill para conectar formulários: execute `claude plugin marketplace add preetsuthar17/ikiform-plugin` e depois `claude plugin install ikiform@ikiform`.

## Ferramentas

Os ids têm o formato `frm_...` para formulários, `sub_...` para envios, `whk_...` para endpoints de webhook e `dlv_...` para entregas. As listas retornam 25 itens por padrão e no máximo 100; quando `has_more` for true, passe `next_cursor` como `cursor`.

| Ferramenta | O que faz |
| --- | --- |
| `list_forms` | Formulários do mais recente ao mais antigo, com id, nome, status, número de envios e endpoint |
| `get_form` | O endpoint, os campos, o campo honeypot, os domínios permitidos, a URL de redirecionamento, os snippets de código e as instruções de configuração de um formulário |
| `create_form` | Cria um formulário a partir de um nome, com domínios permitidos e URL de redirecionamento opcionais |
| `update_form` | Pausa ou retoma um formulário e altera o nome, os domínios permitidos, a URL de redirecionamento, a verificação de spam, os limites de taxa ou as notificações por e-mail |
| `set_form_fields` | Publica um esquema de campos contra o qual os envios são validados, ou o remove |
| `delete_form` | Exclui um formulário. O endpoint dele para de aceitar envios |
| `list_submissions` | Envios do mais recente ao mais antigo, filtrados por formulário, status (`received` ou `spam`) ou data |
| `get_submission` | Um envio com seus campos, metadados e pontuação de spam |
| `mark_spam`, `mark_not_spam` | Move um envio para o spam ou de volta, enviando os webhooks correspondentes |
| `delete_submission` | Exclui um envio permanentemente. Não pode ser desfeito |
| `list_webhook_endpoints` | Endpoints com URL, status, eventos e estado de falha. Os segredos nunca são retornados |
| `create_webhook_endpoint` | Adiciona um endpoint e retorna o segredo de assinatura uma única vez |
| `update_webhook_endpoint` | Altera a URL, o formulário, os eventos ou os headers personalizados de um endpoint, ou o desativa e ativa |
| `roll_webhook_secret` | Retorna um novo segredo de assinatura. O antigo continua funcionando por 24 horas |
| `delete_webhook_endpoint` | Exclui um endpoint e o histórico de entregas dele |
| `list_deliveries` | Entregas recentes de um endpoint, com status, tentativas e o último erro |
| `send_test_event` | Envia um evento `endpoint.test` assinado para um endpoint ativo |
| `replay_failed_deliveries` | Reenvia as entregas que falharam nas últimas `24h`, `3d` ou `7d` |

O servidor também oferece um prompt `connect_form`: instruções passo a passo para conectar o formulário no seu projeto, preenchidas com o endpoint e os campos do seu formulário quando você passa um `form_id`.

## O que pedir

- “Conecte o formulário de contato deste projeto ao Ikiform.”
- “Mostre o spam da semana passada no formulário de lista de espera e restaure o que parecer real.”
- “Por que meu webhook está falhando? Corrija o handler, envie um teste e depois reenvie o que falhou hoje.”
- “Envie as novas inscrições da lista de espera para a minha rota de API em /api/ikiform e coloque o segredo no .env.”
- “Pause o formulário de contato antigo e ative a verificação humana no novo.”

Os agentes devem confirmar com você antes de excluir formulários, envios ou endpoints, reenviar entregas, publicar um esquema de campos ou alterar domínios permitidos, configurações de spam ou limites de taxa. A skill do plugin do Claude Code os orienta a fazer isso. Segredos de assinatura e do Turnstile ficam em variáveis de ambiente, nunca no código.

## Dashboard only

Chaves de API, membros, destinatários de notificação e cobrança ficam no painel, então uma chave que vaza não consegue criar chaves, convidar pessoas, enviar e-mail para novos endereços nem gastar dinheiro.