Formstep

Colete informações verificadas do cliente com uma única solicitação

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Servidor MCP Formstep

O servidor MCP hospedado para Formstep. Colete informações verificadas de clientes com uma única solicitação.

Seu agente envia uma solicitação para um cliente, o destinatário: um formulário com a sua marca e no idioma deles, pré-preenchido com o que você já sabe, para que eles apenas confirmem ou corrijam. Eles enviam arquivos, assinam, agendam ou pagam na mesma página, sem precisar de conta. As respostas voltam sob suas chaves de campo, com seu ID externo e, quando o formulário tem uma pergunta de decisão, um resultado de aprovação, recusa ou alterações. Seu agente as lê com request_get, ou o Formstep chama sua URL de callback no momento em que o destinatário envia.

O servidor está em:

https://api.formstep.io/api/mcp

Este repositório contém documentação, exemplos de configuração e um manifesto de plugin Grok Build. Não há nada para instalar ou executar.

O que um agente pode fazer
Conecte sua ferramenta de IA
Experimente
Ferramentas
Limites
Detalhes do protocolo
Documentação
Relatar um problema

O que um agente pode fazer

Enviar solicitações. Peça informações a uma pessoa específica, com respostas preenchidas ou bloqueadas, e leia o que ela respondeu.
Criar formulários. Crie um formulário e adicione, edite ou remova suas perguntas, páginas e lógica.
Publicar e compartilhar. Publique um formulário, crie links de compartilhamento, traduza-o e defina seu tema e configurações.
Ler resultados. Liste os envios de um formulário e leia suas análises.

A maioria das ferramentas de IA faz login no Formstep com OAuth: você cola a URL, faz login no Formstep no navegador e escolhe um espaço de trabalho. Scripts e agentes headless enviam um token de API.

Conecte sua ferramenta de IA

Deixe qualquer campo de ID de cliente, segredo ou token vazio. A ferramenta de IA encontra a página de login do Formstep a partir do servidor e se registra.

Claude Code

claude mcp add --transport http formstep https://api.formstep.io/api/mcp

Depois digite /mcp no Claude Code para fazer login.

Para compartilhar o servidor com todos que trabalham em um projeto, envie um .mcp.json para o projeto:

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

Claude desktop e claude.ai

Abra Personalizar › Conectores › + › Adicionar conector personalizado e cole a URL. Um conector adicionado no claude.ai também funciona nos aplicativos desktop e móveis.

No Team e Enterprise, um proprietário adiciona o conector primeiro em Configurações da organização › Conectores. Os membros então clicam em Conectar nele. No Free, você pode adicionar um conector personalizado. O guia do próprio Claude: Comece com conectores personalizados.

ChatGPT

Ative o modo de desenvolvedor em Configurações › Aplicativos › Configurações avançadas. Depois abra Configurações › Aplicativos › Criar, cole a URL, escolha OAuth, clique em Escanear ferramentas, faça login no Formstep e clique em Criar.

O modo de desenvolvedor funciona apenas na web. No Pro, o ChatGPT só pode ler: ferramentas que alteram algo, como enviar uma solicitação ou editar um formulário, precisam de Business, Enterprise ou Edu. No Business, apenas administradores e proprietários podem usar o modo de desenvolvedor. O guia da própria OpenAI: Modo de desenvolvedor e aplicativos MCP no ChatGPT.

Cursor

Adicione isso ao .cursor/mcp.json no seu projeto, ou ao ~/.cursor/mcp.json para todos os projetos:

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

Cline

O Cline conecta com um token de API (veja abaixo como criar um). Adicione isso ao cline_mcp_settings.json do Cline:

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

Ou peça ao Cline para instalá-lo: llms-install.md tem os passos que ele segue.

Grok Build

Este repositório também é um plugin Grok Build: .grok-plugin/plugin.json, a configuração do servidor .mcp.json e uma habilidade, formstep-requests. O plugin não executa nada na sua máquina. Ele chama um endpoint de rede, https://api.formstep.io/api/mcp, e faz login com OAuth do Formstep, ou com um token de API que você adiciona como cabeçalho.

