Types

This module contains type definitions for the Litestar MCP Plugin.

MCPConfig

class litestar_mcp.config.MCPConfig

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.

allowed_origins

List of allowed Origin header values. If empty/None, all origins are accepted. When set, requests with a non-matching Origin are rejected with 403.

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.

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, guards=None, allowed_origins=None, include_operations=None, exclude_operations=None, include_tags=None, exclude_tags=None, auth=None, tasks=False, opt_keys=<factory>, session_store=None, session_max_idle_seconds=3600.0, sse_max_streams=10000, sse_max_idle_seconds=3600.0, list_page_size=100, before_tool_call=None, after_tool_call=None, _session_manager=None)

MCPTaskConfig

class litestar_mcp.config.MCPTaskConfig

Bases: object

Configuration for experimental MCP task support.

__init__(enabled=True, list_enabled=True, cancel_enabled=True, default_ttl=300000, max_ttl=3600000, poll_interval=1000)

PromptRegistration

See also MCPOptKeys (documented under Config API) for the opt-key field names that drive handler-based prompt discovery.

class litestar_mcp.registry.PromptRegistration

Bases: object

A registered MCP prompt — either a standalone callable or a route handler.

Standalone prompts are plain (async) functions decorated with @mcp_prompt and passed to LitestarMCP(prompts=[...]).

Handler-based prompts are Litestar route handlers discovered via the mcp_prompt opt key, executed through the normal Litestar pipeline.

name

Unique prompt identifier used in prompts/get.

fn

The callable to invoke (standalone prompt functions).

handler

The Litestar route handler (handler-based prompts).

title

Optional human-readable display name.

description

Optional LLM-facing description.

arguments

Explicit argument definitions. When None, derived from the function signature (standalone prompts) or the handler's parsed signature (handler-based prompts), with DI- and framework-injected parameters filtered out.

icons

Optional list of icon objects for UI display.

get_arguments()

Return prompt arguments, introspecting from signature if needed.

When arguments was set explicitly, returns that list unchanged.

For standalone prompts, walks inspect.signature(fn).parameters (which transparently consults fn.__signature__ when present and otherwise builds from fn.__code__ / fn.__annotations__).

For handler-based prompts, walks the handler's parsed Litestar signature, filtering out DI dependencies and framework parameters (request, headers, …) so the advertised shape matches what an MCP caller is expected to supply.

Both paths enrich each entry with a Google-style docstring description when present.

Return type:

list[dict[str, Any]]

__init__(name, fn=None, handler=None, title=None, description=None, arguments=None, icons=None)

MCPAuthConfig

class litestar_mcp.auth.MCPAuthConfig

Bases: object

Metadata for the /.well-known/oauth-protected-resource manifest.

Authentication enforcement is handled by a Litestar authentication middleware (either your own AbstractAuthenticationMiddleware subclass or the built-in MCPAuthBackend). This struct only describes the auth surface to discovery clients.

issuer

OAuth 2.1 authorization server issuer URL (advertised to clients).

audience

Resource identifier used in the protected-resource manifest.

scopes

Mapping of scope name to human-readable description.

__init__(issuer=None, audience=None, scopes=None)

OIDCProviderConfig

class litestar_mcp.auth.OIDCProviderConfig

Bases: object

Configuration for validating bearer tokens against an OIDC/JWKS provider.

issuer

Expected iss claim and discovery base URL.

audience

Expected aud claim (string, list, or None to skip).

jwks_uri

Optional explicit JWKS endpoint (overrides discovery).

discovery_url

Optional override for the OpenID discovery document URL.

algorithms

Allowed JWS algorithms (default: ["RS256"]).

cache_ttl

JWKS / discovery document cache TTL in seconds.

clock_skew

Tolerance in seconds for exp / iat / nbf checks.

jwks_cache

Optional shared JWKSCache instance. When None the process-wide default cache is used.

__init__(issuer, audience=None, jwks_uri=None, discovery_url=None, algorithms=<factory>, cache_ttl=3600, clock_skew=30, jwks_cache=None)