Changelog#

All notable Litestar MCP changes are summarized here. Entries are grouped by release and focus on user-visible behavior, public API changes, compatibility notes, and important protocol fixes.

Recent Updates#

0.13.2#

Bugfixes#

resolve tool wire names from Parameter(name=...)#: A parameter whose wire alias came from QueryParameter(name=...) or ParameterKwarg(name=...) was advertised and dispatched under its python name, so Litestar never read it and the handler ran as if the argument had never been sent. This made every advanced-alchemy filter provider silently inert over MCP. Wire names now resolve from .name, and header/cookie parameters are excluded from query wire-name resolution.

Advertised names change for affected parameters (for example category_name_in becomes categoryNameIn). For compatibility, the python name is still accepted at dispatch and rewritten to the wire name, logging a warning; the wire name wins when both are sent.

References: https://github.com/cofin/litestar-mcp/issues/92, https://github.com/cofin/litestar-mcp/pull/93

Other changes#

correct the contributor clone URL#: The README development instructions now clone the canonical cofin/litestar-mcp repository.

References: https://github.com/cofin/litestar-mcp/pull/91

0.13.1#

Released: 2026-08-24

Bugfixes#

preserve native dispatch for controllers and request bodies#: MCP tools declared on controllers now resolve path parameters without requiring route handlers to support weak references. Path metadata is cached per application so separate Litestar applications remain isolated.

Omitted request bodies now use the handler's declared default, while explicit falsey JSON bodies such as null, false, 0, empty strings, empty lists, and empty objects are passed through unchanged.

References: https://github.com/cofin/litestar-mcp/pull/94

0.13.0#

Released: 2026-08-19

Features#

configure MCP router options and discovery route ownership#: Added MCPConfig.route_opt for mounted-router policies and separate controls for registering the OAuth protected-resource metadata and agent-card discovery routes. Applications can now let another plugin own the RFC 9728 root path without a duplicate-route startup failure.

References: https://github.com/cofin/litestar-mcp/pull/88

0.12.0#

Released: 2026-07-29

Features#

Tasks, subscriptions, and MRTR#: Added filtered subscriptions/listen streams, the opt-in io.modelcontextprotocol/tasks extension, durable Litestar Store task records, and typed multi-round-trip input_required results for tools, resources, and prompts.

References:
Concurrent stdio bridge#: The bridge now forwards independent request-scoped POST streams concurrently, multiplexes subscription responses, maps cancellation to stream closure, and lazily maps annotated tool parameters to MCP headers.

References:

0.11.1#

Bugfixes#

hide MCP plugin discovery routes from OpenAPI by default#: MCPConfig.include_in_schema=False now hides the plugin-owned /.well-known/oauth-protected-resource, /.well-known/agent-card.json, and /.well-known/mcp-server.json routes from generated OpenAPI schemas, matching the existing default behavior for the /mcp transport route. Marked application routes remain visible in OpenAPI unless the application hides them separately, and include_in_schema=True opts all MCP plugin routes back in.

References:

0.11.0#

Features#

support binary resources and explicit tool content blocks#: Adds MCPResourceLink, MCPBlobResource, and MCPToolResult helpers for protocol-shaped tool results. Marked resources can now advertise MIME metadata with mcp_resource_mime_type or mcp_resource(..., mime_type=...) and resources/read returns binary handler responses as base64 blob contents. Embedded blobs are capped by MCPConfig.max_blob_bytes before encoding; set it to None to rely on deployment or client limits instead.

References:

0.10.0#

Features#

add a Litestar CLI stdio bridge for Streamable HTTP#: Adds litestar --app my_app:app mcp bridge and the litestar-mcp[bridge] extra for stdio-only MCP clients that need to reach a running Litestar MCP app. The command is registered by the LitestarMCP CLI plugin, defaults to the loaded app's MCPConfig.base_path, and supports base URL overrides, explicit endpoints, discovery from /.well-known/mcp-server.json, static headers, token providers, stream errors, and session cleanup. It shields stdio output from accidental application print calls, reports unreachable endpoints with a bridge-owned error message, and caps each stdin JSON-RPC message at 16 MiB by default, configurable with --max-message-size. The bridge is implemented directly on httpx and optional httpx-sse and does not depend on the official mcp Python SDK or its server-side transport dependencies.

References: https://github.com/cofin/litestar-mcp/pull/79
support authenticated stdio principals#: Adds public MCPStdioContext support for MCP.run(transport="stdio", stdio_context=...). Standalone stdio dispatch now seeds synthetic Litestar scopes with user, auth, copied session, copied state, and a resolved owner_id so tools, resources, prompts, guards, and task execution can run on behalf of a process-local principal.

References: https://github.com/cofin/litestar-mcp/issues/74, https://github.com/cofin/litestar-mcp/pull/76
allow custom auth headers and token prefixes#: MCPAuthBackend now accepts header_name and token_prefix options. Existing Authorization: Bearer deployments keep the default behavior, while identity proxy deployments such as Google Cloud IAP and AWS ALB OIDC can validate raw or custom-prefixed JWTs from their provider-specific headers.

