Configuration (MCPConfig)¶

The LitestarMCP plugin is configured through MCPConfig, along with companion dataclasses for custom handler.opt key names (MCPOptKeys), background task execution (MCPTaskConfig), and Agent Skills (MCPSkillsConfig).

Minimal Setup¶

When LitestarMCP() is registered without arguments, it uses the default MCPConfig, mounts the Streamable HTTP controller at /mcp, derives the server name and version from the application's OpenAPI configuration, and discovers all marked routes.

"""Snippet: minimal LitestarMCP setup. Referenced from docs/usage/configuration.rst."""

from litestar import Litestar

from litestar_mcp import LitestarMCP


def build() -> "Litestar":
    # start-example
    app = Litestar(plugins=[LitestarMCP()])
    # end-example
    return app

Custom Configuration¶

Override base_path, name, include_in_schema, filtering rules, or protocol extensions by passing an MCPConfig instance to LitestarMCP:

"""Snippet: custom MCPConfig. Referenced from docs/usage/configuration.rst."""

from litestar import Litestar

from litestar_mcp import LitestarMCP, MCPConfig


def build() -> "Litestar":
    # start-example
    config = MCPConfig(
        base_path="/api/mcp",
        name="My MCP Server",
        include_in_schema=True,
    )
    app = Litestar(plugins=[LitestarMCP(config)])
    # end-example
    return app

Standalone Prompts & Controllers¶

Standalone prompt functions decorated with @mcp_prompt can be passed to LitestarMCP(config, prompts=[...]), while class-based PromptController and SkillController types can either be included in app.route_handlers or registered via MCPConfig(prompt_controllers=[...], skill_controllers=[...]):

"""Snippet: register standalone prompts. Referenced from docs/usage/configuration.rst."""

from litestar import Litestar

from litestar_mcp import LitestarMCP, MCPConfig, mcp_prompt


@mcp_prompt(description="Greet a user by name.")
async def greet(name: "str") -> "str":
    """Build a greeting prompt.

    Args:
        name: The user's name to greet.
    """
    return f"Please greet {name} warmly."


def build() -> "Litestar":
    # start-example
    app = Litestar(
        route_handlers=[],
        plugins=[
            LitestarMCP(
                MCPConfig(name="prompt-demo"),
                prompts=[greet],
            ),
        ],
    )
    # end-example
    return app

Complete MCPConfig Reference¶

Operation and Tag Filtering Precedence¶

MCPConfig provides four filtering lists to narrow which marked routes are exposed on the MCP surface:

• exclude_tags: Denylist of Litestar route tags.
• include_tags: Allowlist of Litestar route tags.
• exclude_operations: Denylist of MCP primitive names (tool, resource, or prompt names).
• include_operations: Allowlist of MCP primitive names.

should_include_handler evaluates filters in strict order of precedence: exclude > include and tags > operations:

1. If exclude_tags is set and the handler carries any excluded tag, the handler is excluded.
2. If include_tags is set and the handler carries none of the included tags, the handler is excluded.
3. If exclude_operations is set and the primitive name is in exclude_operations, the handler is excluded.
4. If include_operations is set and the primitive name is not in include_operations, the handler is excluded.
5. Otherwise, the handler is included.

Filters apply identically to */list responses and direct invocation (tools/call, resources/read, prompts/get). Calling a filtered tool, resource, or prompt returns the same INVALID_PARAMS (-32602) not-found response as an unregistered name.

Enabling MCP Tasks (MCPTaskConfig)¶

Pass tasks=True or an MCPTaskConfig instance to enable the io.modelcontextprotocol/tasks extension:

"""Snippet: enabling the MCP Tasks extension."""

from litestar import Litestar

from litestar_mcp import LitestarMCP, MCPConfig


def build() -> "Litestar":
    # start-example
    app = Litestar(plugins=[LitestarMCP(MCPConfig(tasks=True))])
    # end-example
    return app

When litestar-queues QueuePlugin is registered on the same Litestar application, LitestarMCP automatically enables MCP Tasks and wires QueueTaskExecutor with zero configuration. Install the optional queues extra to distribute background MCP Tasks across litestar-queues workers:

uv add "litestar-mcp[queues]"

pip install "litestar-mcp[queues]"

pdm add "litestar-mcp[queues]"

poetry add "litestar-mcp[queues]"

See MCP Tasks and Distributed Task Queues for MCPTaskConfig options (store, default_ttl_ms, max_ttl_ms, poll_interval_ms, status_callback, executor) and worker rehydration details.

Enabling Agent Skills (MCPSkillsConfig)¶

Pass an MCPSkillsConfig instance to MCPConfig(skills=...) to advertise and serve Agent Skills (io.modelcontextprotocol/skills, SEP-2640) from filesystem directories (paths) or dynamic request-aware SkillSource providers (sources):

"""Snippet: serving Agent Skills over MCP from a directory."""

from pathlib import Path

from litestar import Litestar

from litestar_mcp import LitestarMCP, MCPConfig, MCPSkillsConfig

SKILLS_ROOT = Path(__file__).resolve().parents[1] / "skills"


def build() -> "Litestar":
    # start-example
    config = MCPConfig(skills=MCPSkillsConfig(paths=[SKILLS_ROOT]))
    app = Litestar(plugins=[LitestarMCP(config)])
    # end-example
    return app

See Agent Skills (SEP-2640) for directory layout rules, startup validation, wire methods, and dynamic SkillSource composition.

Tool-Call Lifecycle Callbacks¶

Configure before_tool_call and after_tool_call on MCPConfig to run audit logging, custom metrics, or structured tracing around every tools/call invocation independently of route ownership layers:

"""Snippet: MCP tool-call callback configuration."""

from typing import Any

from litestar import Litestar, Request

from litestar_mcp import LitestarMCP, MCPConfig


# start-example
async def after_tool_call(
    tool_name: "str",
    arguments: "dict[str, Any]",
    request: "Request[Any, Any, Any]",
    *,
    result: "Any",
    exception: "Exception | None",
    duration: "float",
) -> "None":
    request.app.logger.info(
        "mcp tool=%s duration=%0.4f failed=%s",
        tool_name,
        duration,
        exception is not None,
    )


config = MCPConfig(after_tool_call=after_tool_call)
# end-example


def build() -> "Litestar":
    app = Litestar(route_handlers=[], plugins=[LitestarMCP(config)])
    return app

• before_tool_call(tool_name, arguments, request, /): Invoked once per tools/call after the synthetic internal HTTP Request is constructed and before Litestar guards execute. Receives a shallow copy of arguments.
• after_tool_call(tool_name, arguments, request, /, *, result, exception, duration): Invoked in a finally block after every tools/call—including normal completions, guard rejections, validation errors, and unhandled exceptions—with the elapsed duration in seconds.
• Any exception raised inside before_tool_call or after_tool_call is logged and swallowed so observability hooks never corrupt tool execution results.

Opaque-Cursor List Pagination¶

All six catalog enumeration methods—tools/list, resources/list, resources/templates/list, prompts/list, skills/list, and resources/directory/read—implement the MCP opaque-cursor pagination contract:

1. Each method accepts an optional string params.cursor.
2. The server slices the sorted catalog using MCPConfig.list_page_size (default 100, must be a positive integer).
3. When additional items remain after the current slice, the response includes "nextCursor": "<opaque-base64-token>".
4. Clients pass nextCursor back as params.cursor on the next request until nextCursor is omitted.
5. Supplying a non-string, malformed, or negative-offset cursor raises JSON-RPC INVALID_PARAMS (-32602).