litestar-mcp

litestar-mcp exposes explicitly marked Litestar route handlers and class-based SkillController / PromptController definitions as Model Context Protocol (MCP) tools, resources, prompts, and skills over JSON-RPC 2.0, provides a multi-agent runtime (litestar_mcp.agent) with distributed queue execution (litestar_mcp.queues), and includes an optional A2A 1.0 adapter (LitestarA2A) backed by a2a-sdk.

Version 0.16.0 follows the stateless MCP specification (protocol 2026-07-28). The MCP transport is POST-only and request-scoped: the legacy initialize handshake, sessions and Mcp-Session-Id, ping, GET and DELETE transport handlers, replay, and /.well-known/mcp-server.json are removed. Each request supplies protocol version, method, and client capabilities; named calls also supply matching name or URI metadata. Call server/discover for capabilities. Version 0.16.0 also ships:

• Static and dynamic io.modelcontextprotocol/skills catalogs (MCPSkillsConfig(paths=..., sources=...), FilesystemSkillSource, async request-aware SkillSource protocol, and in-memory Skill.build / Skill.from_content / SkillFile.from_content).
• Class-based SkillController and PromptController (@tool, @prompt, PromptMessage) with recursive discovery across nested Router / DishkaRouter / litestar-autowire trees and automatic RESERVED_KWARGS parameter aliasing.
• Universal dependency injection across HTTP routes, MCP tools/call / prompts/get, and standalone AgentRuntime (Tool.execute): Litestar Provide / Dependency, Dishka FromDishka[T], generic Annotated[T, Inject()] / Depends(fn) markers, and ToolContext(container=..., dependency_resolver=...).
• Streamable HTTP client and stdio bridge (MCPStreamableHTTPClient, prepare_mcp_request, mcp_request_headers, and run_stdio_streamable_http_bridge) powered by httpx2 in core.
• Agent runtime, workflows, and protocol bridges (litestar_mcp.agent: Agent, AgentGroup, AgentRuntime, GoogleGenAIClient defaulting to gemini-3.8-flash, AgentChatController, DynamicWorkflow, WorkflowEngine, agent_to_mcp, agent_to_a2a, mcp_to_tools, discover_mcp_tools), plus optional distributed queue execution (litestar_mcp.queues: QueuedAgentChatController, QueuedTurnManager, AgentRegistry) and OpenTelemetry GenAI spans (TelemetryConfig, SpanManager).
• Standards-backed A2A 1.0 and OAuth 2.1 discovery: LitestarA2A / A2AConfig (litestar-mcp[a2a], a2a-sdk>=1.1.4) and litestar-security route authentication policies plus RFC 9728 /.well-known/oauth-protected-resource discovery. See Stateless Protocol.

Mark routes by passing mcp_tool="name", mcp_resource="name", or mcp_prompt="name" directly to the Litestar route decorator — Litestar funnels unknown kwargs into handler.opt, so no opt={...} wrapper is needed. Use the decorator forms for structured metadata: @mcp_tool adds schemas, annotations, scopes, and task policy; @mcp_prompt adds title, arguments, and icons. Route description keys are mcp_description, mcp_resource_description, and mcp_prompt_description; MCPOptKeys can rename every key the plugin reads. There is no opt={"mcp_tool_name": ...} form or mcp_exclude key. To hide a route, leave it unmarked.

Code Style Rules