References: https://github.com/cofin/litestar-mcp/issues/75, https://github.com/cofin/litestar-mcp/pull/77

Bugfixes#

honor custom base paths in standalone internal routes#: Standalone MCP.tool(), MCP.resource(), and MCP.prompt() internal dispatch routes now follow MCPConfig.base_path instead of hard-coding /mcp/internal/....

References: https://github.com/cofin/litestar-mcp/pull/79
return the correct SSE content type for GET streams#: GET /mcp now advertises text/event-stream so strict SSE clients accept the Streamable HTTP event stream.

References: https://github.com/cofin/litestar-mcp/pull/79
reduce routine lifecycle log noise#: Routine startup, registry callback, and router-invalidation lifecycle messages are now logged at debug level instead of warning level.

References: https://github.com/cofin/litestar-mcp/issues/73, https://github.com/cofin/litestar-mcp/pull/76

Other changes#

align reference and security documentation#: Adds reference coverage for MCP, MCPStdioContext, auth helpers, tool-call callback protocols, and the bridge API. Also adds security guidance for domain authorization, bridge identity boundaries, and safe file/path arguments.

References: https://github.com/cofin/litestar-mcp/pull/78, https://github.com/cofin/litestar-mcp/pull/79

0.9.0#

Released: 2026-06-29

Features#

add a standalone MCP application surface#: Adds MCP(...) for applications whose primary surface is an MCP server. Standalone apps can register @mcp.tool, @mcp.resource, and @mcp.prompt callables, lazily expose mcp.app, pass normal Litestar app and route-handler options, run SSE through the Litestar CLI, and run line-delimited stdio JSON-RPC while manually driving ASGI lifespan.

References: https://github.com/cofin/litestar-mcp/issues/71, https://github.com/cofin/litestar-mcp/issues/72, https://github.com/cofin/litestar-mcp/pull/70

Other changes#

tighten standalone transport internals#breaking: Internal transport callers now pass a RequestContext to JSONRPCRouter.dispatch(). litestar_mcp.routes.build_jsonrpc_router is no longer exported, and handler-signature helpers moved to litestar_mcp.utils.handler_signature. Applications should prefer the public MCP and LitestarMCP entry points instead of private router construction.

References: https://github.com/cofin/litestar-mcp/pull/70
clean up runtime, docs, and optional dependency internals#: Refreshes examples, snippet coverage, optional Dishka dependency-key handling, router caching/session plumbing, framework-native serialization paths, release tooling, and Python 3.14 CI coverage.

References: https://github.com/cofin/litestar-mcp/pull/70

0.8.0#

Released: 2026-06-24

Features#

add tool-call observability callbacks#: Adds MCPConfig.before_tool_call and MCPConfig.after_tool_call hooks around tools/call dispatch for audit, metrics, and tracing use cases. The after hook receives either the result or exception plus elapsed dispatch duration, and hook failures are logged without changing tool-call behavior.

References: https://github.com/cofin/litestar-mcp/issues/68, https://github.com/cofin/litestar-mcp/pull/69

Bugfixes#

exclude Dishka-resolved provider params from tool inputs#: Litestar Provide(...) factory parameters whose annotated type can be resolved from app.state.dishka_container are no longer emitted as MCP tool arguments. Ordinary provider-declared inputs, such as pagination and filter values, still appear in schemas and dispatch.

References: https://github.com/cofin/litestar-mcp/issues/67, https://github.com/cofin/litestar-mcp/pull/69

0.7.2#

Released: 2026-06-11

Bugfixes#

include provider-declared query parameters in MCP schemas#: Query parameters declared on Litestar dependency providers now appear in MCP tool input schemas and are forwarded during tool execution, so provider-backed pagination and aliases are discoverable and callable by MCP clients.

References: https://github.com/cofin/litestar-mcp/issues/64, https://github.com/cofin/litestar-mcp/pull/65

0.7.1#

Released: 2026-06-09

Bugfixes#

fix published project URLs#: Corrects package metadata links so the project URL points at the GitHub repository and the documentation URL points at the published docs site.

References: https://github.com/cofin/litestar-mcp/pull/60
return 202 for accepted Streamable HTTP notifications#: Accepted JSON-RPC notifications over MCP Streamable HTTP now return 202 Accepted with an empty body, matching the MCP transport requirement for accepted JSON-RPC notifications and responses sent via POST.

References: https://github.com/cofin/litestar-mcp/issues/61
apply filters to direct tool and resource invocation#: include_* and exclude_* filters now gate direct tools/call and resources/read invocation in addition to list responses. A filtered tool, resource, or resource template is treated like an unknown name or URI. Filters narrow the MCP exposure surface; Litestar guards and auth middleware remain the access-control boundary.

References: https://github.com/cofin/litestar-mcp/issues/62

0.7.0#