Outras ferramentas

Qualquer ferramenta que suporte servidores MCP remotos com login funciona da mesma forma: procure onde ela adiciona um servidor por URL. O guia de conexão vincula as instruções de cada ferramenta.

Faça login e escolha um espaço de trabalho

Na primeira vez que o agente usa o Formstep, sua ferramenta de IA abre uma página do Formstep no navegador. Faça login, escolha o espaço de trabalho e clique em Autorizar.

Uma conexão alcança apenas esse espaço de trabalho. Para usar outro espaço de trabalho, adicione o Formstep uma segunda vez e escolha o outro.

Para verificar se funciona, pergunte:

List my Formstep forms and whether each one is published.

Para remover a conexão, abra OAuth e Chaves de API na barra lateral do espaço de trabalho do Formstep. Em Aplicativos conectados, clique no ícone de lixeira ao lado da conexão e confirme com Desconectar.

Scripts e agentes headless: use um token de API

Qualquer coisa que não possa abrir um navegador, como um script, um trabalho de CI ou um agente headless, envia um token de API como cabeçalho.

Abra OAuth e Chaves de API na barra lateral do seu espaço de trabalho e clique em Criar token (Tokens de API).
Copie o token. Ele começa com fs_.
Envie-o como um cabeçalho Authorization: Bearer.

Um token alcança exatamente um espaço de trabalho, como uma conexão OAuth. Ele expira 30 dias após a criação e não pode ser estendido, então planeje substituí-lo. Mantenha-o fora do git.

Claude Code, pela linha de comando:

claude mcp add --transport http formstep https://api.formstep.io/api/mcp \
  --header "Authorization: Bearer fs_YOUR_TOKEN"

Ou em um arquivo de configuração. Este é o .mcp.json para Claude Code; o Cursor aceita o mesmo objeto headers em seu mcp.json:

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

Outras ferramentas usam a mesma URL e cabeçalho. Veja a documentação delas para saber onde.

Experimente

Envie uma solicitação para uma pessoa. Use o nome de um dos seus formulários 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.

O agente lê as chaves de campo do formulário com fields_list, cria a solicitação com request_create e fornece o link da solicitação.

Se o formulário tiver Enviar lembretes ativado, o Formstep ainda envia ao destinatário os lembretes programados. Para evitar isso, diga também sem lembretes.

O agente não é informado quando o destinatário envia, então pergunte mais tarde:

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

O agente encontra a solicitação pelo ID externo com request_list e depois a lê com request_get. Quando a solicitação é concluída, as respostas voltam organizadas por chave de campo.

Passo a passo: Enviar uma solicitação com um agente de IA e Criar um formulário com um agente de IA.

Ferramentas

Toda ferramenta está em tools/list com seu esquema de entrada completo assim que uma ferramenta de IA conecta. A referência do servidor MCP as descreve em detalhes.

Solicitações

Peça informações a uma pessoa específica e leia o resultado.

fields_list: liste as chaves de campo que uma solicitação pode abordar em um formulário publicado. Chame antes de request_create.
request_create: atribua um formulário publicado a um destinatário, com pré-preenchimento, campos bloqueados, contexto, entrega, expiração e um callback opcional.
request_get: leia uma solicitação pelo ID. Retorna o status, a linha do tempo e, quando concluída, as respostas organizadas por chave de campo.
request_list: liste solicitações de um formulário ou espaço de trabalho, filtradas por status, resultado ou seu próprio ID externo.
request_cancel: retire uma solicitação pendente.
request_remind: envie um e-mail de lembrete ao destinatário agora.
request_replayCallback: envie um callback novamente quando ele nunca chegou ao seu endpoint.
document_create: reserve um upload para um arquivo que uma solicitação entrega ao destinatário. Um upload pode atender a qualquer número de solicitações.

Formulários

