AI
Use HeyForm with AI assistants and coding agents through llms.txt and the MCP server.
Docs for AI agents
Give AI assistants and coding agents up-to-date context about HeyForm with these plain-text files.
/llms.txt: an index of every page with a short description./llms-full.txt: the full documentation in a single file.
MCP server
HeyForm runs a Model Context Protocol server at /mcp on your self-hosted instance. AI agents can use it to manage workspaces, projects, forms, and submissions on your behalf.
The MCP server uses the Streamable HTTP transport and the same account API keys as the REST API.
Create an API key
Follow Create an API key and select only the workspaces and permissions the agent needs. For example, select only *:read scopes for an agent that answers questions about your submissions.
Connect your agent
Replace https://forms.example.com with your HeyForm URL and ak-heyform-... with your API key.
Claude Code
Cursor
Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in your project.
VS Code
Add the server to .vscode/mcp.json. VS Code prompts for the key once and stores it securely.
Codex
Add the server to ~/.codex/config.toml, then set the HEYFORM_API_KEY environment variable to your key.
Other clients that support Streamable HTTP and custom headers can connect with the same URL and Authorization header.
Tools
Each tool requires the same scope as its REST API endpoint. If the key lacks a scope or cannot access a workspace or project, the tool returns an error with the HTTP status, for example 403.
| Tool | Scope | Description |
|---|---|---|
get_current_user | None | Get the user who owns the API key. |
get_user | users:read | Get a user who shares a workspace with you. |
list_workspaces | workspaces:read | List workspaces the key can access. |
get_workspace | workspaces:read | Get a workspace. |
rename_workspace | workspaces:write | Rename a workspace. |
list_projects | projects:read | List projects in a workspace. |
create_project | projects:write | Create a project. |
rename_project | projects:write | Rename a project. |
list_members | members:read | List workspace members. |
invite_members | members:write | Invite people by email. |
remove_member | members:write | Remove a workspace member. |
list_forms | forms:read | List forms in a project. |
get_form | forms:read | Get a form's fields, drafts, logic, theme, and version. |
create_form | forms:write | Create an unpublished form. |
rename_form | forms:write | Rename a form. |
duplicate_form | forms:write | Duplicate a form. |
move_form | forms:write | Move a form to another project in the same workspace. |
update_form_drafts | forms:write | Replace a form's draft fields and logic. |
publish_form | forms:write | Publish a form. |
unpublish_form | forms:write | Stop a form from accepting submissions. |
set_form_availability | forms:write | Open or close a published form. |
update_form_settings | forms:write | Update form settings. |
update_form_theme | forms:write | Update the theme, logo, and favicon. |
update_form_hidden_fields | forms:write | Replace hidden fields. |
update_form_variables | forms:write | Replace variables. |
trash_form | forms:write | Move a form to the trash for 30 days. |
restore_form | forms:write | Restore a form from the trash. |
list_submissions | submissions:read | List a form's submissions. |
get_submission | submissions:read | Get a submission. |
update_submission_category | submissions:write | Move a submission to inbox, starred, archive, or spam. |
update_submission_answer | submissions:write | Edit one answer in a submission. |
To edit a form, the agent reads it with get_form, then passes the form's version to update_form_drafts or publish_form. A stale version returns 409, so the agent can read the form again and retry.
Example prompts
- "Create a customer feedback form in my Marketing project with name, email, and a 1–5 rating, then publish it."
- "Summarize this week's submissions to the Event Registration form."
- "Move every spam-looking submission in the Contact form to spam."