/litestar-mcp

name: litestar-mcp
description: "Auto-activate for litestar_mcp, LitestarMCP, MCP, MCPConfig, mcp.app, mcp.run(), @mcp.tool/resource/prompt, MCPAuthConfig, MCPAuthBackend, mcp_tool=, mcp_resource=, Streamable HTTP, stdio, or OIDC MCP endpoints. Not for non-Litestar MCP servers or clients — use the official MCP Python SDK instead."

litestar-mcp

`litestar-mcp` exposes explicitly marked Litestar route handlers as [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools, resources, and prompts over JSON-RPC 2.0.

Version `0.13.0` follows the stateless MCP specification (protocol `2026-07-28`). The 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. See [Stateless Protocol](references/stateless-protocol.md).

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

• PEP 604 unions: `T | None`, never `Optional[T]`
• Consumer Litestar app modules MAY use `from __future__ import annotations`
• Async all I/O. Pure standalone `@mcp.tool` / `@mcp.resource` / `@mcp.prompt` functions may be sync; keep blocking I/O out of the event loop.

Quick Reference

Install

pip install litestar-mcp

Or install with bridge extras for the stdio-to-HTTP proxy:

pip install "litestar-mcp[bridge]"

Basic Setup

from litestar import Litestar, get, post
from litestar_mcp import LitestarMCP, MCPConfig


@get("/users", mcp_tool="list_users")
async def list_users() -> list[dict[str, str | int]]:
    """List all registered users."""
    return [{"id": 1, "name": "Alice"}]


@post("/analyze", mcp_tool="analyze_data")
async def analyze_data(data: dict[str, str]) -> dict[str, int]:
    """Analyze provided key-value dataset."""
    return {"count": len(data)}


@get("/config", mcp_resource="app_config")
async def get_app_config() -> dict[str, bool]:
    """Read the active application configuration."""
    return {"debug": False}


app = Litestar(
    route_handlers=[list_users, analyze_data, get_app_config],
    plugins=[LitestarMCP(MCPConfig(name="My API"))],
)

The default MCP surface is:

| Endpoint | Purpose | | --- | --- | | `POST /mcp` | The only transport route. JSON-RPC endpoint for `server/discover`, `tools/*`, `resources/*`, `prompts/*`, `completion/complete`, `subscriptions/listen`, and optional task methods | | `GET /.well-known/agent-card.json` | Agent card metadata (enabled by `register_agent_card=True`) | | `GET /.well-known/oauth-protected-resource` | RFC 9728 OAuth protected-resource metadata (enabled by `register_oauth_protected_resource=True`; populated from `auth`) |

MCPConfig

| Option | Type | Default | Description | | --- | --- | --- | --- | | `base_path` | `str` | `"/mcp"` | URL prefix for the MCP transport endpoint | | `include_in_schema` | `bool` | `False` | Include the MCP router and all `/.well-known/*` discovery routes in OpenAPI | | `name` | `str \| None` | `None` | Server name; defaults to OpenAPI title | | `instructions` | `str \| None` | `None` | Server instructions advertised to MCP clients | | `guards` | `list[Any] \| None` | `None` | Litestar guards applied to the MCP router | | `route_opt` | `dict[str, Any] \| None` | `None` | Route `opt` mapping applied to the mounted MCP router (e.g. for opt-based auth/permission policies) | | `register_oauth_protected_resource` | `bool` | `True` | Whether to register RFC 9728 `/.well-known/oauth-protected-resource` route; disable when another plugin owns root discovery | | `register_agent_card` | `bool` | `True` | Whether to register `/.well-known/agent-card.json` discovery route | | `allowed_origins` | `list[str] \| None` | `None` | Restrict accepted `Origin` headers | | `include_operations` | `list[str] \| None` | `None` | Only expose matching operation names | | `exclude_operations` | `list[str] \| None` | `None` | Exclude matching operation names | | `include_tags` | `list[str] \| None` | `None` | Only expose routes with matching OpenAPI tags | | `exclude_tags` | `list[str] \| None` | `None` | Exclude routes with matching OpenAPI tags | | `auth` | `MCPAuthConfig \| None` | `None` | OAuth protected-resource metadata | | `tasks` | `bool \| MCPTaskConfig` | `False` | Enable MCP task support. Pass `MCPTaskConfig` to configure the backing `Store` and record TTLs | | `opt_keys` | `MCPOptKeys` | `MCPOptKeys()` | Rename the `handler.opt` keys the plugin reads | | `cache_ttl_ms` | `int` | `0` | Response cache lifetime in milliseconds; `0` disables caching | | `cache_scope` | `Literal["private", "public"]` | `"private"` | Whether cached responses may be shared between callers | | `subscription_max_streams` | `int` | `10000` | Max concurrent SSE streams | | `subscription_keepalive_seconds` | `float` | `15.0` | Seconds between SSE keepalive pings | | `subscription_channels` | `Any \| None` | `None` | Channels backend backing `subscriptions/listen` fan-out | | `list_page_size` | `int` | `100` | Page size for `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list` | | `before_tool_call` | `BeforeToolCallHook \| None` | `None` | Observe each `to