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.

Warning

An agent can do anything its API key allows. Store the key as a secret, and delete it in Account Settings → API Keys to revoke the agent's access immediately.

Connect your agent

Replace https://forms.example.com with your HeyForm URL and ak-heyform-... with your API key.

Claude Code

claude mcp add --transport http heyform https://forms.example.com/mcp \
  --header "Authorization: Bearer ak-heyform-..."

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in your project.

{
  "mcpServers": {
    "heyform": {
      "url": "https://forms.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ak-heyform-..."
      }
    }
  }
}

VS Code

Add the server to .vscode/mcp.json. VS Code prompts for the key once and stores it securely.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "heyform-api-key",
      "description": "HeyForm API key",
      "password": true
    }
  ],
  "servers": {
    "heyform": {
      "type": "http",
      "url": "https://forms.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:heyform-api-key}"
      }
    }
  }
}

Codex

Add the server to ~/.codex/config.toml, then set the HEYFORM_API_KEY environment variable to your key.

[mcp_servers.heyform]
url = "https://forms.example.com/mcp"
bearer_token_env_var = "HEYFORM_API_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.

ToolScopeDescription
get_current_userNoneGet the user who owns the API key.
get_userusers:readGet a user who shares a workspace with you.
list_workspacesworkspaces:readList workspaces the key can access.
get_workspaceworkspaces:readGet a workspace.
rename_workspaceworkspaces:writeRename a workspace.
list_projectsprojects:readList projects in a workspace.
create_projectprojects:writeCreate a project.
rename_projectprojects:writeRename a project.
list_membersmembers:readList workspace members.
invite_membersmembers:writeInvite people by email.
remove_membermembers:writeRemove a workspace member.
list_formsforms:readList forms in a project.
get_formforms:readGet a form's fields, drafts, logic, theme, and version.
create_formforms:writeCreate an unpublished form.
rename_formforms:writeRename a form.
duplicate_formforms:writeDuplicate a form.
move_formforms:writeMove a form to another project in the same workspace.
update_form_draftsforms:writeReplace a form's draft fields and logic.
publish_formforms:writePublish a form.
unpublish_formforms:writeStop a form from accepting submissions.
set_form_availabilityforms:writeOpen or close a published form.
update_form_settingsforms:writeUpdate form settings.
update_form_themeforms:writeUpdate the theme, logo, and favicon.
update_form_hidden_fieldsforms:writeReplace hidden fields.
update_form_variablesforms:writeReplace variables.
trash_formforms:writeMove a form to the trash for 30 days.
restore_formforms:writeRestore a form from the trash.
list_submissionssubmissions:readList a form's submissions.
get_submissionsubmissions:readGet a submission.
update_submission_categorysubmissions:writeMove a submission to inbox, starred, archive, or spam.
update_submission_answersubmissions:writeEdit 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."