form_list, form_get, form_create, form_update: encontre, leia, crie e renomeie formulários, e defina a pasta, emoji, capa e logotipo.
form_publish, form_unpublish: comece e pare de aceitar envios. form_publish é seguro chamar duas vezes.
form_delete, form_restore: mova um formulário para a lixeira, o que também revoga seus links de compartilhamento, e traga-o de volta.

form_get retorna as perguntas da última versão publicada. Para um rascunho, leia o conteúdo com editor_getDocument.

Editor

editor_getDocument: leia a estrutura completa de um formulário.
editor_updateElement, editor_deleteElement: edite, mova ou remova um bloco.
editor_formatText: formate texto dentro de um bloco.
editor_setLogic, editor_testLogic: altere a regra de um bloco de lógica e teste-a. Crie o bloco com editor_insertLogic.

Cada tipo de bloco tem sua própria ferramenta de inserção com um esquema preciso:

Perguntas: 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
Decisão: editor_insertDecisionQuestion insere a escolha aprovar / recusar / alterar cuja resposta se torna o resultado da solicitação. Uma pergunta de rádio construída manualmente nunca produz um.
Conteúdo: editor_insertHeader, editor_insertParagraph, editor_insertImage, editor_insertList, editor_insertTable, editor_insertRow, editor_insertEmbedded, editor_insertPageDivider, editor_insertDocumentsBlock
Dados e lógica: editor_insertHiddenField, editor_insertCalculatedField, editor_insertVariable, editor_insertRepeatingGroup, editor_insertLogic

Compartilhamento e resultados

formShareLink_list, formShareLink_create, formShareLink_update: gerencie links de compartilhamento, também em um domínio personalizado.
formSubmission_list: liste os envios concluídos de um formulário, e rascunhos sob solicitação.
formAnalytics_get: visualizações, envios, taxa de conclusão e visitantes únicos por dispositivo, país, navegador e origem.

Aparência, configurações e traduções

formTheme_get, formTheme_set: temas claro e escuro.
formSettings_get, formSettings_update: e-mails de notificação, redirecionamento de conclusão, senha, retenção e idioma.
translationLanguage_list, translationDraft_get, translationDraft_update, translationDraft_publish, translationLanguage_delete: traduza um formulário como rascunho e depois publique-o.

Espaço de trabalho

workspace_list: o único espaço de trabalho que sua conexão alcança, com seu ID.
workspaceFolder_list, workspaceFolder_create, workspaceFolder_update, workspaceFolder_delete: gerencie pastas.

Guias integrados

Duas ferramentas retornam documentação em vez de fazer trabalho:

load_skill carrega um guia sobre um tópico: requests, question-types, logic-rules, editing-flows, form-best-practices, form-themes, form-settings, analytics ou toon-format.
load_tools carrega notas de uso para um grupo de ferramentas, chamado catálogo: request-lifecycle, editor-inserts, editor-actions, form-lifecycle, form-appearance, form-behavior, form-sharing, form-translations, form-data ou workspace-management.

Todo guia e catálogo também é um recurso MCP em skill://<name>, como skill://requests. O servidor também serve quatro prompts: identity, capabilities, data_tools e editor_tools.

Ferramentas que pedem primeiro

Seis ferramentas são marcadas como destrutivas, porque desfazê-las exige outra chamada ou não é possível: form_delete, form_unpublish, workspaceFolder_delete, editor_deleteElement, translationLanguage_delete e request_cancel. A maioria das ferramentas de IA pede sua confirmação antes de executá-las. O prompt vem da sua ferramenta de IA, então verifique as configurações de aprovação se precisar de uma parada rígida.

Duas ações não podem ser desfeitas:

workspaceFolder_delete exclui permanentemente a pasta, suas subpastas e todos os formulários dentro.
formShareLink_update com revoked: true desativa permanentemente um link de compartilhamento. Esta ferramenta não é marcada como destrutiva, então sua ferramenta de IA pode não pedir antes.

Limites

