MCP Server

The AgentForms MCP server lets AI assistants (Claude Desktop, Cursor, etc.) create forms and collect human input using the Model Context Protocol.

Installation

bash

pip install agentforms-mcp

Note: Not yet on PyPI. Install from source: pip install -e packages/mcp-server

Requirements: Python 3.12+, mcp[cli] >= 1.0.

Environment Variables

Variable	Default	Description
`AGENTFORMS_API_KEY`	—	Your AgentForms API key (required)
`AGENTFORMS_BASE_URL`	`http://localhost:8000`	AgentForms server URL

Claude Desktop Configuration

Add this to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

JSON

{
  "mcpServers": {
    "agentforms": {
      "command": "uv",
      "args": ["run", "python", "-m", "agentforms_mcp"],
      "env": {
        "AGENTFORMS_API_KEY": "af_live_your_key_here",
        "AGENTFORMS_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Cursor Configuration

Add this to your Cursor MCP settings (.cursor/mcp.json in your project root):

JSON

{
  "mcpServers": {
    "agentforms": {
      "command": "uv",
      "args": ["run", "python", "-m", "agentforms_mcp"],
      "env": {
        "AGENTFORMS_API_KEY": "af_live_your_key_here",
        "AGENTFORMS_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Available Tools

The MCP server exposes 5 tools that AI assistants can call:

create_form

Create a new form to collect structured input from a human. Returns the form URL that can be shared with the recipient.

Parameters

Name	Type	Required	Description
`title`	str	Yes	Form title
`fields`	list[dict]	Yes	Array of field objects
`callback_url`	str	No	Webhook URL
`expires_in`	str	No	Expiry duration (default: `"48h"`)

Returns

Full Form object as a dict: id, url, title, status, fields_count, expires_at, created_at.

get_form_status

Check if a form has been completed, is still pending, or has expired.

Parameters

Name	Type	Required	Description
`form_id`	str	Yes	The form's ULID

Returns

JSON

{"id": "01JN...", "status": "active", "title": "...", "url": "..."}

get_form_response

Get the structured response data from a completed form.

Parameters

Name	Type	Required	Description
`form_id`	str	Yes	The form's ULID

Returns

The full Response object if a response exists. If no response yet:

JSON

{"status": "no_response", "message": "No responses yet"}

cancel_form

Cancel a pending form so it can no longer be submitted.

Parameters

Name	Type	Required	Description
`form_id`	str	Yes	The form's ULID

Returns

JSON

{"id": "01JN...", "status": "cancelled"}

list_forms

List forms with optional status filter.

Parameters

Name	Type	Required	Default	Description
`status`	str	No	—	Filter: `active`, `completed`, `cancelled`, `expired`
`limit`	int	No	20	Max results

Returns

JSON

{"forms": [{"id": "...", "title": "...", "status": "...", ...}]}

Usage Example

Once configured, you can ask your AI assistant to create forms naturally:

Prompt

"Create a form to collect feedback on the new feature.
Ask for their name, a rating from 1-5, and any comments.
Set it to expire in 24 hours."

The assistant will call the create_form tool and return the form URL. Later, you can ask:

Prompt

"Has anyone filled out the feedback form yet?"

The assistant will call get_form_status and get_form_response to check.