Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

4.4 KB
Raw Blame
---
title: Form Input
sidebarTitle: Form Input
description: Collect structured data from users via Pydantic models
icon: rectangle-list
---

import { VersionBadge } from '/snippets/version-badge.mdx'

<VersionBadge version="3.2.0" />

`FormInput` generates a validated form from a Pydantic model. The user fills it out, and the submission is validated against the model before being returned. Structured elicitation that can't be hallucinated.

<Frame>
  <img src="/apps/images/app-form.png" alt="The FormInput provider shown in Goose, with a bug report form" />
</Frame>

```python
from typing import Literal

from pydantic import BaseModel, Field
from fastmcp import FastMCP
from fastmcp.apps.form import FormInput

class BugReport(BaseModel):
    title: str = Field(description="Brief summary")
    severity: Literal["low", "medium", "high", "critical"]
    description: str = Field(
        description="Detailed description",
        json_schema_extra={"ui": {"type": "textarea"}},
    )

mcp = FastMCP("My Server")
mcp.add_provider(FormInput(model=BugReport))
```

This registers two tools:

| Tool | Visibility | Purpose |
|------|-----------|---------|
| `collect_bugreport` | Model | Opens the form UI |
| `submit_form` | App only | Validates and processes the submission |

The tool name is derived from the model class name, lowercased: `collect_{modelname}`. So `BugReport` becomes `collect_bugreport`, `ShippingAddress` becomes `collect_shippingaddress`. Use `tool_name` to override if needed. The LLM calls it with a prompt explaining what it needs, and the user gets a form with fields matching the model. The LLM can also pass `title` and `submit_text` to override the card heading and button label, and `default`, a partial dict of field values that pre-fills the form for the user to confirm or edit. `default` requires `prefab-ui>=0.19.1` and is ignored on older versions.

## Field mapping

`FormInput` uses Prefab's `Form.from_model()`, which maps Pydantic types to form components:

| Python type | Form component |
|------------|---------------|
| `str` | Text input |
| `int`, `float` | Number input |
| `bool` | Checkbox |
| `datetime.date` | Date picker |
| `Literal[...]` | Select dropdown |
| `SecretStr` | Password input |

Use `Field()` metadata to control labels (`title`), placeholders (`description`), and validation (`min_length`, `max_length`, `ge`, `le`). Use `json_schema_extra={"ui": {"type": "textarea"}}` for multiline text.

## Callback

By default, the validated model is returned as JSON. Provide an `on_submit` callback to process the data server-side:

```python
from pydantic import BaseModel
from fastmcp import FastMCP
from fastmcp.apps.form import FormInput

class BugReport(BaseModel):
    title: str
    description: str

reports: list[BugReport] = []

def save_report(report: BugReport) -> str:
    reports.append(report)
    return f"Bug #{len(reports)} filed: {report.title}"

mcp = FastMCP("My Server")
mcp.add_provider(FormInput(model=BugReport, on_submit=save_report))
```

The callback receives a validated model instance and returns a string that becomes the result of the `submit_form` call.

## Configuration

```python
FormInput(
    model=BugReport,             # Required: the Pydantic model
    name="BugTracker",           # App name (default: model name)
    title="File a Bug",          # Card heading (default: model name)
    tool_name="file_bug",        # Tool name (default: collect_{model})
    submit_text="Submit Report", # Button label (default: "Submit")
    on_submit=save_report,       # Optional callback
    send_message=True,           # Push result as a chat message
)
```

Set `send_message=True` to push the result back into the conversation via `SendMessage`, triggering the LLM's next turn. Without it, the result goes only to the form UI, which shows "Submitted.", and the LLM does not see the submission.

## Multiple forms

Add multiple providers for different models β€” each gets its own tool:

```python
from pydantic import BaseModel
from fastmcp import FastMCP
from fastmcp.apps.form import FormInput

class ShippingAddress(BaseModel):
    street: str
    city: str

class BugReport(BaseModel):
    title: str
    description: str

class ContactInfo(BaseModel):
    name: str
    email: str

mcp = FastMCP(
    "My Server",
    providers=[
        FormInput(model=ShippingAddress),
        FormInput(model=BugReport),
        FormInput(model=ContactInfo),
    ],
)
```