Fillo

Docs · Guides · Agents · Changelog

The Fillo MCP server. It gives a coding agent the full Fillo loop — provision a workspace, scaffold a form into the host repo, publish it, and query its responses — without leaving the session, authenticated exactly like a human CLI user.

Install

One click, if your editor supports it:

Claude Code:

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

Any other MCP client: run npx -y @usefillo/mcp over stdio. Set FILLO_API to point at a non-production deployment.

Credentials

The server reads the same credentials the CLI writes to ~/.fillo/config.json, or from the environment:

• FILLO_TOKEN — a fcli_… login token (from npx @usefillo/cli login). Authenticated tools (fillo_list_forms, publishing to a claimed workspace, and local project selection with an ordinary login).
• FILLO_PK — a pk_… publishable key. fillo_provision_workspace mints one and saves it for you.
• FILLO_API_KEY — a fsk_… project API key, minted in Settings → Connections of a claimed workspace. Required by the response tools.
• FILLO_API — overrides the origin (default https://fillo.so).
• FILLO_CONFIG_DIR — overrides the config directory (default ~/.fillo).

The server never prints login tokens, API keys, or claim tokens into the transcript. The pk_ publishable key is safe to surface (it lives in browser code), so fillo_provision_workspace returns it for you to wire into the app's public env.

Tools

Tool	Auth	What it does
fillo_provision_workspace	none (needs an email)	Create an unclaimed preview workspace, return its pk_ key and caps, and email its claim link.
fillo_whoami	login token or pk_	Report the active credential, workspace, and project.
fillo_list_projects	ordinary login token	List projects in the current workspace and mark the current selection.
fillo_create_project	ordinary login token	Create and select an isolated project and save its pk_ key.
fillo_select_project	ordinary login token	Select by id, slug, or unique exact name and update local project state.
fillo_push_form	login token or pk_	Create or update a form from a schema + handle.
fillo_list_forms	login token	List the project's forms.
fillo_get_form	none (published)	Fetch a published form's schema, theme, and capabilities.
fillo_search_examples	none	Search the curated Fillo example library.
fillo_docs	none	Fetch a Fillo docs page as Markdown by topic.
fillo_list_responses	fsk_ API key	List a form's responses (claimed workspaces only).
fillo_get_response	fsk_ API key	Fetch one response (claimed workspaces only).
fillo_response_summary	fsk_ API key	Summarize a form's responses without reading every row (claimed workspaces only).
fillo_claim_status	pk_	Report the provisioned workspace's caps and claim deadline.

No destructive tools. Every tool is a thin wrapper over Fillo's public HTTP API — the server never touches the database and imports no app code, so workspace scoping, rate limits, and validation stay in one place.

The three project tools are local-only and require the general token minted by fillo login. A project-specific handoff and a hosted remote-MCP OAuth grant remain pinned to the project a human approved. Selecting locally also clears cached preview and fsk_ state from the prior project; replace any FILLO_PK or FILLO_API_KEY environment overrides yourself.

Projects are sites/apps beneath one billed workspace. They isolate forms, publishable/API keys, allowed origins, respondent identities, and agent authority. Workspace membership, billing, storage connections, and usage totals remain shared.

Links

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

MIT licensed.