Migrating to v0.14–v0.18¶

This guide summarizes the breaking changes, package layout reorganization, protocol upgrades, and zero-config ergonomics introduced across litestar-mcp versions v0.14.0 through v0.18.0.

1. Release Highlights at a Glance (v0.14–v0.18)¶

2. Package Layout Reorganization (v0.14.0–v0.18.0)¶

litestar-mcp is organized into six domain subpackages with strict optional-extra isolation:

• litestar_mcp.core: Protocol-agnostic primitives (Tool, ToolCall, ToolResult, tool, ToolContext, JSONRPCRequest, JSONRPCError, JSONRPCErrorException, SubscriptionManager, TelemetryConfig, SpanManager, exceptions).
• litestar_mcp.mcp: MCP plugin (LitestarMCP), standalone wrapper (MCP), MCPConfig, MCPController, MCPHandlerService, Registry, PromptController, SkillController, Agent Skills (Skill, SkillFile, SkillCatalog, SkillSource, FilesystemSkillSource), MCP Tasks (MCPTaskStore, TaskRecord, MCPTaskExecutor, InProcessTaskExecutor, ToolTaskCall), stdio (MCPStdioContext, run_stdio, run_stdio_async), bridge (run_stdio_streamable_http_bridge), and CLI (mcp_group).
• litestar_mcp.agent: Multi-agent specifications (Agent, AgentGroup), AgentRuntime, TurnBudget, ModelClient / GoogleGenAIClient / MockModelClient, SessionStore, AgentChatController, in-process DynamicWorkflow / WorkflowEngine, and protocol bridges (agent_to_mcp, mcp_to_tools, discover_mcp_tools, agent_to_a2a).
• litestar_mcp.queues (optional queues extra): QueueTaskExecutor, DurableWorkflowEngine, WorkflowStore, WorkflowRun, NodeRecord, TaskDependencyChain, QueuedAgentChatController, QueuedTurnManager, QueuedTurn, AgentRegistry, and PrincipalSnapshot.
• litestar_mcp.a2a (optional a2a extra): LitestarA2A and A2AConfig.
• litestar_mcp.utils: Route marker decorators (mcp_tool, mcp_resource, mcp_prompt), description rendering, URI template matching, and handler signature introspection.

Deep Import Migration Map¶

Top-level imports from litestar_mcp (from litestar_mcp import LitestarMCP, MCP, MCPConfig, ...) remain unchanged. If your code imported internal module paths from v0.13 or earlier, update them as follows:

3. Removal of litestar_mcp.auth in Favor of Litestar Middleware & litestar-security¶

v0.14.0 removed the plugin-specific litestar_mcp.auth and litestar_mcp.manifests modules (MCPAuthBackend, MCPAuthConfig, OIDCProviderConfig, create_oidc_validator, JWKSCache, DefaultJWKSCache, TokenValidator), MCPConfig.auth, MCPConfig.register_oauth_protected_resource, and the plugin-mounted /.well-known/oauth-protected-resource route. The base package also depends on litestar rather than litestar[jwt].

See Authentication Middleware, JWT & Google IAP and First-Party litestar-security Integration for complete examples.

4. Dual-Version Streamable HTTP (v0.14.0 vs v0.17.0)¶

• In v0.14.0: MCP.run() changed its default transport from "sse" to transport="streamable-http" (removing transport="sse"), and /mcp initially required the stateless 2026-07-28 server/discover flow.
• Restored in v0.17.0: /mcp now negotiates both modern 2026-07-28 and initialize-era 2025-06-18 / 2025-03-26 (SUPPORTED_PROTOCOL_VERSIONS = ("2026-07-28", "2025-06-18", "2025-03-26")) on a single stateless endpoint:
• 2026-07-28 clients: Call server/discover, supply protocol metadata in params._meta, and send SEP-2575 headers (MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Param-*).
• 2025-06-18 / 2025-03-26 clients: Call initialize, notifications/initialized (receiving 202 Accepted), and ping, and may send DELETE /mcp (receiving 204 No Content).

Every JSON-RPC request (excluding notifications) must carry a string or integer-valued finite numeric id. Missing, null, boolean, container, or fractional request IDs are rejected with HTTP 400 Bad Request and JSON-RPC INVALID_REQUEST (-32600) before dependency resolution or handler execution.

5. httpx2, Streaming Backpressure & Native Stdio Lifespan (v0.14.0)¶

httpx2 Replaces httpx and the bridge Extra¶

