Skip to content

MCP Protocol & Primitives Overview

litestar-mcp turns an existing Litestar application—or a standalone MCP wrapper—into a compliant Model Context Protocol server without duplicating business logic, validation schemas, or dependency injection wiring.

The plugin follows a direct compilation pipeline:

  1. Declare or Mark: Tag existing Litestar route handlers with mcp_tool, mcp_resource, or mcp_prompt keyword arguments, apply @mcp_tool / @mcp_resource / @mcp_prompt decorators, or mount class-based PromptController and SkillController routers.
  2. Discover & Compile: During on_app_init, LitestarMCP inspects app.routes and MCPConfig, builds JSON Schema 2020-12 contracts from parsed_fn_signature, infers ToolAnnotations hints from HTTP methods, and populates the Registry and SkillCatalog.
  3. Dispatch via Internal ASGI Scope: Incoming JSON-RPC 2.0 calls over Streamable HTTP (POST /mcp, DELETE /mcp) or in-process stdio execute through a synthesized internal HTTP scope (execute_tool, execute_handler), running your Litestar middleware, guards, Provide dependencies, and Dishka Scope.REQUEST containers identically across every transport.
MCP Tools and ToolAnnotations Compilation Pipeline Litestar routes marked with mcp_tool or @mcp_tool compile signature types, Provide dependencies, and HTTP verb hints into JSON Schema and ToolAnnotations for tools/list and tools/call. 1. Route Declaration mcp_tool=True | "name" @mcp_tool(...) / @mcp.tool() mcp_tool_annotations=ToolAnnotations mcp_tool_output_schema={...} task=True | "required" | "optional" HTTP verb -> readOnly/idempotent hints 2. Registry Schema Builder Registry.register_tool() Extracts msgspec / Pydantic / dataclass Strips Dishka & internal DI params Precedence: description > summary > doc Applies include/exclude tag filters litestar mcp export-tool-spec 3. JSON-RPC Execution tools/list & tools/call Dispatches via internal ASGI scope Emits structuredContent when typed Supports ToolContext.report_progress Handles params.task async execution isError: true on 4xx/5xx tool errors
MCP Resources and RFC 6570 URI Templates Pipeline Static resources and parameterized RFC 6570 URI templates register in the MCP Registry, supporting resources/list, resources/templates/list, resources/read, and resources/subscribe. 1. Resource & Template Opts mcp_resource="name" mcp_resource_uri="app://config" mcp_resource_template="notes://{id}" @mcp_resource / @mcp.resource() Built-in: litestar://openapi RFC 6570 Level 1 Path Variables 2. URI Matcher & Subscriptions Registry Resource Index Compiles URI regex & param extractors Infers MIME type (application/json) Tracks active URI subscriptions Optional ChannelsPlugin fan-out notify_resource_updated(uri) 3. Resource JSON-RPC Surface resources/read & list resources/list (static URIs) resources/templates/list (RFC 6570) resources/subscribe & unsubscribe Returns text or base64 blob contents notifications/resources/updated
MCP Prompts and PromptController Compilation Pipeline Prompts declared via route markers, @mcp_prompt, or class-based PromptController resolve dependencies through Litestar and Dishka DI during prompts/get. 1. Prompt Authoring PromptController / @mcp_prompt Route opt: mcp_prompt="name" Class-based PromptController Universal DI: Provide / FromDishka[T] Inject() & Depends(fn) markers Controller-level guards & dependencies 2. Prompt Argument Schema PromptArgument Extraction Excludes DI & Request parameters Derives required/optional arguments Parses Google docstring Args table Supports completion suggestions completion/complete handler 3. Prompt Message Normalization prompts/list & prompts/get Executes within ASGI request scope Normalizes str, dict, or list[dict] Produces role + TextContent blocks Enforces controller & route guards messages: [{role, content}]
Agent Skills SEP-2640 and SkillSource Pipeline MCPSkillsConfig combines static FilesystemSkillSource directories, request-aware SkillSource plugins, and SkillController classes into the io.modelcontextprotocol/skills extension and skills:// resources. 1. Skill Sources (SEP-2640) MCPSkillsConfig paths=[Path("skills")] (SKILL.md) sources=[CustomSkillSource()] SkillController & @skill_list/@skill_load Skill.build() & Skill.from_content() SkillFile.from_content() + SHA-256 2. Request-Aware Resolution CompositeSkillSource Passes Request + DI per invocation Tenant & user-scoped skill filtering Path traversal protection & symlink guard Parses YAML frontmatter & manifest io.modelcontextprotocol/skills 3. Dual Discovery Surface skills/* & skills://* skills/list (cursor pagination) skills/load (SKILL.md + file manifest) skills/read_file (UTF-8 or base64) expose_as_resources: skills://{name} skills://{name}/{path} fallback

