Drive your app with AI agents (MCP)
New in 0.3.0.
Pass mcp_server=True and your Fast Dash app serves a web UI and a
Model Context Protocol (MCP) server, so any
MCP-capable agent — Claude Code, Cursor, Cline, … — can inspect and drive it.
The same type hints that build the UI describe what an agent sees via the
describe_app tool: every input (id, type, default,
allowed options, current value) and every output the app produces.
The MCP server is built on Dash's native MCP support
(Dash ≥ 4.3, installed automatically) and is mounted on the same port as the
web app, at /mcp.
from fast_dash import fastdash
import plotly.graph_objects as go
@fastdash(mcp_server=True) # web UI AND MCP on :8080/mcp
def plot_bars(n: int = 6, color: str = "#1c7ed6") -> go.Figure:
"""Plot a bar chart with n bars in the chosen color."""
bars = go.Figure(go.Bar(y=list(range(1, n + 1)), marker_color=color))
return bars
Connect an agent
The endpoint is http://localhost:8080/mcp, served over MCP's streamable HTTP
transport. Each client names its config key differently:
Claude Code: run claude mcp add --transport http my-app http://localhost:8080/mcp,
or add it to the project's .mcp.json:
{"mcpServers": {"my-app": {"type": "http", "url": "http://localhost:8080/mcp"}}}
Cursor: in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{"mcpServers": {"my-app": {"url": "http://localhost:8080/mcp"}}}
VS Code: in .vscode/mcp.json:
{"servers": {"my-app": {"type": "http", "url": "http://localhost:8080/mcp"}}}
Checking that MCP is up
A plain GET /mcp answers with MCP's event stream (text/event-stream,
body : mcp stream open) when the MCP server is mounted, and with the
app's web page when it isn't. That makes a one-line readiness check for a
container health check or CI:
curl -fsS http://127.0.0.1:8080/mcp | grep -q "mcp stream open" && echo "MCP is up"
Check /mcp itself: other paths under it, such as /mcp/health, return
the web page even when MCP is running.
To check what an agent will actually see, run fastdash doctor --mcp
against the running app. It connects as a real MCP client (it needs
pip install mcp), initializes, lists the tools and resources, and reads
describe_app:
$ fastdash doctor --mcp http://127.0.0.1:8080/mcp
Connecting to http://127.0.0.1:8080/mcp (streamable HTTP) ...
initialize OK protocol 2025-11-25, server Plotly Dash 4.5.0
list_tools OK get_dash_component, set_input, set_inputs, invoke, ...
list_resources OK dash://layout, dash://components
describe_app OK Plot Bars: 2 inputs (n:integer, color:string), 1 output (output_bars:Graph)
MCP surface healthy.
It exits with status 1 and names the likely cause when a step fails, for
example when /mcp serves the web page because the app wasn't built with
mcp_server=True. Add --json for the full report, contract included.
A good contract doesn't prove the app runs. Add --invoke to also run it
once through the invoke tool, with its current values, the way an agent
would. The check then fails if the callback raises or the app can't run
from those values:
$ fastdash doctor --mcp http://127.0.0.1:8080/mcp --invoke
...
invoke OK ran in 576.2 ms: output_bars={"data": [{"marker": {"color": "#1c7e...
MCP surface healthy.
--invoke runs your real callback, side effects and cost included, so it
is off by default. An input with no default needs a value:
--invoke-input n=7, repeatable. The value is read as JSON when it parses
and as text otherwise. A failed run names the cause, for example
Problem: invoke ran and the callback failed: RuntimeError: database
unavailable.
What the agent gets
| Surface | Provided by | Use |
|---|---|---|
describe_app() |
Fast Dash | Start here. The full contract + current state: each input's id, type, default, options and current value, and each output the app produces |
set_input(component_id, value) |
Fast Dash | Set one input |
set_inputs(inputs) |
Fast Dash | Set several inputs at once (inputs is a {id: value} dict) |
invoke(inputs=None) |
Fast Dash | Run the callback (optionally setting inputs first), in one call |
set_form(specs) |
Fast Dash | Generate a form at runtime (DynamicDash only) |
get_invocation(index) |
Fast Dash | Fetch a past run's full kwargs + result |
list_component_types() |
Fast Dash | List the legal component types for set_form |
dash://layout, dash://components, get_dash_component |
Dash (native) | Read the static component tree (ids + Dash widget types) |
component_id is the parameter name itself (e.g. "n", "color").
Outputs come back as data: text whole, a table's first 100 rows, a Plotly
figure's data and layout. An image output (a PIL image, a matplotlib
figure or a data:image/... string) can't be read as JSON, so invoke and
get_invocation also return it as an MCP image content block: a PNG that a
vision-capable agent sees just as the user does. Its JSON entry keeps the
shape ({"type": "Image", "size": [...], "image": "attached as an image content
block"}), and the image block follows a text block naming the output id.
describe_app reports the shape only.
Discover the contract
Call describe_app() to learn the exact input ids, their Python types,
defaults, allowed options and current values, plus what a run produces — and
use that to build a valid invoke call:
{
"title": "Plot Bars",
"doc": "Plot a bar chart with n bars in the chosen color.",
"inputs": [
{"id": "n", "tag": "NumberInput", "type": "integer", "default": 6, "options": null, "current_value": 6, "secret": false, "required": false},
{"id": "color", "tag": "ColorInput", "type": "string", "default": "#1c7ed6", "options": null, "current_value": "#1c7ed6", "secret": false, "required": false}
],
"outputs": [
{"id": "output_bars", "tag": "Graph", "type": "object", "label": "BARS"}
]
}
required: true marks a parameter with no default: invoke refuses to run
without it and names what's missing. An output's id comes from the variable
the function returns (return bars gives output_bars); a function that
returns an expression gets output_output_1, output_output_2, and so on. tag is the widget the hint became — a str input can be a single-line
TextInput, a multi-line TextArea or a ColorInput, and they are not
interchangeable. Every input tag is a type set_form accepts, so an agent can
rebuild the widget it found. outputs lets an
agent see what a run returns without having to run it.
The contract is enforced
Whatever describe_app() advertises is what set_input / set_inputs /
invoke accept — an agent cannot set a value the UI itself could never produce.
A value outside a dropdown's options, outside a Slider's min/max, or of the
wrong type (a string for a number, a string for a switch) is rejected with an
error naming the constraint. An upload takes what the browser sends, a
data:<mime>;base64,... URI, and an UploadImage only one that decodes to an
image. invoke is atomic: one bad value rejects the
whole call without mutating anything. The same holds for a form an agent builds
at runtime with set_form — the specs it declared become the contract it is
then held to.
Secrets
A PasswordInput's value is never reported back over MCP: the contract
marks it "secret": true and masks it everywhere (describe_app, the
set_input echo, get_invocation). An agent can fill the field; it cannot
read it. A PasswordInput default (say, a key pre-filled from config)
never leaves the server either: the served page and Dash's native
dash://layout / get_dash_component carry only ********, and the real
value is swapped back in when the callback runs.
Note
The drive tools' (invoke / set_inputs / set_input) raw MCP input
schemas are generic objects — the per-parameter contract lives in
describe_app(), not in those tool schemas. The native dash://components
resource lists ids and Dash widget types only, and get_dash_component
reflects the browser, so for a headless agent neither shows values an
agent set via set_input/set_inputs — use describe_app() for current
values.
Drive it from the agent
# From the agent's side — set inputs and run in a single round-trip:
invoke(inputs={"n": 12, "color": "#2f9e44"})
Agent mutations are reflected in the live browser within ~500 ms (no reload), so a human watching the page sees what the agent does.
Drive it from Python
fast_dash.connect() drives a running app from a script, a notebook or another
service. Its methods are the app's tools, it blocks until each answers, and it
returns the tool's JSON as a dict. It needs no asyncio and no extra package.
Start the app above, then run:
from fast_dash import connect
with connect("http://127.0.0.1:8080/mcp") as app:
print([i["id"] for i in app.describe_app()["inputs"]]) # ['n', 'color']
run = app.invoke(inputs={"n": 12, "color": "#2f9e44"})
print(run["ok"], run["history_index"]) # True 0
past = app.get_invocation(index=run["history_index"])
print(past["kwargs_summary"]) # {'n': 12, 'color': '#2f9e44'}
Every tool takes keyword arguments named as in the table above:
set_input(component_id, value), set_inputs(inputs), invoke(inputs),
set_form(specs) and get_invocation(index). describe_app and
list_component_types take none. Arguments also go by position
(app.set_input("n", 3)), app.tools lists the tool names, and an image
output's PNG bytes are in the result's .images.
A bad call raises fast_dash.mcp.MCPError with the reason: the server can't be
reached, nothing is mounted at that path, or a tool failed. A rejected input is
not an error; it comes back as {"ok": False, "errors": {...}}, as it does for
an agent. A root URL gets /mcp added. headers={...} goes with every request,
for example an Authorization header for a proxy in front of the app, and
timeout= (default 30 seconds) caps each call.
For async code, or to see the raw protocol, use the official
mcp client SDK (pip install mcp) and its
streamable-HTTP client against the same URL.
Test it without a server
app.mcp_test_client() calls the same tools in-process and synchronously: no
server, port, asyncio or mcp package. Each call is a JSON-RPC request to the
app's real /mcp route, so a test sees exactly what an agent sees, validation
errors included. Each tool is a method, and it returns the tool's JSON as a dict:
from fast_dash import FastDash
def plot_bars(n: int = 5, color: str = "#1c7ed6") -> int:
return n
def test_agent_contract():
client = FastDash(callback_fn=plot_bars, mcp_server=True).mcp_test_client()
assert [i["id"] for i in client.describe_app()["inputs"]] == ["n", "color"]
assert list(client.invoke(inputs={"n": 12})["outputs"].values()) == [12]
bad = client.invoke(inputs={"n": "twelve"})
assert bad["ok"] is False and "n" in bad["errors"]
Arguments go by name or by position (client.set_input("n", 3)). An image
output's PNG bytes are in the result's .images, and client.tools lists the
tool names. The client works with both the Flask and FastAPI backends. The app
needs mcp_server=True, and the one-MCP-app-per-process rule still applies.
It has the same methods as connect(), so a script written against one runs
against the other.
Agent-generated UIs with DynamicDash
DynamicDash is a Fast Dash app whose input form is generated at runtime —
either by a parent control or by an agent calling the set_form tool. The form
materializes in the browser within ~500 ms of the call.
from fast_dash import DynamicDash, Graph, Markdown
def score(**candidate_scores):
"""Render a radar chart of whatever numeric fields were sent."""
...
app = DynamicDash(
callback_fn=score,
placeholder="Ask the agent to call set_form() to build the form.",
output_components=[Graph, Markdown],
mcp_server=True,
)
app.run(port=8052) # MCP is served at :8052/mcp
The agent then calls, for example:
set_form(specs=[
{"name": "communication", "type": "Slider", "props": {"min": 0, "max": 10}},
{"name": "technical", "type": "Slider", "props": {"min": 0, "max": 10}},
])
After set_form, describe_app() reflects the materialized form — each field's
id, type, default, options, and props (e.g. a slider's min/max) plus
its current value — so a reconnecting (or second) agent can discover and drive the
form without remembering the spec it sent. From there, set_inputs(...) + invoke()
run it, validated against the very specs the form was built from: a value outside
that slider's 0..10 is rejected exactly as it would be on a static app.
Real-time push (opt-in)
On the default Flask backend, agent mutations reach the browser via a ~500 ms
polling drain. Install the fastapi extra and pass backend="fastapi" to run
on Dash's ASGI backend, where updates stream over a WebSocket with set_props
(sub-100 ms, no polling):
$ pip install 'fast-dash[fastapi]'
@fastdash(mcp_server=True, backend="fastapi") # real-time WebSocket push
def plot_bars(n: int = 6) -> go.Figure:
...
The same ASGI backend also powers native-WebSocket streaming for
stream=True apps (no flask-socketio); on the default Flask backend,
stream=True continues to use flask-socketio unchanged.
Security & limitations
Warning
The MCP route shares the web app's host/port and has no authentication —
anyone who can reach it can drive your callback. Keep it bound to
127.0.0.1 (the default) during development, and put it behind your own
auth before exposing it. Serving on a non-loopback host (e.g.
run_kwargs={"host": "0.0.0.0"}) with mcp_server=True raises a warning.
- One MCP-enabled app per process (Dash's tool registry is process-global).
- Multi-function and steps modes skip the MCP surface.
- Chat append on the native-WebSocket streaming path is not yet ported (it replaces rather than appends).