• The runtime HTTP client dependency is httpx2 (replacing httpx and httpx-sse).
• Because httpx2 includes built-in Server-Sent Events (EventSource) support, the [bridge] optional extra was removed; litestar mcp bridge and MCPStreamableHTTPClient work out of the box with base litestar-mcp.
• Custom transports passed to run_stdio_streamable_http_bridge(..., transport=...) or MCPStreamableHTTPClient(..., transport=...) must subclass httpx2.AsyncBaseTransport.
• max_message_size (--max-message-size, default 16 MiB) now bounds each incoming SSE event from the remote server in addition to each newline-delimited stdin frame.

Streaming Backpressure & Stdio Lifespan¶

• Request progress streams use a bounded channel (MCPConfig.stream_queue_capacity=256) with producer backpressure, while subscriptions/listen streams disconnect slow consumers cleanly when their queue fills.
• MCPConfig.stream_cleanup_timeout and A2AConfig.stream_cleanup_timeout default to 5.0 seconds.
• In-process stdio (litestar mcp stdio and run_stdio_async(app, shutdown_timeout=5.0)) enters native Litestar.lifespan(). The legacy manual app_lifespan helper was removed in v0.14.0.

6. Dynamic SkillSource & Asynchronous SkillCatalog (v0.16.0)¶

In v0.14.0, MCPSkillsConfig(paths=[...]) loaded a static synchronous SkillCatalog. In v0.16.0, MCPSkillsConfig(sources=[...]) added the request-aware SkillSource protocol, making SkillCatalog methods asynchronous:

7. A2A 1.0 JSON-RPC, HTTP+JSON REST & Multi-Tenancy (v0.14.0–v0.18.0)¶

• Install litestar-mcp[a2a] (a2a-sdk>=1.1.4).
• LitestarA2A enforces A2A 1.0 (A2A-Version: 1.0 or 1.0.x).
• v0.17.0 HTTP+JSON REST & Multi-Tenancy:
• Set A2AConfig(enable_http_json=True) (enabled by default) to mount native A2A 1.0 REST endpoints (/a2a/message:send, /a2a/message:stream, /a2a/tasks/{id}, /a2a/tasks/{id}:cancel, /a2a/tasks/{id}:subscribe) alongside POST /a2a JSON-RPC 2.0.
• Set A2AConfig(agent_card_route_opt={...}) to supply separate Litestar route opt entries (such as public discovery auth policies) for /.well-known/agent-card.json independent of A2AConfig.route_opt.
• Multi-tenant requests resolve tenant identifiers from /{tenant:str}/a2a/... path prefixes or the X-A2A-Tenant header (A2AConfig.tenant_header) and pass the prepared ServerCallContext to A2AConfig.context_builder(request, context).
• v0.18.0 Direct AgentExecutor & Bridge Support:
• LitestarA2A(agent_card, request_handler, config=...) accepts an AgentExecutor directly as request_handler (wrapping it in DefaultRequestHandler with an InMemoryTaskStore automatically), and agent_to_a2a(agent, runtime=runtime) returns a ready-to-mount LitestarA2A plugin.

8. Zero-Config litestar-queues Integration & Route-Opt Inference (v0.18.0)¶

Upgrading to v0.18.0 lets you delete manual wiring across five common patterns:

1. Zero-Config QueueTaskExecutor: Registering QueuePlugin (litestar-queues>=0.13.0) on the same Litestar app as LitestarMCP automatically enables MCP Tasks and attaches QueueTaskExecutor unless MCPConfig(tasks=False) or MCPTaskConfig(executor="in_process") is explicitly set.
2. Automatic litestar_mcp_tasks Store Resolution: MCPTaskConfig.store defaults to resolving the "litestar_mcp_tasks" store from app.stores (StoreRegistry), falling back to MemoryStore().
3. Boolean Route Markers & Decorator Defaults: @get("/users", mcp_tool=True), @get("/config", mcp_resource=True), and @post("/summarize", mcp_prompt=True) (as well as @mcp_tool(), @mcp_resource(), @mcp_prompt() without a name argument) automatically name the primitive after the Python handler function.
4. Automatic Resource media_type Inheritance: Route handlers marked with mcp_resource automatically advertise their Litestar media_type (for example, @get("/report.pdf", media_type="application/pdf", mcp_resource=True)) without requiring a separate mcp_resource_mime_type override.
5. AgentRuntime & DurableWorkflowEngine as Litestar Plugins: Register AgentRuntime(agent) and DurableWorkflowEngine([workflow]) directly in Litestar(plugins=[...]) to wire the runtime and workflow_engine dependencies automatically.