Config API#

This module contains the configuration classes for the Litestar MCP Plugin.

MCPConfig#

class litestar_mcp.config.MCPConfig[source]#

Bases: object

Configuration for the Litestar MCP Plugin.

The plugin uses Litestar's opt attribute to discover routes marked for MCP exposure. Server name and version are derived from the Litestar app's OpenAPI configuration.

base_path#: Base path for MCP API endpoints.

include_in_schema#: Whether to include MCP routes in OpenAPI schema generation.

name#: Optional override for server name. If not set, uses OpenAPI title.

guards#: Optional list of guards to protect MCP endpoints.

route_opt#: Optional route opt mapping applied to the mounted MCP router. Use this to declare an opt-based authentication policy for the MCP surface.

register_oauth_protected_resource#: Whether to register the RFC 9728 protected resource metadata route. Disable this when another plugin owns the application-root discovery path.

register_agent_card#: Whether to register the agent card discovery route.

allowed_origins#: Exact additional Origin values to accept. A missing Origin is valid; a present Origin must match the request origin or one of these configured values.

auth#: Optional OAuth 2.1 auth configuration. When set, bearer token validation is enforced on MCP endpoints.

tasks#: Optional task configuration or True to enable the default experimental in-memory task implementation.

list_page_size#: Page size for tools/list, resources/list, resources/templates/list, and prompts/list. The MCP spec lets servers choose the page size; clients cannot override it per request — they page through results via the opaque cursor / nextCursor round-trip. Must be a positive integer.

before_tool_call#: Optional callback invoked once before each tools/call dispatch, after the synthesized request is built and before guards run.

after_tool_call#: Optional callback invoked once after each tools/call dispatch with either the result or exception and elapsed dispatch duration in seconds.

max_blob_bytes#: Maximum raw byte length for base64-embedded MCP blobs. Set to None to disable the library cap.

property task_config: MCPTaskConfig | None#: Return the normalized task configuration, if task support is enabled.

__init__(base_path='/mcp', include_in_schema=False, name=None, instructions=None, guards=None, allowed_origins=None, include_operations=None, exclude_operations=None, include_tags=None, exclude_tags=None, auth=None, tasks=False, opt_keys=<factory>, cache_ttl_ms=0, cache_scope='private', subscription_max_streams=10000, subscription_keepalive_seconds=15.0, subscription_channels=None, list_page_size=100, before_tool_call=None, after_tool_call=None, max_blob_bytes=26214400, route_opt=None, register_oauth_protected_resource=True, register_agent_card=True)#

MCPOptKeys#

The opt-key names used to mark Litestar route handlers as MCP tools, resources, or prompts. Field defaults match the documented kwargs (mcp_tool, mcp_resource, mcp_prompt, mcp_prompt_description, mcp_prompt_title, mcp_prompt_arguments, mcp_prompt_icons, …); override the dataclass to remap a project to non-default opt keys.

class litestar_mcp.config.MCPOptKeys[source]#

Bases: object

Configurable names for the handler.opt keys read by the plugin.

Downstream apps can rename any key to avoid collisions with other plugins or app-specific conventions. All fields default to mcp_<purpose> and the pattern mirrors litestar.security.jwt.auth.JWTAuth.exclude_opt_key.

tool#: Opt key that marks a route handler as an MCP tool (handler.opt[tool] = "<tool-name>").

resource#: Opt key that marks a route handler as an MCP resource.

resource_uri#: Opt key that carries a concrete resource URI override.

resource_mime_type#: Opt key that carries the resource MIME type for list responses and binary resources/read fallbacks.

resource_template#: Opt key that carries an RFC 6570 Level 1 URI template for the resource (handler.opt[resource_template] = "app://workspaces/{workspace_id}/files/{file_id}").

required_client_capabilities#: Opt key declaring standard client capabilities required before a tool may be invoked.

task_input_before_start#: Opt key selecting a synchronous MRTR input round before task creation.

prompt#: Opt key that marks a route handler as an MCP prompt (handler.opt[prompt] = "<prompt-name>").

description#: Opt key overriding the tool description (handler.opt[description] = "LLM prose").

resource_description#: Opt key overriding the resource description. Kept distinct from description so a handler that exposes both a tool and a resource on the same route can target each.

prompt_description#: Opt key overriding the prompt description.

prompt_title#: Opt key overriding the prompt title.

prompt_arguments#: Opt key overriding the prompt argument list (a list[dict] matching the decorator's arguments= param).

prompt_icons#: Opt key overriding the prompt icons list (a list[dict] matching the decorator's icons= param).

agent_instructions#: Opt key for the ## Instructions section.

when_to_use#: Opt key for the ## When to use section.

returns#: Opt key for the ## Returns section.

for_field(field_name, kind)[source]#

Return the opt key for (field_name, kind).

The description field has kind-specific keys (description for tools, resource_description for resources, prompt_description for prompts) so a handler exposing multiple MCP roles on the same route can carry distinct override prose. All other fields are kind-agnostic.

Return type:: str

__init__(tool='mcp_tool', resource='mcp_resource', resource_uri='mcp_resource_uri', resource_mime_type='mcp_resource_mime_type', resource_template='mcp_resource_template', required_client_capabilities='mcp_required_client_capabilities', task_input_before_start='mcp_task_input_before_start', prompt='mcp_prompt', description='mcp_description', resource_description='mcp_resource_description', prompt_description='mcp_prompt_description', prompt_title='mcp_prompt_title', prompt_arguments='mcp_prompt_arguments', prompt_icons='mcp_prompt_icons', agent_instructions='mcp_agent_instructions', when_to_use='mcp_when_to_use', returns='mcp_returns')#