Skip to content

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).