Formhaus

@formhaus/mcp

[formhaus-dev/formhaus MCP server]

MCP server that lets AI agents check Formhaus form definitions against the real @formhaus/core engine. Runs over stdio. Requires Node 22.12 or later. The checks need no account or key.

validate_definition, fix_definition, simulate_path, translation_template, capabilities and example_definitions run offline. The other tools publish forms, read submissions and manage settings in Formhaus Cloud. If the app has its own backend, keep the data there and don't publish without the user's consent.

Setup

Claude Code plugin, with the Formhaus skills:

claude plugin marketplace add formhaus-dev/formhausclaude plugin install formhaus@formhaus

Inside a Claude Code session, /plugin marketplace add formhaus-dev/formhaus and /plugin install formhaus@formhaus do the same after a confirmation prompt.

Claude Code, server only:

claude mcp add formhaus -- npx -y @formhaus/mcp

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json):

{  "mcpServers": {    "formhaus": {      "command": "npx",      "args": ["-y", "@formhaus/mcp"]    }  }}

Tools

publish_form, list_forms, get_submissions, update_form_settings, get_webhook and reveal_webhook_secret call Formhaus Cloud at https://api.formhaus.dev. All but publish_form need FORMHAUS_API_KEY in the server environment, and publish_form uses it when set. An account key (fh_live_...) reaches every form and all six tools. An agent key (fh_agent_..., returned once by the first keyless publish_form) reaches only the forms it created, and update_form_settings, get_webhook and reveal_webhook_secret need an account key. The server reads FORMHAUS_API_KEY from its own environment, not from the project .env. Add it to the env of the formhaus server in your MCP client config (for example .mcp.json with ${FORMHAUS_API_KEY} and the value in your shell or a gitignored .env your client loads), then restart the server. FORMHAUS_API_BASE overrides the API URL. The server also sends short usage instructions to the client on connect.

simulate_path applies answers as initial values, with group answers as arrays of item objects, then presses the actions in order, or Next until the last step or the first blocking error. errors covers visited steps only. Custom validators, onStepValidate and lifecycle hooks are not run. The capabilities are also available as the formhaus://capabilities resource.

The tool handlers are exported for use without MCP:

import { simulatePathTool, validateDefinitionTool } from '@formhaus/mcp';
const report = await validateDefinitionTool({ definition });const result = await simulatePathTool({ definition, answers: { kind: 'business' } });

See the MCP guide for example output. A remote MCP server for Formhaus Cloud is also available. npx formhaus sets up the server in the coding agents on your machine; see formhaus.

License

MIT