Framework Integration¶

The plugin is a first-class Litestar citizen. It participates in the plugin system, works alongside guards and middleware, and surfaces through OpenAPI when asked.

Plugin Ordering¶

Register LitestarMCP in your application's plugins list. Ordering matters when other plugins touch the same route metadata - register MCP after plugins that mutate handlers (e.g. DI or serialization plugins) so their mutations are visible at discovery time.

docs/examples/snippets/framework_litestar.py¶

app = Litestar(
    route_handlers=[],
    plugins=[LitestarMCP(MCPConfig(base_path="/mcp"))],
)

Dependency Providers and Dishka¶

Tool input schemas include user-supplied parameters declared on Litestar Provide(...) factories, such as pagination or filter parameters. When an app also uses Dishka via dishka.integrations.litestar.setup_dishka, provider-factory parameters whose annotated type is resolvable from the Dishka container are treated as external DI inputs instead of MCP tool arguments. This keeps Dishka-backed services out of tools/list schemas and tools/call validation while preserving ordinary Litestar provider parameters.

OpenAPI Integration¶

Marked routes appear in the OpenAPI schema just like any other handler. The MCP routes themselves (/mcp and /.well-known/*) are hidden by default - pass include_in_schema=True on MCPConfig to expose them.

The plugin also uses your OpenAPI security declarations to populate /.well-known/oauth-protected-resource automatically: if your app uses OAuth2PasswordBearerAuth or publishes an OAuth2 security scheme, the RFC 9728 metadata picks up the scopes without additional config.

Guards on MCP Routes¶

Attach Litestar guards to the MCP router by passing them through MCPConfig:

MCPConfig(guards=[my_guard])

Guards run on /mcp exactly as they do for any other handler. The well-known discovery endpoints intentionally bypass guards so clients can negotiate authentication before presenting a token (see Discovery).

Custom Base Path¶

By default the transport is served at /mcp. Override this with base_path on MCPConfig when mounting the plugin under an API prefix:

MCPConfig(base_path="/api/mcp") publishes the transport at /api/mcp and emits discovery documents that advertise the same URL.
Well-known documents always live under /.well-known/* regardless of base_path; that is part of the RFC.

Filtering Exposure¶

Use the include_tags / exclude_tags and include_operations / exclude_operations options to restrict which marked handlers are exposed. Filters apply to tools/list, resources/list, resources/templates/list, direct tools/call, and direct resources/read. A filtered handler is omitted from list responses and direct invocation returns the same not-found response as an unknown name or URI. Precedence is exclude > include and tags > operations. Filters are not authentication; use MCP router guards or auth middleware for access control.