Dishka FastMCP

https://github.com/bagowix/dishka-fastmcp
Admin
Dishka IoC container integration for FastMCP: scopes, finalization and providers for MCP tools,...
Tokens:47,346
Snippets:362
Trust Score:7.5
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Install dishka-fastmcp and import dishka_fastmcp; it is a different package from fastmcp-dishka (import fastmcp_dishka).
- Put @inject below @mcp.tool, @mcp.resource or @mcp.prompt, so FromDishka parameters stay out of the tool schema; the other order raises DishkaFastMCPError at import.
- Async handlers need make_async_container; sync handlers need make_container. One server's injected handlers share one kind.
- Pass dishka_lifespan(container) to FastMCP(lifespan=...) and call setup_dishka(container, mcp) once per server that owns a container.
- When the container is shared with FastAPI or FastStream, list the MCP lifespan first in combine_lifespans or pass finalize_container=False.
- Return completed values from handlers; task=True handlers cannot use FromDishka.
- For REQUEST dependencies outside handlers, add DishkaMiddleware() first and resolve with await get_request_container().get(T).

================
CODE SNIPPETS
================
### Install dishka-fastmcp with poetry

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/getting-started.md

Install the package using poetry. Requires Python 3.11+, Dishka 1.10.1+, FastMCP 4.0.0 through latest 4.x, and MCP SDK 2.x.

```bash
poetry add dishka-fastmcp
```

--------------------------------

### Clone and set up development environment with uv

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/CONTRIBUTING.md

Clones the repository and installs dependencies using uv. Run `uv run prek install` once to install git hooks.

```bash
git clone https://github.com/bagowix/dishka-fastmcp
cd dishka-fastmcp
uv sync            # creates the venv and installs dev dependencies
uv run prek install  # one-time: installs the git hooks
```

--------------------------------

### Basic wiring of Dishka with FastMCP

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/setup-dishka.md

Demonstrates the standard setup using dishka_lifespan and setup_dishka to inject dependencies into FastMCP tools.

```python
from dishka import Provider, Scope, make_async_container, provide
from fastmcp import FastMCP

from dishka_fastmcp import FromDishka, dishka_lifespan, inject, setup_dishka


class Repo:
    def get(self, user_id: int) -> str:
        return f'user:{user_id}'


class AppProvider(Provider):
    repo = provide(Repo, scope=Scope.REQUEST)


container = make_async_container(AppProvider())
mcp = FastMCP('app', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def get_user(user_id: int, repo: FromDishka[Repo]) -> str:
    return repo.get(user_id)
```

--------------------------------

### Install dishka-fastmcp with pip

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/getting-started.md

Install the package using pip. Requires Python 3.11+, Dishka 1.10.1+, FastMCP 4.0.0 through latest 4.x, and MCP SDK 2.x.

```bash
pip install dishka-fastmcp
```

--------------------------------

### Development Commands

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/AGENTS.md

Commands for setting up the environment, running tests, linting, type checking, and auditing workflows. Run `uv sync` to create the venv and install dev dependencies, then use the other commands for verification.

```bash
uv sync                       # create venv, install dev deps
uv run pytest --cov           # tests + coverage (100%)
uv run ruff format --check && uv run ruff check
uv run mypy && uv run pyright
uv run zizmor .github/        # workflow audit (offline without GH_TOKEN)
uv run prek install           # one-time: git hooks
uv run prek run --all-files   # every hook, incl. pymarkdown (not run in CI)
```

--------------------------------

### setup_dishka signature

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/reference.md

Associates a root container with the FastMCP application. Call it once before the server starts. Routers mounted into the application get the container through dishka_lifespan.

```python
setup_dishka(container: AsyncContainer | Container, app: FastMCP) -> None
```

--------------------------------

### Opening a REQUEST scope with DishkaMiddleware

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-middleware.md

This example demonstrates setting up a FastMCP server with DishkaMiddleware and using get_request_container within a provider to resolve request-scoped dependencies.

```python
from collections.abc import Sequence

from dishka import AsyncContainer, Provider, Scope, make_async_container, provide
from fastmcp import FastMCP
from fastmcp.server.providers import Provider
from fastmcp.tools import Tool

from dishka_fastmcp import (
    DishkaFastMCPError,
    DishkaMiddleware,
    dishka_lifespan,
    get_request_container,
    setup_dishka,
)


class FeatureFlags:
    def __init__(self) -> None:
        self._enabled = {'user:get': True}

    def enabled(self, name: str) -> bool:
        return self._enabled.get(name, False)


class FeatureFlagsProvider(Provider):
    flags = provide(FeatureFlags, scope=Scope.REQUEST)


class FeatureTools(Provider):
    async def _list_tools(self) -> Sequence[Tool]:
        try:
            container = get_request_container()
        except DishkaFastMCPError:
            return []  # FastMCP also lists components outside any request
        flags = await container.get(FeatureFlags)
        return [tool for tool in ALL_TOOLS if flags.enabled(tool.name)]


container = make_async_container(FeatureFlagsProvider())
mcp = FastMCP(
    'app',
    lifespan=dishka_lifespan(container),
    middleware=[DishkaMiddleware()],
)
setup_dishka(container, mcp)
mcp.add_provider(FeatureTools())
```

