formbase (formbase.so)

formbase.so coleta e verifica informações de clientes para fluxos de trabalho e agentes de IA

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Servidor MCP formbase

O servidor MCP hospedado para formbase.so. O formbase coleta e verifica informações de clientes para fluxos de trabalho e agentes de IA.

Seu agente cria uma solicitação para uma pessoa. Essa pessoa, o destinatário, recebe um formulário personalizado com o que você já sabe preenchido. Ela o completa em qualquer dispositivo, sem precisar de conta. O formbase devolve as respostas sob chaves de campo que seu agente pode ler.

O servidor está em:

https://api.formbase.so/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 identificada, 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.

MCP (Model Context Protocol) é o padrão que as ferramentas de IA usam para chamar outros aplicativos. A maioria das ferramentas de IA faz login no formbase com OAuth: você cola a URL, faz login no formbase no navegador e escolhe um espaço de trabalho. Scripts e agentes headless enviam um token de API em vez disso.

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 formbase a partir do servidor e se registra sozinha.

Claude Code

claude mcp add --transport http formbase https://api.formbase.so/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": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/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óvel.

Nos planos 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 plano Free, você pode adicionar um conector personalizado. O guia do próprio Claude: Comece com conectores personalizados.

Cursor

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

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

VS Code

Adicione isto a .vscode/mcp.json no seu projeto. Observe que o VS Code nomeia a chave de nível superior servers:

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

Ou execute MCP: Adicionar Servidor na Paleta de Comandos e cole a URL. Veja o guia MCP do VS Code.

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, formbase-requests. O plugin não executa nada na sua máquina. Ele chama um endpoint de rede, https://api.formbase.so/api/mcp, e faz login com OAuth do formbase, 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 também cobre ChatGPT e Codex.

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

Na primeira vez que o agente usar o formbase, sua ferramenta de IA abre uma página do formbase 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 formbase uma segunda vez e escolha o outro.

Para verificar se funciona, pergunte:

List my formbase forms and whether each one is published.

Para remover a conexão, abra Chaves OAuth e API na barra lateral do espaço de trabalho do formbase. 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 Chaves OAuth e 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 fb_.
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 formbase https://api.formbase.so/api/mcp \
  --header "Authorization: Bearer fb_YOUR_TOKEN"

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

{
  "mcpServers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_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 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.

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 formbase ainda envia ao destinatário os lembretes programados. Para evitar isso, diga também sem lembretes.

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

Has the formbase 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: Envie uma solicitação com um agente de IA e Crie 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 se conecta. A referência do servidor MCP as descreve em detalhes.

Solicitações

Peça informações a uma pessoa identificada e leia o resultado.

fields_list: liste as chaves de campo que uma solicitação pode usar 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 opção única criada 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 de um formulário, parciais e concluídos.
formAnalytics_get: visualizações, envios, taxa de conclusão e detalhamentos 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 confirmação 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 confirmação antes de executá-las. O aviso vem da sua ferramenta de IA, então verifique as configurações de aprovação dela 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 dela.
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 confirmação primeiro.

Limites

Limite de taxa. 120 chamadas de ferramenta por minuto por token, compartilhadas 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 formbase 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 skills de IA do workspace. As skills que você escreve no formbase funcionam apenas no chat de IA integrado do formbase. Os guias do próprio servidor (load_skill) funcionam via MCP.

Detalhes do protocolo

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

Transporte. HTTP Streamable, apenas POST. Cada resposta é JSON. Não há stream 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.formbase.so/.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 fb_ e dura 30 dias a partir da criação.
- Um token de acesso OAuth começa com fbo_ 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 diz como corrigir a chamada. Solução de problemas de solicitações explica os comuns.
Navegadores. O servidor permite chamadas de origem cruzada apenas dos próprios sites do formbase, 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
Conecte um agente de IA
Crie um formulário com um agente de IA
Envie uma solicitação com um agente de IA
Visão geral das 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@formbase.so.
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 (fb_... ou fbo_...) 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 estes documentos 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 formbase é coberto pelos termos de serviço.