mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-19 12:04:18 +02:00
75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# FastMCP Background Tasks Example
|
|
|
|
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.
|
|
|
|
## Run it
|
|
|
|
In one terminal, start the server:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
## How it works
|
|
|
|
The server enables tasks with one line:
|
|
|
|
```python
|
|
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.
|
|
|
|
## Distributed workers (optional)
|
|
|
|
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:
|
|
|
|
```bash
|
|
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 |
|
|
|
|
## Learn more
|
|
|
|
- [Server background tasks](https://gofastmcp.com/servers/tasks)
|
|
- [Client background tasks](https://gofastmcp.com/clients/tasks)
|
|
- [Docket](https://github.com/chrisguidry/docket)
|