--------------------------------

### Injecting request context into a tool

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/fastmcp-provider.md

Example showing how to inject the FastMCP Context directly into a tool using FastMCPProvider and FromDishka.

```APIDOC
## Injecting request context into a tool

### Description
Demonstrates how to use FastMCPProvider to inject the current FastMCP Context into a tool handler.

### Code Example
```python
from dishka import make_async_container
from fastmcp import Context, FastMCP

from dishka_fastmcp import (
    FastMCPProvider,
    FromDishka,
    dishka_lifespan,
    inject,
    setup_dishka,
)

container = make_async_container(FastMCPProvider())
mcp = FastMCP('app', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def request_id(ctx: FromDishka[Context]) -> str:
    return ctx.request_id
```
```

--------------------------------

### Use @inject with resources and prompts

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/getting-started.md

The same decorator works for every supported FastMCP component. Place `@inject` below `@mcp.resource` or `@mcp.prompt`.

```python
@mcp.resource('users://{user_id}')
@inject
async def user(user_id: str, repo: FromDishka[UserRepo]) -> dict:
    return await repo.get(user_id)


@mcp.prompt
@inject
async def summarize(text: str, service: FromDishka[Summarizer]) -> str:
    return await service.run(text)
```

--------------------------------

### __version__

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/reference.md

The installed package version, as a string.

```APIDOC
## __version__

### Description
The installed package version, as a string.
```

--------------------------------

### setup_dishka(container, app)

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/setup-dishka.md

Associates a root dishka container with a FastMCP application. Call once before the server starts. The container is stored on the app object and shared with mounted servers.

```APIDOC
## setup_dishka(container, app)

### Description
Associates a root dishka container with a FastMCP application. Call once before the server starts. The container is stored on the app object and shared with mounted servers.

### Signature
```python
def setup_dishka(container: AsyncContainer | Container, app: FastMCP) -> None:
```

### Parameters
- **container** (AsyncContainer | Container) - Required - The root dishka container. Both async and sync containers are accepted.
- **app** (FastMCP) - Required - The FastMCP application to associate the container with.

### Return Type
None

### Behavior
- Thin wrapper over register_container; stores the container as an attribute on the app object.
- Call once before the server starts. Calling twice with the same container is idempotent; calling with a different container raises DishkaFastMCPError.
- Does not close the container on shutdown; use dishka_lifespan for that.
- Mounted servers resolve dependencies from the container during MCP requests.
- Direct server.call_tool() calls work off the registered attribute; mounted routers are reached through actual MCP requests.
- get_registered_container(app) returns the registered container; unregister_container(app) drops it.
```

--------------------------------

### setup_dishka(container, app)

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/reference.md

Associates a root container with a FastMCP application. Call it once before the server starts.

```APIDOC
## setup_dishka(container, app)

### Description
Associates a root container with the FastMCP application. Call it once before the server starts.

### Signature
```python
setup_dishka(container: AsyncContainer | Container, app: FastMCP) -> None
```

### Parameters
- **container** (AsyncContainer | Container) - Required - The root container to associate with the application.
- **app** (FastMCP) - Required - The FastMCP application instance.

### Usage
Call this function once before the server starts. Routers mounted into the application get the container through `dishka_lifespan`.
```

--------------------------------

### Handling DishkaFastMCPError during setup

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/setup-dishka.md

Illustrates how the library raises a DishkaFastMCPError if an attempt is made to register a different container to an already configured FastMCP application.

```python
from dishka import make_async_container
from dishka_fastmcp import DishkaFastMCPError, setup_dishka

container = make_async_container(AppProvider())
other = make_async_container(AppProvider())
mcp = FastMCP('app')

setup_dishka(container, mcp)
try:
    setup_dishka(other, mcp)  # a different container for the same app
except DishkaFastMCPError as exc:
    print(exc)  # "A different dishka container is already registered for this FastMCP application."
finally:
    # the application owns its container: close both when done
    await container.close()
    await other.close()
```

--------------------------------

### Configure FastMCP server with Dishka container

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/getting-started.md

Create the container before the FastMCP server so the lifespan can close it on shutdown. Use `@inject` below `@mcp.tool`; placing it above fails at import.

```python
from dishka import Provider, Scope, make_async_container, provide
from fastmcp import FastMCP

from dishka_fastmcp import FromDishka, dishka_lifespan, inject, setup_dishka


class Catalog:
    _prices: dict[str, int] = {'book': 12, 'pen': 2}

    def price(self, item: str) -> int:
        return self._prices.get(item, 0)


class AppProvider(Provider):
    catalog = provide(Catalog, scope=Scope.REQUEST)


container = make_async_container(AppProvider())
mcp = FastMCP('example', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def get_price(item: str, catalog: FromDishka[Catalog]) -> int:
    return catalog.price(item)
```

--------------------------------

### Install dishka-fastmcp with uv

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/index.md

Install the dishka-fastmcp package using uv.

```bash
uv add dishka-fastmcp
```

--------------------------------

### Install dishka-fastmcp with uv or pip

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/README.md

Install the package using uv or pip. Requires Python 3.11+, dishka>=1.10.1, fastmcp>=4.0.0,<5, and mcp>=2.0.0,<3. Servers on FastMCP 3.x should use dishka-fastmcp 2.0.x.

```bash
uv add dishka-fastmcp        # or: pip install dishka-fastmcp
```

--------------------------------

### Consuming context inside a provider

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/fastmcp-provider.md

Example showing how to consume the FastMCP Context inside a custom dishka provider, decoupled from the handler.

```APIDOC
## Consuming context inside a provider

### Description
Demonstrates how to use the FastMCP Context within a custom dishka provider to provide derived values.

### Code Example
```python
from dishka import Provider, Scope, provide
from fastmcp import Context


class RequestProvider(Provider):
    @provide(scope=Scope.REQUEST)
    def request_id(self, context: Context) -> str:
        return context.request_id
```
```

--------------------------------

### Catching DishkaFastMCPError

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/errors.md

Example of how to catch the DishkaFastMCPError exception when retrieving a request container.

```python
from dishka_fastmcp import DishkaFastMCPError

try:
    container = get_request_container()
except DishkaFastMCPError as exc:
    logging.warning('no dishka request scope: %s', exc)
```

--------------------------------

### Mount a router server with shared container using dishka_lifespan and setup_dishka

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/lifecycle.md

Build a server from routers and give it one container. Pass `dishka_lifespan(container)` to the server's lifespan and call `setup_dishka(container, server)` so routers mounted at any depth use that container. Mounted routers can be added later and support `namespace` or `tool_names`. The example mounts a `users` server with a tool that injects `UserRepository` via `FromDishka`.

```python
container = make_async_container(AppProvider())
server = FastMCP('app', lifespan=dishka_lifespan(container))
setup_dishka(container, server)

users = FastMCP('users')


@users.tool
@inject
async def get_user(user_id: int, repo: FromDishka[UserRepository]) -> User:
    return await repo.get(user_id)


server.mount(users, namespace='users')
```

--------------------------------

### Run a single test

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/CONTRIBUTING.md

Runs a specific test by its full path. Example targets `test_async_tool_injects_and_hides_deps_from_schema` in `tests/test_tools.py`.

```bash
uv run pytest tests/test_tools.py::test_async_tool_injects_and_hides_deps_from_schema
```

--------------------------------

### Add Agent Skill with npx

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/README.md

Install the Agent Skill for coding agents (Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI) that walks through adding dishka-fastmcp to a FastMCP server.

```bash
npx skills add bagowix/dishka-fastmcp
```

--------------------------------

### Sync handlers with sync Dishka container

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/getting-started.md

Use a sync Dishka container for regular sync handlers. FastMCP runs them in a worker thread, and dishka-fastmcp keeps dependency creation, usage, and cleanup in that thread.

```python
from dishka import make_container

container = make_container(AppProvider())
mcp = FastMCP('sync', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
def get_price_sync(item: str, catalog: FromDishka[Catalog]) -> int:
    return catalog.price(item)
```

--------------------------------

### Handling missing request scope

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-middleware.md

Example of handling the DishkaFastMCPError when code might execute outside of an MCP request context.

```python
from dishka_fastmcp import DishkaFastMCPError, get_request_container

try:
    container = get_request_container()
except DishkaFastMCPError:
    # outside an MCP request, without the middleware, in a task worker, or on a
    # mounted server that owns a different container
    ...
else:
    value = await container.get(Service)
```

--------------------------------

### Add Agent Skill with npx

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/index.md

Install the Agent Skill for coding agents to add dishka-fastmcp to a FastMCP server.

```bash
npx skills add bagowix/dishka-fastmcp
```

--------------------------------

### inject usage example

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/reference.md

Resolves FromDishka parameters, removes them from the public signature, and manages one Scope.REQUEST around the handler. Sync and async functions are detected automatically. Under DishkaMiddleware, async handlers share the scope the middleware opened instead.

```python
@inject
async def handler(service: FromDishka[Service]) -> Result: ...
```

--------------------------------

### Wiring a root server with mounted routers

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/setup-dishka.md

Shows how to configure a root FastMCP server with a container and mount additional routers that inherit the DI context.

```python
container = make_async_container(AppProvider())
server = FastMCP('root', lifespan=dishka_lifespan(container))
setup_dishka(container, server)

users = FastMCP('users')


@users.tool
@inject
async def get_user(user_id: int, repo: FromDishka[Repo]) -> str:
    return repo.get(user_id)


server.mount(users, namespace='users')
```

--------------------------------

### setup_dishka(container, app)

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/configuration.md

Sets up dishka integration for a FastMCP app. Takes two positional arguments: the container and the app. No options.

```APIDOC
## setup_dishka(container, app)

### Description
Sets up dishka integration for a FastMCP app. Takes two positional arguments: the container and the app. No options.

### Parameters
- **container** (AsyncContainer | Container) - Required - The dishka container to use.
- **app** (FastMCP) - Required - The FastMCP application instance.
```

--------------------------------

### Basic tool with a REQUEST-scoped dependency

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/inject.md

Demonstrates setting up a Dishka container and using @inject to provide a Catalog dependency to a FastMCP tool.

```python
from dishka import Provider, Scope, make_async_container, provide
from fastmcp import FastMCP

from dishka_fastmcp import FromDishka, dishka_lifespan, inject, setup_dishka


class Catalog:
    _prices: dict[str, int] = {'book': 12, 'pen': 2}

    def price(self, item: str) -> int:
        return self._prices.get(item, 0)


class AppProvider(Provider):
    catalog = provide(Catalog, scope=Scope.REQUEST)


container = make_async_container(AppProvider())
mcp = FastMCP('shop', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def get_price(item: str, catalog: FromDishka[Catalog]) -> int:
    return catalog.price(item)
```

--------------------------------

### DishkaMiddleware()

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/configuration.md

Middleware for FastMCP that provides dishka dependency injection. Constructor takes no arguments; configuration is determined by its position in the middleware list. Requires an AsyncContainer root and raises DishkaFastMCPError per request otherwise.

```APIDOC
## DishkaMiddleware()

### Description
Middleware for FastMCP that provides dishka dependency injection. Constructor takes no arguments; configuration is determined by its position in the middleware list. Requires an AsyncContainer root and raises DishkaFastMCPError per request otherwise.

### Parameters
- **(list position)** (list[Middleware] on FastMCP) - Required - Put DishkaMiddleware first; middleware listed before it runs outside the request scope.

### Notes
Requires an AsyncContainer root; raises DishkaFastMCPError per request otherwise.
```

--------------------------------

### setup_dishka(container, app)

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/llms.txt

Associates a root container with a FastMCP app. This is the entry point for integrating Dishka dependency injection with FastMCP.

```APIDOC
## setup_dishka(container, app)

### Description
Associates a root container with a FastMCP app. This is the entry point for integrating Dishka dependency injection with FastMCP.

### Parameters
- **container** (Container) - Required - The root Dishka container to associate with the app.
- **app** (FastMCP) - Required - The FastMCP application instance.

### Usage
```python
setup_dishka(container, app)
```
```

--------------------------------

### Error: Lifespan startup sees a different container

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/errors.md

Raised when entering the lifespan for an app that already has a different container registered, either by setup_dishka or by another dishka_lifespan.

```APIDOC
## Error: Lifespan startup sees a different container

### Message
`dishka_lifespan received a different container than the one already registered for this FastMCP application.`

### Location
`dishka_fastmcp/lifespan.py`, inside the `dishka` generator (line 55), before `register_container`.

### Triggered by
- Entering the returned lifespan for an app that already has a *different* container registered, by `setup_dishka` or by another `dishka_lifespan`.
- Registering the *same* container is allowed and proceeds.

### Behavior
Surfaces when the server starts (entering the lifespan context).
```

--------------------------------

### Wire FastMCP server with dishka container and inject handler

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/skills/dishka-fastmcp/SKILL.md

Sets up a FastMCP server with a dishka async container, registers the container via setup_dishka, and uses @inject with FromDishka to inject a REQUEST-scoped Catalog into a tool handler. The client only sees the tool's ordinary parameters (item), not the injected dependency. dishka_lifespan closes the container on shutdown.

```python
from dishka import Provider, Scope, make_async_container, provide
from fastmcp import FastMCP

from dishka_fastmcp import FromDishka, dishka_lifespan, inject, setup_dishka


class AppProvider(Provider):
    catalog = provide(Catalog, scope=Scope.REQUEST)


container = make_async_container(AppProvider())
mcp = FastMCP('shop', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def get_price(item: str, catalog: FromDishka[Catalog]) -> int:
    return catalog.price(item)  # the client sees only `item`
```

--------------------------------

### FastMCPProvider()

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/configuration.md

A dishka provider that supplies FastMCP-related dependencies. Constructor takes no arguments; add an instance as a dishka provider (e.g., make_async_container(AppProvider(), FastMCPProvider())).

```APIDOC
## FastMCPProvider()

### Description
A dishka provider that supplies FastMCP-related dependencies. Constructor takes no arguments; add an instance as a dishka provider (e.g., make_async_container(AppProvider(), FastMCPProvider())).

### Parameters
None.
```

--------------------------------

### Expose FastMCP context with FastMCPProvider

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/context.md

Sets up a Dishka container with FastMCPProvider and injects the FastMCP Context into a tool handler using FromDishka and inject. The container is passed to dishka_lifespan and setup_dishka wires it to the FastMCP server.

```python
from dishka import make_async_container
from fastmcp import Context, FastMCP

from dishka_fastmcp import (
    FastMCPProvider,
    FromDishka,
    dishka_lifespan,
    inject,
    setup_dishka,
)

container = make_async_container(FastMCPProvider())
mcp = FastMCP('app', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def request_id(ctx: FromDishka[Context]) -> str:
    return ctx.request_id

```

--------------------------------

### Handle startup conflicts with DishkaFastMCPError

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-lifespan.md

Catch DishkaFastMCPError when attempting to register a different container for an app that already has one registered.

```python
from dishka_fastmcp import DishkaFastMCPError, dishka_lifespan, setup_dishka

setup_dishka(container_a, mcp)
try:
    lifecycle = dishka_lifespan(container_b)  # different container for the same app
    async with lifecycle(mcp):
        ...
except DishkaFastMCPError as exc:
    print(exc)  # "dishka_lifespan received a different container than the one already registered..."
```

--------------------------------

### Combine FastMCP lifespan with FastAPI lifespan using combine_lifespans

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/lifecycle.md

Use when the same container serves a FastAPI application alongside FastMCP. List the FastMCP lifespan first because combine_lifespans exits lifespans in reverse order, ensuring the container closes after the other component shuts down. The FastAPI guide's order (app_lifespan first) would close the container too early.

```python
mcp_app = mcp.http_app(path='/')
app = FastAPI(lifespan=combine_lifespans(mcp_app.lifespan, app_lifespan))
app.mount('/mcp', mcp_app)
```

--------------------------------

### Open request scope for whole MCP request with DishkaMiddleware

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/lifecycle.md

Use DishkaMiddleware to open a single Scope.REQUEST for the entire MCP request, allowing dynamic component providers and middleware to access the request container via get_request_container(). Without the middleware, @inject keeps its per-handler scope. The example shows a FeatureTools provider that returns an empty list when no request container is available (e.g., outside a request).

```python
from collections.abc import Sequence

from fastmcp.server.providers import Provider as ComponentProvider
from fastmcp.tools import Tool

from dishka_fastmcp import DishkaFastMCPError, DishkaMiddleware, get_request_container


class FeatureTools(ComponentProvider):
    async def _list_tools(self) -> Sequence[Tool]:
        try:
            container = get_request_container()
        except DishkaFastMCPError:
            return []  # FastMCP also lists components outside any request
        flags = await container.get(FeatureFlags)
        return [tool for tool in ALL_TOOLS if flags.enabled(tool.name)]


container = make_async_container(AppProvider(), FastMCPProvider())
mcp = FastMCP(
    'app',
    lifespan=dishka_lifespan(container),
    middleware=[DishkaMiddleware(), AuditMiddleware()],
)
setup_dishka(container, mcp)
mcp.add_provider(FeatureTools())
```

--------------------------------

### DishkaMiddleware

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-middleware.md

Class that opens a REQUEST scope around every MCP request the server handles. It should be placed first in the middleware list. It requires an AsyncContainer as the root container, which can be registered via setup_dishka or provided in the lifespan state.

```APIDOC
## DishkaMiddleware

### Description
Opens a REQUEST scope around every MCP request the server handles. Put it first in FastMCP(middleware=[...]) so that middleware after it sees the scope. List requests, reads and prompt renders get one as well. Async @inject handlers share the scope instead of opening their own, and it is finalized once when the rest of the request is done and before the response goes out. Notifications get no scope.

### Constructor
DishkaMiddleware() - takes no constructor arguments.

### Usage
Instantiate one per server that should open request-wide scopes. The root container must be an AsyncContainer, found as for @inject: registered by setup_dishka on the server, or put into the lifespan state of the server serving the request by dishka_lifespan.

### Notes
- A mounted server's DishkaMiddleware does nothing when its parent already opened a scope.
- A direct server.call_tool() outside an MCP request gets no scope; @inject then opens one per handler.
- The scope's Context and FastMCP describe the request as this middleware sees it.
```

--------------------------------

### Provide context for FastMCP requests

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/container-internals.md

The provide_context function populates the REQUEST scope with FastMCP request objects. It returns a dictionary mapping fastmcp.Context and fastmcp.FastMCP to their respective instances, which is consumed by FastMCPProvider and used in wrap_injection and DishkaMiddleware.

```python
def provide_context(args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[Any, Any]:
    """Populate the REQUEST scope with FastMCP request objects."""
    del args, kwargs
    return {Context: get_context(), FastMCP: get_server()}
```

--------------------------------

### on_request(context, call_next)

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-middleware.md

Middleware method that opens a REQUEST scope for the current MCP request and runs the rest of the request chain inside it.

```APIDOC
## on_request(context, call_next)

### Description
Runs the rest of the request inside one REQUEST scope. This method is called by FastMCP for each incoming request and ensures that all dependencies resolved during the request share a single REQUEST-scoped container.

### Method
async def on_request(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> object

### Parameters
- **context** (MiddlewareContext[Any]) - Required - The FastMCP middleware context of the request.
- **call_next** (CallNext[Any, Any]) - Required - The next middleware/handler in the chain.

### Return Type
object - The result of running the rest of the request.

### Behavior
1. Obtains the current FastMCP request context via `current_request()`.
2. If no MCP request is being served or a request scope is already open, runs `call_next(context)` without opening a scope.
3. Finds the root container via `require_container()`.
4. If the root container is not an `AsyncContainer`, raises `DishkaFastMCPError`.
5. Opens an async REQUEST-scoped container with a task-reentrant lock.
6. Stores the scope on the request, runs `call_next(context)`, and detaches the scope in a finally block.

### Scope Semantics
- Every MCP request gets a scope: tool calls, list requests, resource reads, prompt renders, handshake, and ping. Notifications get no scope.
- Async @inject handlers share the scope; sync handlers keep their own scope in worker threads.
- The scope is locked with a task-reentrant lock, so lookups run one at a time.
- The scope is finalized once before the response goes out; a finalizer that raises fails the request.
- The outermost DishkaMiddleware opens the scope; mounted servers do not open a second one.
- Direct `await server.call_tool(...)` outside an MCP request gets no scope; @inject opens one per handler instead.
```

--------------------------------

### Registering FastMCPProvider in container

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/fastmcp-provider.md

Adding an instance of FastMCPProvider when creating the dishka container.

```python
container = make_async_container(AppProvider(), FastMCPProvider())
```

--------------------------------

### require_container()

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/container-internals.md

Returns the root container for the active FastMCP application, following a specific resolution order.

```APIDOC
## require_container()

### Description
Returns the root container for the active FastMCP application. The resolution order is: 1) background task check, 2) active server check, 3) registered container, 4) serving container, 5) raise missing setup error.

### Method
Function

### Signature
require_container() -> AsyncContainer | Container

### Returns
- **AsyncContainer | Container** - The root container.

### Errors
- Raises an exception when no active application is found or setup is missing.
```

--------------------------------

### Integrate dishka with FastMCP using dishka_fastmcp

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/llms.txt

Shows how to wire a dishka async container into a FastMCP server. The Catalog provider is scoped to REQUEST, and the tool's catalog parameter is injected via FromDishka, so clients only see the item argument in the schema.

```python
from dishka import Provider, Scope, make_async_container, provide
from fastmcp import FastMCP

from dishka_fastmcp import FromDishka, dishka_lifespan, inject, setup_dishka


class Catalog:
    _prices = {'book': 12, 'pen': 2}

    def price(self, item: str) -> int:
        return self._prices.get(item, 0)


class AppProvider(Provider):
    catalog = provide(Catalog, scope=Scope.REQUEST)


container = make_async_container(AppProvider())
mcp = FastMCP('shop', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)


@mcp.tool
@inject
async def get_price(item: str, catalog: FromDishka[Catalog]) -> int:
    return catalog.price(item)  # client sees only `item` in the schema
```

--------------------------------

### Configure basic Dishka lifespan ownership

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-lifespan.md

The server owns the container and closes it on shutdown by passing the container to dishka_lifespan.

```python
from dishka import Provider, Scope, make_async_container, provide
from fastmcp import FastMCP

from dishka_fastmcp import dishka_lifespan, setup_dishka


class AppProvider(Provider):
    @provide(scope=Scope.APP)
    async def resource(self) -> AsyncIterator[str]:
        try:
            yield 'connected'
        finally:
            await self.close()


container = make_async_container(AppProvider())
mcp = FastMCP('app', lifespan=dishka_lifespan(container))
setup_dishka(container, mcp)
```

--------------------------------

### register_container(container: AsyncContainer | Container, app: FastMCP) -> None

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/container-internals.md

Associates a root container with a FastMCP application. Registration is guarded by a module-global lock. Re-registering the same container is a no-op; registering a different container raises DishkaFastMCPError.

```APIDOC
## register_container(container: AsyncContainer | Container, app: FastMCP) -> None

### Description
Associates a root container with a FastMCP application. Registration is guarded by a module-global lock. Re-registering the same container is a no-op; registering a different container raises DishkaFastMCPError.

### Parameters
- **container** (AsyncContainer | Container) - Required - The container to associate with the application.
- **app** (FastMCP) - Required - The FastMCP application to associate the container with.

### Raises
- **DishkaFastMCPError** - If a different container is already registered for the application.
```

--------------------------------

### FastMCPProvider class definition

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/fastmcp-provider.md

The FastMCPProvider class subclasses dishka.Provider and registers two from_context providers at Scope.REQUEST for Context and FastMCP.

```APIDOC
## FastMCPProvider

### Description
Exposes FastMCP request-scoped objects (Context and FastMCP) via from_context.

### Class Definition
```python
class FastMCPProvider(Provider):
    """Exposes FastMCP request-scoped objects via from_context."""

    context = from_context(Context, scope=Scope.REQUEST)
    server = from_context(FastMCP, scope=Scope.REQUEST)
```

### Class Attributes
- **context** (from_context result) - Scope.REQUEST - The current fastmcp.Context (FastMCP operation context: request IDs, progress reporting, resource access).
- **server** (from_context result) - Scope.REQUEST - The current fastmcp.FastMCP server instance.

### Constructor
`FastMCPProvider()` takes no arguments. Add an instance as a provider when building the dishka container.

### Usage Example
```python
container = make_async_container(AppProvider(), FastMCPProvider())
```
```

--------------------------------

### register_container function

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/container-internals.md

Associates a root container with a FastMCP application. Registration is thread-safe; attempting to register a different container for an already-registered application raises a DishkaFastMCPError.

```python
def register_container(container: AsyncContainer | Container, app: FastMCP) -> None:
    """Associate a root container with a FastMCP application."""
    with _register_lock:
        existing = get_registered_container(app)
        if existing is not None and existing is not container:
            raise DishkaFastMCPError(
                'A different dishka container is already registered for this FastMCP application.',
            )
        setattr(app, _ATTR, container)
```

--------------------------------

### Run pre-commit hooks for docs changes

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/CONTRIBUTING.md

Runs all pre-commit hooks, which lint Markdown with pymarkdown. CI does not run these, so run before pushing docs changes.

```bash
uv run prek run --all-files
```

--------------------------------

### Resolve FastMCP Context and FastMCP in dependencies with FastMCPProvider

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/skills/dishka-fastmcp/SKILL.md

Adds FastMCPProvider() to the container so REQUEST-scoped providers can inject the current fastmcp.Context and fastmcp.FastMCP. Context and FastMCP are REQUEST-scoped, so SESSION or APP factories cannot take them; dishka rejects such a graph at container build time.

```python
from typing import NewType

from fastmcp import Context

from dishka_fastmcp import FastMCPProvider

RequestId = NewType('RequestId', str)


class RequestProvider(Provider):
    @provide(scope=Scope.REQUEST)
    def request_id(self, context: Context) -> RequestId:
        return RequestId(context.request_id)


container = make_async_container(AppProvider(), FastMCPProvider(), RequestProvider())
```

--------------------------------

### FastMCPProvider class definition

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/fastmcp-provider.md

The FastMCPProvider class definition from dishka_fastmcp/providers.py, registering Context and FastMCP as request-scoped dependencies.

```python
class FastMCPProvider(Provider):
    """Exposes FastMCP request-scoped objects via ``from_context``."""

    context = from_context(Context, scope=Scope.REQUEST)
    server = from_context(FastMCP, scope=Scope.REQUEST)
```

--------------------------------

### RequestScope

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/container-internals.md

A named tuple representing the REQUEST container opened by DishkaMiddleware and the root container it came from.

```APIDOC
## RequestScope

### Description
A REQUEST container DishkaMiddleware opened, and the root it came from.

### Fields
- **root** (AsyncContainer) - The root container the scope was opened from.
- **container** (AsyncContainer) - The open Scope.REQUEST container.

### Usage
Stored on FastMCP's per-request context object under attribute __dishka_fastmcp_request_scope__.
```

--------------------------------

### Combine Dishka lifespan with context-manager lifespans

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-lifespan.md

Use combine_lifespans to merge lifespans. Note that exit order is reversed, so placing dishka_lifespan last ensures it closes before other resources.

```python
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

from fastmcp import FastMCP
from fastmcp.utilities.lifespan import combine_lifespans

from dishka_fastmcp import dishka_lifespan, setup_dishka


@asynccontextmanager
async def application_lifespan(app: FastMCP) -> AsyncIterator[dict[str, object]]:
    resource = await create_resource()
    try:
        yield {'resource': resource}
    finally:
        await resource.close()


mcp = FastMCP(
    'app',
    lifespan=combine_lifespans(
        application_lifespan,
        dishka_lifespan(container),
    ),
)
setup_dishka(container, mcp)
```

--------------------------------

### FromDishka

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/docs/reference.md

Re-export of Dishka's dependency marker, provided so handlers can import their entire integration surface from one package.

```APIDOC
## FromDishka

### Description
Re-export of Dishka's dependency marker. It is provided here so handlers can import their entire integration surface from one package.
```

--------------------------------

### dishka_lifespan(container, *, finalize_container=True)

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/dishka-lifespan.md

Creates a FastMCP lifespan that registers a dishka container for the server's lifetime, yields lifespan state containing the container, and optionally closes the container on shutdown.

```APIDOC
## dishka_lifespan(container, *, finalize_container=True)

### Description
Creates a FastMCP lifespan that publishes a dishka container for the server's lifetime. On startup, it registers the container for the app and yields lifespan state containing the container. On shutdown, it optionally closes the container and unregisters the registration.

### Signature
```python
def dishka_lifespan(
    container: AsyncContainer | Container,
    *,
    finalize_container: bool = True,
) -> Lifespan:
```

### Parameters
- **container** (AsyncContainer | Container) - Required - The root dishka container to publish for the server's lifetime. Works with both AsyncContainer and sync Container.
- **finalize_container** (bool, keyword-only) - Optional, default True - If True, the lifespan closes the container on shutdown (awaiting container.close() for AsyncContainer, calling container.close() for sync Container), finalizing every Scope.APP provider, and removes the registration. If False, closing is left to the container's owner, and a registration that setup_dishka made before startup survives the shutdown.

### Return Type
Lifespan (FastMCP lifespan; enters with an AsyncGenerator[dict[str, Any], None] yielding a mapping, exits on shutdown).

### Behavior
On startup (__call__ on the returned lifespan):
1. If a container is already registered for the app (by setup_dishka or by another dishka_lifespan) and it is not the same object, raises DishkaFastMCPError ("dishka_lifespan received a different container than the one already registered for this FastMCP application."). If it is the same container, proceeds.
2. Registers the container for the app with register_container(container, app) - the same registration setup_dishka performs.
3. Yields lifespan state {LIFESPAN_STATE_KEY: container}, i.e. {'dishka_fastmcp.container': container} (the constant LIFESPAN_STATE_KEY = 'dishka_fastmcp.container', defined in _container.py line 39). Mounted servers read this state during every MCP request the served server handles, which is how routers without a container of their own resolve dependencies.
4. On shutdown: if finalize_container is True, closes the container (async or sync), then unregisters the app registration. Unregistration happens when finalize_container is True or when no registration existed before startup. With finalize_container=False and a pre-existing setup_dishka registration, the registration survives the shutdown, so direct call_tool() calls keep working between sessions (the lifespan is re-entrant for a same-container lifespan). The unregister runs in a nested finally even when container closing raises, so the registration is always dropped when the lifespan owned the close.

### Composition
The result is a FastMCP Lifespan, so it composes with other @lifespan functions through | (left side enters first and exits last), and with lifespans that yield a mapping or None through fastmcp.utilities.lifespan.combine_lifespans (lifespans enter in argument order and exit in reverse order). For ASGI hosting, combine each mcp.http_app().lifespan at the ASGI layer instead of combining dishka_lifespan instances directly, because combine_lifespans passes the same ASGI application to every lifespan.
```

--------------------------------

### Error: Async handler with a sync container

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/errors.md

Raised when an async handler tries to resolve dependencies while the root container is a sync Container from make_container(...).

```APIDOC
## Error: Async handler with a sync container

### Message
`Async handler needs an AsyncContainer; got a sync Container. Use make_async_container(...) for async tools.`

### Location
`dishka_fastmcp/_container.py`, `get_async_container` (line 210).

### Triggered by
- An `async def` (or async-generator) `@inject` handler resolving dependencies while the root container is a sync `Container` from `make_container(...)`.

### Behavior
Raised inside the handler call (surfaces as `ToolError` unless `mask_error_details=False`).
```

--------------------------------

### Error: No container for the active FastMCP application

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/errors.md

Raised when no dishka container is available for the active FastMCP application, such as when calling an @inject handler without setup_dishka or when get_async_container/get_sync_container is called outside any FastMCP operation.

```APIDOC
## Error: No container for the active FastMCP application

### Message
`No dishka container for the active FastMCP application. Call setup_dishka(container, mcp) on it, or serve it through a server whose lifespan includes dishka_lifespan(container): mounted servers find the container there during MCP requests. Also check that @inject sits below the FastMCP decorator.`

### Location
`dishka_fastmcp/_container.py`, constant `_MISSING_SETUP`; raised by `require_container` (line 192).

### Triggered by
- Calling a `@inject` handler (`@mcp.tool`/`@mcp.resource`/`@mcp.prompt`) without `setup_dishka` on the active app.
- Calling `get_async_container`/`get_sync_container` outside any FastMCP operation (direct `get_async_container((), {})`).
- A mounted server whose serving root has no `dishka_lifespan`.
- A server behind `create_proxy(...)` without its own `setup_dishka`.
- Looking a container up from a mounted server's lifespan.
- Also raised when `@inject` is placed above the FastMCP decorator and the schema was already built from the uncleaned signature.
```

--------------------------------

### Error handling for awaitable return values

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/inject.md

Shows that returning an awaitable from a tool handler results in a DishkaFastMCPError to prevent scope misuse.

```python
from dishka_fastmcp import DishkaFastMCPError, FromDishka, inject


@mcp.tool
@inject
async def broken(resource: FromDishka[Resource]) -> object:
    return resource.load_async()  # returns an awaitable — rejected
```

--------------------------------

### Run all CI checks locally

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/CONTRIBUTING.md

Runs the exact checks CI performs on Python 3.11–3.15. Includes GitHub Actions audit, formatting, linting, type checking, and tests with 100% coverage threshold.

```bash
uv run zizmor .github/        # GitHub Actions audit (offline unless GH_TOKEN is set)
uv run ruff format --check    # formatting
uv run ruff check             # linting
uv run mypy                   # type checking (strict)
uv run pyright                # type checking (strict, second checker)
uv run pytest --cov           # tests with coverage (threshold: 100%)
```

--------------------------------

### get_registered_container(app: FastMCP) -> AsyncContainer | Container | None

Source: https://github.com/bagowix/dishka-fastmcp/blob/main/_autodocs/api-reference/container-internals.md

Returns the container registered for the given FastMCP application, or None if none is registered.

```APIDOC
## get_registered_container(app: FastMCP) -> AsyncContainer | Container | None

### Description
Returns the container registered for the given FastMCP application, or None if none is registered.

### Parameters
- **app** (FastMCP) - Required - The FastMCP application to look up.

### Returns
- **AsyncContainer | Container | None** - The registered container, or None if not registered.
```
Tokens:
Raw