examples/tasks/README.md
A runnable client/server pair for SEP-2663 background tasks. The server exposes
one task=True tool that reports progress as it works; the client drives it
three ways — transparently, through an explicit handle, and several at once in
parallel.
This runs on the in-memory backend by default, so there's nothing to install or start beyond the two processes.
In one terminal, start the server:
uv sync # from the fastmcp root, once
python examples/tasks/server.py # listens on http://127.0.0.1:8000/mcp
In another terminal, drive it from the client:
# Transparent — call_tool runs the background task and returns its result
python examples/tasks/client.py --duration 8
# Explicit handle — returns immediately, poll it yourself, then collect
python examples/tasks/client.py handle --duration 6
# Parallel — fire several tasks at once and watch them overlap
python examples/tasks/client.py parallel
python examples/tasks/client.py parallel 8 6 4 2
The parallel run is the one to watch: four tasks of decreasing duration all
start at once and total wall-clock tracks the longest task rather than the
sum, because the worker runs them concurrently.
The server enables tasks with one line:
mcp = FastMCP("Tasks Example")
mcp.add_extension(TasksExtension())
The client opts in by importing fastmcp_tasks (which it does to use
call_tool_task). That single import enables task support for every Client
in the process — without it, a Client never advertises the tasks capability,
so the server would run the calls synchronously.
The default memory:// backend runs the worker in the server process. To run
workers as separate processes, point Docket at Redis and start it first:
cd examples/tasks
docker compose up -d
export FASTMCP_DOCKET_URL=redis://localhost:24242/0 # or: direnv allow
python server.py # in one terminal
python -m fastmcp_tasks.worker_cli worker server.py # extra worker(s) in others
| Backend | Workers |
|---|---|
memory:// | in-process only (default) |
redis://… | distributed across processes |