Limite de taxa. 120 chamadas de ferramenta por minuto por token, compartilhado com a API REST. Apenas tools/call conta. Acima do limite, a chamada retorna um resultado de ferramenta com falha com RATE_LIMITED e um retryAfterMs. request_create e document_create também compartilham um segundo limite de 60 chamadas por minuto por token.
Cota mensal. Cada request_create gasta uma unidade da cota mensal do plano do proprietário do workspace, independentemente de o destinatário responder ou não. Uma solicitação de teste (test: true) não gasta nada. Quando a cota é gasta, request_create falha com MONTHLY_ALLOWANCE_REACHED.
Planos pagos. Enviar e-mail a um destinatário (o convite e lembretes) e formAnalytics_get exigem o plano Pro ou Business. Consulte planos e preços.
Sem notificação quando um destinatário envia. O servidor nunca chama seu agente. Pergunte novamente mais tarde, ou passe um callbackUrl para request_create para que o Formstep chame seu endpoint (callbacks).
Sem uploads de arquivos por chamada de ferramenta. As imagens são definidas por URL: uma URL http(s):// ou um URI data:image. Um documento para uma solicitação é a exceção: document_create retorna uma URL de upload para a qual você PUT o arquivo dentro de uma hora. Apenas PDF e imagens, 25 MB por arquivo.
Sem habilidades de IA do workspace. As habilidades que você escreve no Formstep funcionam apenas no chat de IA integrado do Formstep. Os guias próprios do servidor (load_skill) funcionam via MCP.

Detalhes do protocolo

Para quem escreve seu próprio cliente MCP ou depura uma conexão.

Transporte. HTTP transmitível, apenas POST. Cada resposta é JSON. Não há fluxo de eventos nem ID de sessão, então cada chamada é independente. Conforme exigido pela especificação MCP, envie Content-Type: application/json e Accept: application/json, text/event-stream.
Versão do protocolo. 2025-11-25.
Login. Cada chamada precisa de Authorization: Bearer <token>, com initialize incluído. Sem um, o servidor responde 401 com um cabeçalho WWW-Authenticate que aponta para https://api.formstep.io/.well-known/oauth-protected-resource. A partir daí, um cliente encontra o servidor OAuth 2.1, que exige PKCE (S256) e suporta registro dinâmico de clientes. A referência lista cada etapa.
Tokens. Ambos os tipos alcançam um workspace e as mesmas ferramentas.
- Um token de API começa com fs_ e dura 30 dias a partir da criação.
- Um token de acesso OAuth começa com fso_ e dura 1 hora. Sua ferramenta de IA o renova com um token de atualização, que dura 30 dias e é substituído a cada uso.
Resultados. Um resultado de ferramenta é um item de texto que contém JSON. Uma falha tem success: false e uma mensagem error. As ferramentas de solicitação adicionam um código de motivo, como UNKNOWN_FIELD_KEY, sob details, e um suggestion que explica como corrigir a chamada. Solução de problemas de solicitações explica os comuns.
Navegadores. O servidor permite chamadas entre origens apenas dos próprios sites do Formstep, então uma página da web em outra origem não pode chamá-lo diretamente.

Documentação

Referência do servidor MCP: cada ferramenta, OAuth para seu próprio cliente e limites
Conectar um agente de IA
Criar um formulário com um agente de IA
Enviar uma solicitação com um agente de IA
Visão geral de solicitações, chaves de campo e callbacks
Tokens de API e a API REST
Política de privacidade e termos de serviço

Relatar um problema

Envie um e-mail para support@formstep.io.
Ou abra uma issue neste repositório. Diga qual ferramenta de IA você usa, como ela faz login, a ferramenta que chamou e o erro que recebeu.

As issues são públicas. Nunca cole um token (fs_... ou fso_...) ou as respostas de um destinatário em uma; envie-nos um e-mail. Para relatar um problema de segurança, consulte SECURITY.md.

Correções a esta documentação são bem-vindas como pull requests.

Licença

Os arquivos neste repositório são licenciados sob MIT; consulte LICENSE. O uso do serviço Formstep é coberto pelos termos de serviço.