Fillo

Docs · Guides · Agents · Changelog

O servidor MCP Fillo. Ele dá a um agente de codificação o ciclo completo do Fillo — provisionar um workspace, criar um formulário no repositório do host, publicá-lo e consultar suas respostas — sem sair da sessão, autenticado exatamente como um usuário humano de CLI.

Instalação

Um clique, se o seu editor suportar:

Claude Code:

claude mcp add fillo -- npx -y @usefillo/mcp

Qualquer outro cliente MCP: execute npx -y @usefillo/mcp via stdio. Defina FILLO_API para apontar para uma implantação que não seja de produção.

Credenciais

O servidor lê as mesmas credenciais que a CLI grava em ~/.fillo/config.json, ou do ambiente:

• FILLO_TOKEN — um token de login fcli_… (de npx @usefillo/cli login). Ferramentas autenticadas (fillo_list_forms, fillo_publish_form e pushes confiáveis para um workspace reivindicado), além de seleção local de projeto com um login comum. Pushes de solicitação de arquivo permanecem como rascunho/encenados para revisão.
• FILLO_PK — uma chave publicável pk_…. fillo_provision_workspace gera uma e a salva para você.
• FILLO_API_KEY — uma chave de API de projeto fsk_…, gerada em Configurações → Conexões de um workspace reivindicado. Necessária pelas ferramentas de resposta.
• FILLO_API — substitui a origem (padrão https://fillo.so).
• FILLO_CONFIG_DIR — substitui o diretório de configuração (padrão ~/.fillo).

O servidor nunca imprime tokens de login, chaves de API ou tokens de reivindicação no transcript. A chave publicável pk_ é segura para exibir (ela vive no código do navegador), então fillo_provision_workspace a retorna para você conectá-la ao env público do aplicativo. O provisionamento também torna esse projeto temporário o contexto MCP local ativo, para que um login de conta salvo mais antigo não possa receber o próximo push. Selecionar um projeto muda o contexto de volta para a conta.

Ferramentas

Ferramenta	Auth	O que faz
fillo_provision_workspace	nenhuma (precisa de um e-mail)	Cria um workspace de pré-visualização não reivindicado, retorna sua chave pk_ e limites, e envia por e-mail o link de reivindicação.
fillo_whoami	token de login ou pk_	Relata a credencial, o workspace e o projeto ativos.
fillo_list_projects	token de login comum	Lista projetos no workspace atual e marca a seleção atual.
fillo_create_project	token de login comum	Cria e seleciona um projeto isolado e salva sua chave pk_.
fillo_select_project	token de login comum	Seleciona por id, slug ou nome exato único e atualiza o estado local do projeto.
fillo_push_form	token de login ou pk_	Cria ou atualiza um formulário e publica por padrão; defina publish: false com um token de login para fluxos de revisão explícitos. Solicitações de arquivo bloqueadas por armazenamento permanecem como rascunho.
fillo_publish_form	token de login	Leva um rascunho ou alterações encenadas para produção após revisão; retorna o link exato de configuração de armazenamento quando bloqueado.
fillo_list_forms	token de login	Lista os formulários do projeto.
fillo_get_form	nenhuma (publicado)	Busca o esquema, tema e capacidades de um formulário publicado.
fillo_search_examples	nenhuma	Pesquisa a biblioteca de exemplos curada do Fillo.
fillo_docs	nenhuma	Busca uma página de docs do Fillo como Markdown por tópico.
fillo_list_responses	token de login ou chave fsk_	Lista as respostas aceitas de um formulário (somente workspaces reivindicados).
fillo_search_library / fillo_get_library_form	nenhuma	Pesquisa e lê a biblioteca pública de formulários.
fillo_get_response	chave de API fsk_	Busca uma resposta (somente workspaces reivindicados).
fillo_response_summary	chave de API fsk_	Resume as respostas de um formulário sem ler cada linha (somente workspaces reivindicados).
fillo_claim_status	pk_	Relata os limites do workspace provisionado e o prazo de reivindicação.

Gerenciando um workspace reivindicado

Tudo o que um membro pode fazer no painel do Fillo também tem uma ferramenta, sob o MESMO NOME que o servidor MCP hospedado do Fillo usa — um nome, uma capacidade, qualquer servidor que seu agente alcançou. Cada uma chama a rota HTTP que a CLI do Fillo chama: seu token de login fcli_ quando você tem um (npx @usefillo/cli login ou FILLO_TOKEN), caso contrário uma chave de API de projeto fsk_ em FILLO_API_KEY carregando o escopo nomeado. Com ambos, o token de login vence — uma chave não tem humano atuante.

Área	Ferramentas	Escopo
Ciclo de vida do formulário	fillo_pull_form, fillo_rename_form, fillo_duplicate_form, fillo_unpublish_form, fillo_discard_changes, fillo_delete_form, fillo_list_versions	forms:read, forms:write
Logo	fillo_import_logo — baixe um PNG, JPEG ou WebP de uma URL https pública; coloque o id retornado no logo ou dark.logo do tema	forms:write
Uploads	fillo_get_storage, fillo_set_storage, fillo_list_drive_folders, fillo_set_drive_folder, fillo_reset_drive_folder	storage:manage
Configurações	fillo_get_settings, fillo_update_settings	settings:manage (mais forms:write para as chaves de apresentação)
Destinos	fillo_get_integration, fillo_enable_integration, fillo_disable_integration, fillo_list_connections, fillo_select_connection, fillo_disconnect_integration, fillo_remove_connection_account, fillo_rename_discord_channel, fillo_hubspot_properties, fillo_hubspot_pipelines	integrations:manage
Respostas e entrega	fillo_list_held_responses, fillo_release_responses, fillo_delete_response, fillo_delivery_status, fillo_retry_deliveries, fillo_redeliver_responses, fillo_list_drafts, fillo_form_insights, fillo_list_respondents, fillo_delete_respondent	responses:manage, respondents:*; fillo_form_insights precisa de forms:read e responses:read
Webhooks	fillo_list_webhooks, fillo_add_webhook, fillo_update_webhook, fillo_remove_webhook	webhooks:manage
Workspace	fillo_rename_workspace, fillo_rename_project, fillo_get_branding, fillo_set_branding, fillo_get_billing, fillo_list_members, fillo_invite_member, fillo_change_member_role, fillo_remove_member	workspace:manage, members:manage
Credenciais	fillo_list_tokens, fillo_revoke_token, fillo_list_sync_tokens, fillo_create_sync_token, fillo_revoke_sync_token, fillo_list_api_keys, fillo_revoke_api_key, fillo_list_agents, fillo_revoke_agent	workspace:manage
Configurações de desenvolvedor	fillo_get_code_sync_policy, fillo_set_code_sync_policy, fillo_get_origins, fillo_set_origins, fillo_identity_status, fillo_enable_identity, fillo_disable_identity	workspace:manage

fillo_delete_form, fillo_get_branding, fillo_set_branding, fillo_get_billing, fillo_list_api_keys e fillo_revoke_api_key precisam de um token de login — não há rota de chave de API de projeto para eles, então uma chave vazada nunca pode enumerar ou revogar as credenciais do workspace ou ler seu plano. fillo_get_billing é somente leitura: relata o plano e o uso deste mês e retorna o link de Configurações, mas nenhuma ferramenta pode assinar, mudar o plano ou abrir checkout — um proprietário ou administrador faz isso em Configurações → Cobrança e plano. fillo_delete_response também precisa de um, por um motivo diferente: sua rota com escopo não aceita confirmação digitada, então em uma chave de API de projeto a confirmação seria verificada apenas pelo chamador, o que não é confirmação alguma.

A URL de destino de um webhook é uma credencial — o caminho de um catch hook do Zapier ou um webhook do n8n é o que autoriza postar nele — então fillo_delivery_status nomeia destinos sem soletrá-los: hooks de propriedade do conector voltam como "Zapier" ou "n8n", e outros webhooks como seu host mais uma impressão digital curta do caminho. Leia a URL completa na página de Atividade do painel.

A camada humana

Ações rotineiras e reversíveis rodam apenas com a credencial. Dois tipos não:

• Para fora — despublicar, iniciar um destino de terceiros, adicionar um webhook, liberar ou reenviar respostas, convidar um membro ou mudar um papel, uma política de sincronização de código, as origens permitidas ou verificação de identidade. Essas exigem confirm: true, e a ferramenta recusa sem isso com uma mensagem dizendo ao modelo para perguntar a uma pessoa primeiro. Nada mudou quando ela recusa. Publicar é a exceção neste servidor: fillo_push_form e fillo_publish_form não exigem confirm, porque um token de login É a pessoa que executou fillo login nesta máquina — o mesmo motivo pelo qual fillo publish roda sem uma flag. O servidor OAuth hospedado, onde a concessão pertence a um agente em vez de a você, é o que bloqueia a publicação atrás de um link de aprovação.
• Destrutivas — excluir um formulário, uma resposta ou um respondente, remover um membro ou uma conta de integração, desconectar um provedor ou um servidor Discord, revogar um token, token de sincronização, chave de API ou concessão MCP, desligar a verificação de identidade. Essas exigem confirm como uma string que deve ser exatamente igual ao alvo — o e-mail de um membro, um id de token, um id de resposta — e o servidor compara, então um palpite é um 409 que cita o valor para tentar novamente.

Um segredo que o Fillo gera uma vez (um segredo de assinatura de webhook, um token fsync_, um segredo de verificação de identidade) é retornado naquele único resultado de ferramenta e nunca mais. Armazene-o em um gerenciador de segredos; ele nunca é gravado em um log.

Anotações de escrita usam a dica de pior caso conservadora porque um push pode substituir o estado de rascunho e uma publicação pode substituir o esquema público, e openWorldHint marca exatamente as ações cujo efeito sai do workspace. Cada ferramenta é um wrapper fino sobre a API HTTP pública do Fillo — o servidor nunca toca no banco de dados e não importa código do aplicativo, então escopo de workspace, limites de taxa, autorização e validação ficam em um só lugar.

As três ferramentas de projeto são somente locais e exigem o token geral gerado por fillo login. Uma transferência específica de projeto e uma concessão OAuth hospedada de MCP remoto permanecem vinculadas ao projeto que um humano aprovou. Selecionar localmente também limpa o estado em cache de pré-visualização e fsk_ do projeto anterior; substitua quaisquer substituições de ambiente FILLO_PK ou FILLO_API_KEY você mesmo.

Projetos são sites/aplicativos sob um workspace faturado. Eles isolam formulários, chaves publicáveis/API, origens permitidas, identidades de respondentes e autoridade de agente. Associação ao workspace, cobrança, conexões de armazenamento e totais de uso permanecem compartilhados.

Links

• Docs: fillo.so/docs
• Site: fillo.so

Licenciado sob MIT.