Getting Started

The Litestar MCP plugin lets AI models interact with your Litestar application through the Model Context Protocol (MCP). You mark individual routes with kwargs, and the plugin exposes them over MCP Streamable HTTP and JSON-RPC.

Core Concepts

Model Context Protocol (MCP)

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

Tools (mcp_tool)

Operations that AI models can execute — mark routes with mcp_tool="name".

Resources (mcp_resource)

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

Route Marking

Pass mcp_tool / mcp_resource / mcp_prompt kwargs to your route decorators; Litestar funnels them into the handler's opt dictionary, where the plugin discovers them at startup.

How It Works

  1. Mark routes — add mcp_tool / mcp_resource / mcp_prompt kwargs to your route decorators.

  2. Litestar processing — Litestar moves those kwargs into the route handler's opt dictionary.

  3. Plugin discovery — at startup the plugin scans handler opt dictionaries for MCP markers.

  4. MCP exposure — marked routes become available through the MCP Streamable HTTP transport surface.

  5. AI interaction — AI models discover and interact with your marked routes.

Installation

Install from PyPI using pip:

pip install litestar-mcp

Or using uv:

uv add litestar-mcp

Basic Usage

The simplest way to add MCP support to your Litestar application:

from litestar import Litestar, get
from litestar_mcp import LitestarMCP

@get("/")
async def hello() -> dict[str, str]:
    return {"message": "Hello from Litestar!"}

# Add MCP plugin with default configuration
app = Litestar(
    route_handlers=[hello],
    plugins=[LitestarMCP()]
)

That's it! Your application now has MCP endpoints available at:

  • /mcp - Streamable HTTP MCP endpoint

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

Marking Routes for MCP Exposure

To expose your routes as MCP tools or resources, mark them using kwargs:

from litestar import Litestar, get
from litestar_mcp import LitestarMCP

# Mark a route as an MCP tool (executable)
@get("/users", mcp_tool="list_users")
async def get_users() -> list[dict]:
    """List all users in the system."""
    return [{"id": 1, "name": "Alice"}]

# Mark a route as an MCP resource (readable data)
@get("/schema", mcp_resource="user_schema")
async def get_user_schema() -> dict:
    """Get the user data schema."""
    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"}

app = Litestar(
    route_handlers=[get_users, get_user_schema, health_check],
    plugins=[LitestarMCP()]
)

Configuration

Customize the MCP integration with MCPConfig:

from litestar_mcp import MCPConfig, LitestarMCP

config = MCPConfig(
    base_path="/api/mcp",         # Change base path (default: "/mcp")
    include_in_schema=True,       # Include MCP routes in OpenAPI (default: False)
    name="My API Server",         # Override server name (default: from OpenAPI)
)

app = Litestar(
    route_handlers=[...],
    plugins=[LitestarMCP(config)]
)

Resources vs Tools

Use Resources (mcp_resource) for:

  • Read-only data that AI models need to reference

  • Static information like schemas, documentation, configuration

  • Data that doesn't require parameters to retrieve

Use Tools (mcp_tool) for:

  • Operations that perform actions or mutations

  • Dynamic queries that need input parameters

  • Any operation that changes state

Testing Your Integration

Start your application and test the MCP endpoints:

# Start your app
uvicorn myapp:app --reload

# Discover the MCP server
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"}}}}'

# List available tools
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

# List available resources
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: resources/list" \
  -d '{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

You should see JSON-RPC responses describing your application's MCP capabilities.

Built-in Resources

The plugin automatically provides one built-in resource:

  • litestar://openapi - Your application's OpenAPI schema (always available)

Examples

See the examples/ directory for complete working examples:

  • docs/examples/hello_world/ - Simple integration with marked routes

Next Steps