API Reference¶
This reference documents the public Python API, CLI subcommands, and contributor workflow for litestar-mcp. Every class, protocol, struct, decorator, and function listed in these chapters is rendered directly from static AST and PEP 257 attribute docstrings.
Package Boundaries & Import Surface¶
litestar-mcp is organized into focused subpackages so optional integrations (litestar-queues, a2a-sdk, google-genai, opentelemetry-api, dishka, litestar-security) are never imported unless configured by your application.
| Package Namespace | Optional Extra | Responsibilities & Primary Exports |
|---|---|---|
litestar_mcp |
Base package | Top-level convenience re-exports (LitestarMCP, MCP, MCPConfig, MCPOptKeys, MCPTaskConfig, MCPSkillsConfig, MCPController, PromptController, SkillController, @mcp_tool, @mcp_resource, @mcp_prompt, @tool, @prompt, Skill, SkillSource, FilesystemSkillSource, MCPToolResult, MCPResourceLink, MCPBlobResource, MCPInputRequiredResult, MCPRequestContext, MCPStdioContext) and lazy resolution for LitestarA2A, A2AConfig, and litestar_mcp.agent. |
litestar_mcp.core |
Base package (otel optional) |
Protocol-agnostic primitives: Tool, ToolCall, ToolResult, ToolArgumentError, @tool, ToolContext, JSON-RPC 2.0 models (JSONRPCRequest, JSONRPCError, JSONRPCErrorException), SSE SubscriptionManager, OpenTelemetry TelemetryConfig and SpanManager, and core exceptions (LitestarMCPError, MissingDependencyError, BridgeConnectionError, BridgeMessageTooLargeError). |
litestar_mcp.mcp |
Base package | MCP server runtime, route discovery, Registry, MCPHandlerService, internal ASGI execution (execute_tool, execute_handler_response, blank_http_scope), MCPTaskStore and MCPTaskRuntime, Agent Skills (SkillCatalog, SkillIntegrityError), stdio transport (ASGIStreamingTransport, run_stdio, run_stdio_async), Streamable HTTP bridge (run_bridge, run_stdio_streamable_http_bridge), and MCPStreamableHTTPClient. |
litestar_mcp.queues |
litestar-mcp[queues] |
Distributed execution on litestar-queues: QueueTaskExecutor, run_mcp_tool_task, DurableWorkflowEngine, WorkflowStore, WorkflowRun, NodeRecord, TaskDependencyChain, QueuedAgentChatController, QueuedTurnManager, QueuedTurn, AgentRegistry, PrincipalSnapshot, and run_agent_turn. |
litestar_mcp.agent |
Base package (google / a2a optional) |
Multi-agent orchestration and in-process workflows: Agent, AgentGroup, AgentMessage, AgentRuntime, TurnRequest, TurnResponse, TurnBudget, BudgetExceededError, AgentChatController, SessionStore (MemorySessionStore, LitestarStoreSessionStore), ModelClient (GoogleGenAIClient, MockModelClient), AgentStreamFrame, DynamicWorkflow, WorkflowNode, WorkflowEngine, and litestar_mcp.agent.bridges. |
litestar_mcp.a2a |
litestar-mcp[a2a] |
Agent-to-Agent (A2A 1.0) protocol plugin (LitestarA2A, A2AConfig) mounting JSON-RPC 2.0 (POST /a2a), optional HTTP+JSON REST routes, and /.well-known/agent-card.json discovery around a2a-sdk. |
litestar_mcp.utils |
Base package | Route and function decorators (mcp_tool, mcp_resource, mcp_prompt), schema description bounds validation (validate_tool_descriptions), and handler signature introspection helpers. |
Reference Chapters¶
Plugin & Configuration
LitestarMCP plugin lifecycle, standalone MCP application wrapper, MCPConfig, MCPOptKeys, MCPTaskConfig, MCPSkillsConfig, tool-call hooks, and MCPController.
Primitives, Controllers & Skills
@mcp_tool, @mcp_resource, @mcp_prompt, PromptController, SkillController, Agent Skills (SkillSource, FilesystemSkillSource, SkillCatalog), content blocks, Registry, and MCPHandlerService.
Tasks, Queues & Durable Workflows
MCPTaskExecutor, MCPTaskRuntime, MCPTaskStore, TaskRecord, QueueTaskExecutor, DurableWorkflowEngine, WorkflowStore, TaskDependencyChain, QueuedAgentChatController, and QueuedTurnManager.
Agents, Sessions & Workflows
Agent, AgentGroup, AgentRuntime, TurnBudget, AgentChatController, SessionStore backends, GoogleGenAIClient, AgentStreamFrame, DynamicWorkflow, and WorkflowEngine.
A2A 1.0, Bridges & Transports
LitestarA2A, A2AConfig, bidirectional MCP and A2A bridges (agent_to_mcp, mcp_to_tools, discover_mcp_tools, agent_to_a2a), MCPStdioContext, HTTP bridge runners, and MCPStreamableHTTPClient.
Core Primitives & Observability
Core Tool and @tool, ToolContext, TelemetryConfig, SpanManager, JSON-RPC 2.0 structures, SubscriptionManager, exception hierarchy, and internal ASGI executors.
CLI Reference
Auto-generated reference and practical recipes for litestar mcp stdio, litestar mcp bridge, litestar mcp export-tool-spec, list-tools, list-resources, and run.
Contributing Guide
Local workspace setup, running unit and protocol conformance suites, type-checking and linting gates, and the documentation verification pipeline.
Release History¶
See the Changelog for release notes, new capabilities, and migration notes across versions v0.1.0 through v0.18.0.