The Four MCP Surface Primitives

Primitive Registration Surface JSON-RPC Wire Methods Primary Purpose
Tools mcp_tool=True / @mcp_tool / SkillController (@tool) tools/list, tools/call Executable operations that accept structured JSON arguments, run validation and guards, and return structured or binary content blocks (or promote long-running work to background MCP Tasks).
Resources mcp_resource=True / @mcp_resource / mcp_resource_template resources/list, resources/templates/list, resources/read Read-only application state, schemas (litestar://openapi), binary projections, and parameterized RFC 6570 Level 1 URI templates (app://workspaces/{workspace_id}/files/{file_id}).
Prompts mcp_prompt=True / @mcp_prompt / PromptController (@prompt) prompts/list, prompts/get Templated model instructions and multi-message conversation starters normalized into MCP PromptMessage sequences with optional controller-level instructions.
Agent Skills MCPSkillsConfig(paths=[...], sources=[...]) / SkillController skills/list, skills/get, resources/directory/read, resources/read Reusable SKILL.md instruction bundles and supporting files (io.modelcontextprotocol/skills, SEP-2640) served from digest-locked filesystem folders or dynamic request-aware SkillSource providers.

Protocol Versions & Capabilities

LitestarMCP supports dual-version stateless Streamable HTTP negotiation on a single endpoint (MCPConfig.base_path, defaulting to /mcp):

  • Supported Protocol Versions: SUPPORTED_PROTOCOL_VERSIONS = ("2026-07-28", "2025-06-18", "2025-03-26").
  • Stateless 2026-07-28 Discovery: Uses server/discover and enforces SEP-2575 request metadata (params._meta["io.modelcontextprotocol/protocolVersion"], params._meta["io.modelcontextprotocol/clientCapabilities"]) paired with HTTP routing headers (MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Param-*).
  • Session-Oriented 2025-06-18 & 2025-03-26 Handshake: Supports initialize, notifications/initialized, ping, 202 Accepted on notifications/*, and 204 No Content on DELETE /mcp for broad ecosystem compatibility with existing MCP clients and inspectors.
  • Opt-In Extensions:
  • io.modelcontextprotocol/tasks: Advertised when MCPConfig.tasks is enabled (or auto-wired when litestar-queues QueuePlugin is installed on the application).
  • io.modelcontextprotocol/skills: Advertised with {"directoryRead": true | false} when MCPConfig.skills is configured.

Core Guides in This Section

Configuration

Complete MCPConfig, MCPOptKeys, MCPTaskConfig, and MCPSkillsConfig reference, operation/tag filtering precedence, opaque-cursor pagination, and lifecycle callbacks.

Marking Routes & Decorators

Compare route opt keyword arguments with @mcp_tool, @mcp_resource, and @mcp_prompt, description fallback precedence, docstring DI stripping, and universal dependency injection.

Tools & Annotations

Internal ASGI execution, JSON Schema 2020-12 synthesis, automatic HTTP verb ToolAnnotations inference, explicit input_schema, binary content blocks, and the isError: true contract.

Resources & URI Templates

Static resources, automatic media_type inference, RFC 6570 Level 1 URI templates, built-in litestar://openapi, skill:// resolution order, and resource subscriptions.

Prompts & PromptController

Standalone @mcp_prompt functions, route-bound prompts, class-based PromptController with prepended instructions and guards, and return value normalization.

Agent Skills (SEP-2640)

Static filesystem SKILL.md bundles, startup validation, dynamic request-aware SkillSource implementations with SHA-256 verification, and SkillController unification.

Discovery & Protocol Versions

Dual-version Streamable HTTP negotiation across 2026-07-28 (server/discover + SEP-2575 headers) and 2025-06-18 / 2025-03-26 (initialize, ping, DELETE /mcp).

Stdio, HTTP Bridge & Tool Spec

In-process litestar mcp stdio (`MCPStdioContext`), remote litestar mcp bridge proxy flags, and static tool manifest export via litestar mcp export-tool-spec.