Released: 2026-06-07

Features#

paginate MCP list methods#: Adds opaque cursor pagination for MCP list methods so clients can page through tools, resources, resource templates, and prompts using nextCursor.

References: https://github.com/cofin/litestar-mcp/issues/47, https://github.com/cofin/litestar-mcp/pull/58

Bugfixes#

converge handler signature introspection#: Uses the same handler-signature introspection path for schema generation and execution-time argument handling, reducing drift between advertised input schemas and accepted call arguments.

References: https://github.com/cofin/litestar-mcp/issues/49, https://github.com/cofin/litestar-mcp/pull/58
document the MCP primitive error contract#: Locks and documents the primitive-level error contract for tools, resources, and prompts. Handler HTTP status is preserved in error data where relevant instead of minting non-standard JSON-RPC codes.

References: https://github.com/cofin/litestar-mcp/issues/48, https://github.com/cofin/litestar-mcp/pull/58

Other changes#

document MCP Prompts end-to-end#: Adds Prompts coverage across the usage guide, API reference, README, and task-manager example.

References: https://github.com/cofin/litestar-mcp/issues/56, https://github.com/cofin/litestar-mcp/pull/58

0.6.0#

Released: 2026-06-04

Features#

add MCP Prompts support#: Adds MCP Prompts support, including prompt discovery and retrieval via prompts/list and prompts/get.

References: https://github.com/cofin/litestar-mcp/pull/46

Bugfixes#

unwrap Annotated parameters in input schemas#: Unwraps Annotated[T, Parameter(...)] declarations when generating MCP tool input schemas so Litestar parameter metadata does not hide the underlying value type.

References: https://github.com/cofin/litestar-mcp/issues/52, https://github.com/cofin/litestar-mcp/pull/53

Other changes#

update for Litestar 3 deprecations#: Updates runtime, docs, and tests for Litestar 3 deprecation paths.

References: https://github.com/cofin/litestar-mcp/pull/54

0.5.1#

Released: 2026-04-19

Bugfixes#

restore full Litestar execution parity#: Runs MCP tool execution through the full Litestar request lifecycle for hooks, renamed fields, and path-parameter coercion.

References: https://github.com/cofin/litestar-mcp/issues/41, https://github.com/cofin/litestar-mcp/issues/42, https://github.com/cofin/litestar-mcp/issues/43, https://github.com/cofin/litestar-mcp/pull/44

0.5.0#

Released: 2026-04-19

Features#

add consumer-readiness features#: Adds structured tool/resource descriptions, resource templates, resources/templates/list, completion/complete, injectable JWKS cache support, and well-known discovery documents.

References: https://github.com/cofin/litestar-mcp/pull/40

Other changes#

refresh docs and examples for consumer usage#: Raises the supported Python floor to 3.10, renames bundled examples to hello_world and task_manager, adds example tests and snippet markers, and updates docs to prefer Litestar route kwargs such as mcp_tool="name".

References: https://github.com/cofin/litestar-mcp/pull/40
remove scope enforcement and auth extra#breaking: Removes inline scope enforcement so scopes are discovery metadata and Litestar guards are the access-control surface. The legacy auth extra was removed and auth dependencies now install with the core package.

References: https://github.com/cofin/litestar-mcp/pull/40

0.4.0#

Released: 2026-04-16

Features#

switch to Streamable HTTP#: Replaces the legacy REST endpoint surface with MCP Streamable HTTP, using GET /mcp for SSE and POST /mcp for JSON-RPC requests.

References: https://github.com/cofin/litestar-mcp/pull/32

Other changes#

add database integration test matrix#: Adds database-backed integration coverage for Advanced Alchemy, SQLSpec, Dishka, and auth-mode combinations.

References: https://github.com/cofin/litestar-mcp/pull/34

0.3.0#

Released: 2026-03-22

Features#

align with MCP JSON-RPC, transport, and auth specs#: Adds MCP spec compliance for JSON-RPC 2.0, Streamable HTTP, and OAuth auth bridging.

References: https://github.com/cofin/litestar-mcp/pull/13

0.2.2#

Released: 2025-09-30

Bugfixes#

remove duplicate CLI pass_context decorator#: Removes a duplicate pass_context decorator from CLI commands.

References: https://github.com/cofin/litestar-mcp/pull/6

0.2.1#

Released: 2025-09-28

Features#

add Litestar CLI plugin integration#: Implements Litestar CLI plugin integration.

References: https://github.com/cofin/litestar-mcp/pull/5

0.2.0#

Released: 2025-09-27

Features#

add CLI interface#: Adds the initial command-line interface.

References: https://github.com/cofin/litestar-mcp/pull/4

0.1.0#

Released: 2025-09-06

Features#

initial release#: Adds the initial Litestar MCP plugin with route marking via mcp_tool and mcp_resource kwargs, automatic route discovery, REST-based MCP endpoints, OpenAPI schema exposure, MCPConfig, and support for tools and resources.

References: