Litestar MCP

Litestar plugin for Model Context Protocol (MCP) integration

The Litestar MCP Plugin enables integration between Litestar web applications and the Model Context Protocol (MCP), allowing AI models to interact with your marked application routes through MCP Streamable HTTP and JSON-RPC.

Features

✨ Simple Integration: Mark routes with kwargs to expose them via MCP 🔧 Lightweight: Minimal configuration and dependencies 🚀 Protocol-Native: Uses MCP Streamable HTTP, JSON-RPC, and SSE directly 📊 OpenAPI Integration: Automatic OpenAPI schema exposure 🎯 Type Safe: Full type hints with dataclasses 🔐 Auth-Ready: Optional OAuth metadata and bearer-token validation hooks

Installation

pip install litestar-mcp

Quick Start

Add MCP capabilities to your Litestar application by marking routes:

from litestar import Litestar, get
from litestar_mcp import LitestarMCP

# Mark routes for MCP exposure using kwargs
@get("/users", mcp_tool="list_users")
async def get_users() -> list[dict]:
    """List all users - exposed as MCP tool."""
    return [{"id": 1, "name": "Alice"}]

@get("/schema", mcp_resource="user_schema")
async def get_schema() -> dict:
    """User schema - exposed as MCP resource."""
    return {"type": "object", "properties": {"id": "integer", "name": "string"}}

# Regular routes are not exposed to MCP
@get("/health")
async def health_check() -> dict:
    return {"status": "ok"}

# Add MCP plugin
app = Litestar(
    route_handlers=[get_users, get_schema, health_check],
    plugins=[LitestarMCP()]
)

Your application now exposes MCP endpoints at /mcp plus well-known metadata documents that AI models can use to:

  • 🔍 Discover marked routes via tools and resources

  • 📊 Access your application's OpenAPI schema

  • 🛠️ Execute marked tools and read marked resources

Core Concepts

Model Context Protocol (MCP)

An open standard that enables AI models to securely access and interact with external systems.

Tools (mcp_tool)

Functions that AI models can execute - mark routes with mcp_tool="name" kwargs.

Resources (mcp_resource)

Read-only data that AI models can access - mark routes with mcp_resource="name" kwargs.

Route Marking

Use mcp_tool or mcp_resource kwargs in route decorators - Litestar automatically adds these to the route's opt dictionary.

How It Works

  1. Mark Routes: Add mcp_tool or mcp_resource kwargs to your route decorators

  2. Litestar Processing: Litestar automatically moves these kwargs into the route handler's opt dictionary

  3. Plugin Discovery: The plugin scans route handlers' opt dictionaries for MCP markers at app startup

  4. MCP Exposure: Marked routes become available through the MCP Streamable HTTP transport surface

  5. AI Interaction: AI models can discover and interact with your marked routes

Kwargs to Opt Mechanism

Litestar automatically funnels unknown kwargs in route decorators into the handler's opt dictionary. This is the recommended way to mark routes for MCP — pass the metadata straight through to @get / @post / etc. and let Litestar wire up handler.opt for you:

@get("/users", mcp_tool="list_users", mcp_description="List every user.")
async def get_users() -> list[dict]:
    ...

The plugin reads these MCP kwargs from handler.opt:

  • mcp_tool, mcp_resource — mark the handler as a tool / resource

  • mcp_resource_template — RFC 6570 URI template for templated resources

  • mcp_description, mcp_resource_description — LLM-facing description

  • mcp_agent_instructions — rendered as ## Instructions

  • mcp_when_to_use — rendered as ## When to use

  • mcp_returns — rendered as ## Returns

Stacking @mcp_tool(...) / @mcp_resource(...) on top of the route decorator is still supported (and is useful when you need output_schema, annotations, scopes, or task_support — fields that do not have opt-key equivalents), but the kwarg form is shorter and the right default 99% of the time.

Available Endpoints

Once configured, your application exposes:

  • /mcp - Streamable HTTP MCP endpoint for JSON-RPC and SSE

  • /.well-known/mcp-server.json - MCP server manifest

  • /.well-known/agent-card.json - Agent metadata document

  • /.well-known/oauth-protected-resource - OAuth metadata when auth is enabled

What Makes This Different?

  • Route-Centric: Mark individual routes for MCP exposure using simple kwargs

  • Minimal Setup: Just add mcp_tool or mcp_resource kwargs to existing route handlers

  • Protocol-Native: Uses MCP Streamable HTTP and JSON-RPC directly

  • Litestar Native: Built specifically for Litestar applications using the opt mechanism

Getting Started

Check out the Getting Started guide to learn the basics, or explore the Usage Guide for deeper topics.

Community

Indices and tables