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.

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)

MCPTaskConfig

class litestar_mcp.config.MCPTaskConfig

Bases: object

Configuration for the opt-in MCP Tasks extension.

__init__(store=None, default_ttl_ms=300000, max_ttl_ms=3600000, poll_interval_ms=1000)

MCPStdioContext

Runtime identity for standalone stdio transports. Its fields seed the synthesized dispatch scope so handlers, guards, and task execution read the usual request.user / request.scope["auth"] / session / state. See Standalone Application for the stdio walkthrough.

class litestar_mcp.app.MCPStdioContext

Bases: object

Runtime identity context for standalone MCP stdio transports.

Stdio has no HTTP header layer. Resolve credentials out-of-band in the host process, then pass the resulting identity values here so Litestar handlers and guards can read the usual scope["user"] / scope["auth"] / session / state fields.

__init__(client_id='stdio', owner_id=None, user=None, auth=None, session=None, state=None)

MCPResourceLink

class litestar_mcp.content.MCPResourceLink

Bases: object

A tool-result content block linking to a fetchable MCP resource.

to_content_block()

Return the MCP resource_link content block.

Return type:

dict[str, typing.Any]

__init__(name, uri, mime_type=None, description=None, title=None, size=None, annotations=None, meta=None)

MCPBlobResource

class litestar_mcp.content.MCPBlobResource

Bases: object

A tool-result embedded resource backed by bytes.

to_content_block(*, max_blob_bytes=None)

Return the MCP embedded resource content block.

Parameters:

max_blob_bytes (Optional[int]) -- Optional byte limit enforced before base64 encoding.

Return type:

dict[str, typing.Any]

__init__(uri, data, mime_type='application/octet-stream', annotations=None, meta=None)

MCPToolResult

class litestar_mcp.content.MCPToolResult

Bases: object

A complete MCP tool result with explicit content blocks.

to_result(*, max_blob_bytes=None)

Return the MCP tools/call result object.

Return type:

dict[str, typing.Any]

__init__(content, structured_content=<object object>, is_error=False, meta=None)

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, typing.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)