π The fast, Pythonic way to build MCP servers and clients.
---
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),
],
)
```