Primitives, Controllers & Skills API¶

API reference for MCP decorators (@mcp_tool, @mcp_resource, @mcp_prompt), description validation (validate_tool_descriptions), class-based PromptController and SkillController routers, Agent Skills (SkillSource, FilesystemSkillSource, Skill, SkillFile, SkillCatalog, SkillIntegrityError), structured content return types, the Registry, and MCPHandlerService request context helpers.

For usage guides, see Marking Routes & Decorators, Tools & Annotations, Resources & URI Templates, Prompts & PromptController, and Agent Skills (SEP-2640).

Route & Function Decorators¶

mcp_tool ¶

mcp_tool(
    name=None,
    *,
    description=None,
    agent_instructions=None,
    when_to_use=None,
    returns=None,
    input_schema=None,
    output_schema=None,
    annotations=None,
    read_only=None,
    scopes=None,
    task=None,
    task_support=None,
    task_input_before_start=False,
    queue=None,
)

Decorator to mark a route handler as an MCP tool.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	The name of the MCP tool. Defaults to the function name.	`None`
`description`	`str \| None`	LLM-facing description. Overrides `fn.__doc__`. Ignored when `handler.opt["mcp_description"]` is set (opt wins). Empty string is treated as absent so the docstring fallback still applies.	`None`
`agent_instructions`	`str \| None`	Mandatory-context block rendered in the `## Instructions` section of the combined description.	`None`
`when_to_use`	`str \| None`	Optional structured hint for LLM clients — rendered as the `## When to use` section.	`None`
`returns`	`str \| None`	Optional return-shape hint — rendered as the `## Returns` section.	`None`
`input_schema`	`dict[str, Any] \| None`	Optional explicit JSON Schema for the tool input.	`None`
`output_schema`	`dict[str, Any] \| None`	Optional JSON Schema for the tool's structured output.	`None`
`annotations`	`dict[str, Any] \| None`	Optional metadata annotations (audience, priority, etc.).	`None`
`read_only`	`bool \| None`	Optional shorthand setting `annotations["readOnlyHint"]`.	`None`
`scopes`	`list[str] \| None`	Optional list of OAuth scopes advertised as discovery metadata (surfaced under `tools[].annotations.scopes` in `tools/list`). Scopes are not enforced inline — attach a Litestar `Guard` to the route / router / controller for authorization.	`None`
`task`	`str \| bool \| None`	Preferred task mode parameter. Accepts `"optional"` (or `True`), `"required"`, or `"sync"` / `"disabled"` / `"inline"` / `"forbidden"` / `False`.	`None`
`task_support`	`str \| bool \| None`	Optional task support mode alias for `task`.	`None`
`task_input_before_start`	`bool`	Execute the first call synchronously so an MRTR input-required result can be completed before creating the task on the retry.	`False`
`queue`	`str \| bool \| None`	Optional target `litestar-queues` queue name for this tool, or `False` / `"in_process"` to force in-process background task execution.	`None`

Returns:

Type	Description
`Callable[[F], F]`	Decorator function that adds MCP metadata to the handler.

Example

Pass MCP metadata straight through to the route decorator — Litestar funnels unknown kwargs into handler.opt, so no double-decoration is required:

@get("/users", mcp_tool="user_manager", mcp_description="List every user.")
async def get_users() -> list[dict]:
    return [{"id": 1, "name": "Alice"}]

The decorator form is retained for parity; it carries the same metadata to the registry and is useful when you want to stamp an explicit input_schema / output_schema, annotations, scopes, or task/MRTR policy without mixing more keys into handler.opt.

mcp_resource ¶

mcp_resource(
    name=None,
    *,
    uri_template=None,
    mime_type=None,
    description=None,
    agent_instructions=None,
    when_to_use=None,
    returns=None,
)

Decorator to mark a route handler as an MCP resource.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	The name of the MCP resource. Defaults to the function name.	`None`
`uri_template`	`str \| None`	Optional RFC 6570 Level 1 URI template (e.g. `"app://workspaces/{workspace_id}/files/{file_id}"`). Concrete URIs matching the template dispatch to this handler with extracted variables passed as kwargs.	`None`
`mime_type`	`str \| None`	Optional resource MIME type advertised in list responses and used as a fallback for resource reads.	`None`
`description`	`str \| None`	LLM-facing description. Overrides `fn.__doc__`.	`None`
`agent_instructions`	`str \| None`	Mandatory-context block rendered in the `## Instructions` section.	`None`
`when_to_use`	`str \| None`	Optional structured hint rendered as the `## When to use` section.	`None`
`returns`	`str \| None`	Optional return-shape hint rendered as the `## Returns` section.	`None`

Returns:

Type	Description
`Callable[[F], F]`	Decorator function that adds MCP metadata to the handler.

Example

Pass MCP metadata straight through to the route decorator — Litestar funnels unknown kwargs into handler.opt:

@get("/config", mcp_resource="app_config")
async def get_config() -> dict:
    return {"debug": True}

@get(
    "/workspaces/{workspace_id:str}/files/{file_id:str}",
    mcp_resource="workspace_file",
    mcp_resource_template="app://workspaces/{workspace_id}/files/{file_id}",
)
async def read_workspace_file(workspace_id: str, file_id: str) -> dict:
    ...

The decorator form is retained for parity; it carries the same metadata to the registry.

mcp_prompt ¶

mcp_prompt(
    name=None, *, title=None, description=None, arguments=None, icons=None
)

Decorator to mark a callable as an MCP prompt template.

Prompt functions take keyword arguments matching the declared prompt arguments and return prompt messages. The return value is normalised to a list of PromptMessage dicts:

str → single {"role": "user", "content": {"type": "text", "text": ...}}
dict → treated as a single message and wrapped in a list
list[dict] → used directly
Any other type → str(result) wrapped as a single user text message

Both sync and async callables are supported.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	Unique identifier for the prompt (used in `prompts/get`).	`None`
`title`	`str \| None`	Optional human-readable display name for UI clients.	`None`
`description`	`str \| None`	LLM-facing description. When omitted, `fn.__doc__` is used as the fallback during registration.	`None`
`arguments`	`list[dict[str, Any]] \| None`	Optional explicit argument definitions — each entry is a dict with `name` (required), and optional `title`, `description`, and `required` keys. `title` is the human-readable display name from the MCP `BaseMetadata` mixin (a hint for UI clients; not used for matching). When omitted, the argument list is derived automatically from the decorated function's signature and Google-style docstring — note that signature introspection cannot infer `title`, so set it explicitly when needed.	`None`
`icons`	`list[dict[str, Any]] \| None`	Optional list of icon objects for UI display. Each entry is a dict with `src` (URL), `mimeType`, and optionally `sizes` per the MCP spec.	`None`

Returns:

Type	Description
`Callable[[F], F]`	Decorator function that adds MCP metadata to the callable.

Example

Standalone prompt function registered via LitestarMCP(prompts=[summarize_text]):

@mcp_prompt(name="summarize", description="Summarise a document.")
async def summarize_text(text: str, style: str = "concise") -> str:
    return f"Please summarise the following in a {style} style:\\n\\n{text}"

validate_tool_descriptions ¶

validate_tool_descriptions(
    tools,
    *,
    max_tool_description_length=1000,
    max_param_description_length=750,
    max_output_field_description_length=300,
)

Validate tool, input parameter, and output schema field description lengths.

Class-Based Controllers¶

PromptController ¶

Bases: Controller

Litestar controller whose @prompt methods are served as MCP prompts.

Attributes:

Name	Type	Description
`prefix`	`str \| None`	Optional namespace prepended to prompt names as /.
`instructions`	`str \| None`	Text prepended to the first user message of every prompt result.

qualify_prompt_name ¶

qualify_prompt_name(name)

Return the registered prompt name for name under this controller's prefix.

prompt ¶

prompt(name=None, *, title=None, description=None, arguments=None, icons=None)

Mark a controller method as an MCP prompt served through the controller's guards and dependencies.

SkillController ¶

Bases: PromptController

Prompt controller that also serves @tool methods as MCP tools and exposes them to agents.

Attributes:

Name	Type	Description
`name`	`str`	Skill identifier, also the default prompt prefix and A2A skill id.
`description`	`str`	Skill description for A2A cards.
`tags`	`Sequence[str] \| None`	Optional categorization tags for discovery.
`examples`	`tuple[str, ...]`	Example requests for A2A cards.

qualify_prompt_name ¶

qualify_prompt_name(name)

Namespace prompts under prefix, falling back to name.

get_tools ¶

get_tools()

Return the controller's tools bound to this instance.

get_instructions ¶

get_instructions()

Return the skill instructions or an empty string.

to_agent_skill ¶

to_agent_skill()

Project the controller metadata to an A2A AgentSkill dictionary.

Agent Skills (`io.modelcontextprotocol/skills`)¶

SkillSource ¶

Bases: Protocol

Async, request-aware source of Agent Skills.

list_skills ¶

list_skills(request)

Every skill the caller of request may see; names unique within the result.

get_skill ¶

get_skill(request, name)

The skill named name iff list_skills(request) would include it.

read_file ¶

read_file(request, skill, file)

Bytes of file (of skill as returned by this source in the same request).

FilesystemSkillSource ¶

Eager, digest-locked filesystem source of Agent Skills.

Attributes:

Name	Type	Description
`paths`	`tuple[Path, ...]`	Configured root directories searched by this source.
`skills`	`tuple[Skill, ...]`	Loaded skills sorted by `name`.

list_skills ¶

list_skills(request)

Return all filesystem skills sorted by name.

get_skill ¶

get_skill(request, name)

Return the filesystem skill named name, or None.

read_file ¶

read_file(request, skill, file)

Read file.path from disk asynchronously.

Skill ¶

One skill loaded from a skill directory or constructed dynamically.

Parameters:

Name	Type	Description	Default
`name`	`str`	Skill identifier, matching the `name` frontmatter key.	required
`description`	`str`	Human-readable summary from frontmatter.	required
`uri`	`str`	Canonical `skill://<name>/SKILL.md` URI.	required
`frontmatter`	`dict[str, Any]`	Full parsed YAML frontmatter mapping, preserved verbatim.	required
`files`	`tuple[SkillFile, ...]`	Every file belonging to the skill, sorted by `relative_path`.	required

Attributes:

Name	Type	Description
`name`	`str`	Skill identifier, matching the `name` frontmatter key.
`description`	`str`	Human-readable summary from frontmatter.
`uri`	`str`	Canonical `skill://<name>/SKILL.md` URI.
`frontmatter`	`dict[str, Any]`	Full parsed YAML frontmatter mapping, preserved verbatim.
`files`	`tuple[SkillFile, ...]`	Every file belonging to the skill, sorted by `relative_path`.

from_content ¶

from_content(skill_md, files=None)

Construct an in-memory Skill from SKILL.md content and optional auxiliary files.

build ¶

build(name, description, body='', *, metadata=None, files=None)

Build an in-memory Skill by rendering YAML-safe frontmatter around body.

get_file ¶

get_file(relative_path)

Return the SkillFile at relative_path or None if absent.

list_directory ¶

list_directory(relative_path='')

List files and immediate subdirectories under relative_path ("" for skill root).

to_entry ¶

to_entry()

Return the skills/list / skills/get entry for this skill.

to_resources ¶

to_resources()

Return the resources/list entries for every file in this skill.

SkillFile ¶

One file inside a skill folder or dynamic skill manifest.

Parameters:

Name	Type	Description	Default
`relative_path`	`str`	Forward-slash path relative to the skill root.	required
`path`	`Path \| None`	Absolute filesystem path on disk, or `None` for in-memory/lazy files.	required
`uri`	`str`	Canonical `skill://<name>/<relative_path>` URI.	required
`mime_type`	`str`	Resolved MIME type (`application/octet-stream` fallback).	required
`size`	`int`	Byte length recorded in the skill manifest.	required
`digest`	`str`	`sha256:<hex>` digest recorded in the skill manifest.	required
`content`	`bytes \| None`	Optional inline byte payload served without calling `source.read_file`.	`None`

Attributes:

Name	Type	Description
`relative_path`	`str`	Forward-slash path relative to the skill root.
`path`	`Path \| None`	Absolute filesystem path on disk, or `None` for in-memory/lazy files.
`uri`	`str`	Canonical `skill://<name>/<relative_path>` URI.
`mime_type`	`str`	Resolved MIME type (`application/octet-stream` fallback).
`size`	`int`	Byte length recorded in the skill manifest.
`digest`	`str`	`sha256:<hex>` digest recorded in the skill manifest.
`content`	`bytes \| None`	Optional inline byte payload served without calling `source.read_file`.

from_content ¶

from_content(skill_name, relative_path, content)

Construct an in-memory SkillFile with manifest metadata computed from content.

to_manifest_entry ¶

to_manifest_entry()

Return the skills/list / skills/get resource manifest entry.

to_resource ¶

to_resource(skill)

Return the resources/list entry for this file within skill.

SkillCatalog ¶

Request-aware composition of SkillSource instances.

Attributes:

Name	Type	Description
`sources`	`tuple[SkillSource, ...]`	Tuple of composed `SkillSource` instances in priority order.

from_config ¶

from_config(config)

Build a catalog from config (paths first as FilesystemSkillSource, then sources).

list_skills ¶

list_skills(request)

Return every skill visible to request across all sources, deduplicated and sorted by name.

get_skill ¶

get_skill(request, name)

Return the skill named name visible to request, or None.

get ¶

get(request, uri)

Return the skill whose canonical skill://<name>/SKILL.md URI equals uri, else None.

get_file ¶

get_file(request, uri)

Resolve uri to a SkillFileMatch visible to request, or None.

list_directory ¶

list_directory(request, uri)

List direct file and directory children under uri, or None if not a visible directory.

resource_entries ¶

resource_entries(request)

Return resources/list entries for every file in every visible skill.

read_file ¶

read_file(request, match)

Read match.file (inline or via match.source.read_file) and verify size and digest.

SkillIntegrityError ¶

Bases: Exception

Raised when a skill file's on-disk or source-returned bytes no longer match its manifest digest.

Content Blocks & Return Helpers¶

MCPToolResult ¶

A complete MCP tool result with explicit content blocks.

Parameters:

Name	Type	Description	Default
`content`	`Any`	One or more content blocks (or values normalized into content blocks).	required
`structured_content`	`Any`	Optional structured JSON payload emitted under `structuredContent`.	`<object object at 0x7f0a4019ce20>`
`is_error`	`bool`	Whether the tool result represents an execution error (`isError`).	`False`
`meta`	`dict[str, Any] \| None`	Optional `_meta` dictionary emitted on the tool result.	`None`

Attributes:

Name	Type	Description
`content`	`Any`	One or more content blocks (or values normalized into content blocks).
`structured_content`	`Any`	Optional structured JSON payload emitted under `structuredContent`.
`is_error`	`bool`	Whether the tool result represents an execution error (`isError`).
`meta`	`dict[str, Any] \| None`	Optional `_meta` dictionary emitted on the tool result.

to_result ¶

to_result(*, max_blob_bytes=None)

Return the MCP tools/call result object.

MCPResourceLink ¶

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

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical resource name.	required
`uri`	`str`	Target MCP resource URI.	required
`mime_type`	`str \| None`	Optional MIME type of the linked resource.	`None`
`description`	`str \| None`	Optional human- or LLM-readable description of the linked resource.	`None`
`title`	`str \| None`	Optional display title for the resource link.	`None`
`size`	`int \| None`	Optional size of the linked resource in bytes.	`None`
`annotations`	`dict[str, Any] \| None`	Optional MCP content annotations attached to the resource link.	`None`
`meta`	`dict[str, Any] \| None`	Optional `_meta` dictionary emitted on the content block.	`None`

Attributes:

Name	Type	Description
`name`	`str`	Logical resource name.
`uri`	`str`	Target MCP resource URI.
`mime_type`	`str \| None`	Optional MIME type of the linked resource.
`description`	`str \| None`	Optional human- or LLM-readable description of the linked resource.
`title`	`str \| None`	Optional display title for the resource link.
`size`	`int \| None`	Optional size of the linked resource in bytes.
`annotations`	`dict[str, Any] \| None`	Optional MCP content annotations attached to the resource link.
`meta`	`dict[str, Any] \| None`	Optional `_meta` dictionary emitted on the content block.

to_content_block ¶

to_content_block()

Return the MCP resource_link content block.

MCPBlobResource ¶

A tool-result embedded resource backed by bytes.

Parameters:

Name	Type	Description	Default
`uri`	`str`	Canonical URI identifying the embedded binary resource.	required
`data`	`bytes \| bytearray \| memoryview`	Raw binary payload encoded as base64 in the MCP content block.	required
`mime_type`	`str`	MIME type of the binary payload.	`'application/octet-stream'`
`annotations`	`dict[str, Any] \| None`	Optional MCP annotations attached to the embedded resource.	`None`
`meta`	`dict[str, Any] \| None`	Optional `_meta` dictionary emitted on the embedded resource.	`None`

Attributes:

Name	Type	Description
`uri`	`str`	Canonical URI identifying the embedded binary resource.
`data`	`bytes \| bytearray \| memoryview`	Raw binary payload encoded as base64 in the MCP content block.
`mime_type`	`str`	MIME type of the binary payload.
`annotations`	`dict[str, Any] \| None`	Optional MCP annotations attached to the embedded resource.
`meta`	`dict[str, Any] \| None`	Optional `_meta` dictionary emitted on the embedded resource.

to_content_block ¶

to_content_block(*, max_blob_bytes=None)

Return the MCP embedded resource content block.

Parameters:

Name	Type	Description	Default
`max_blob_bytes`	`int \| None`	Optional byte limit enforced before base64 encoding.	`None`

MCPInputRequiredResult ¶

Typed MCP multi-round-trip input request result.

request_state crosses an untrusted client boundary. Applications MUST authenticate and integrity-protect it (for example with AEAD or an HMAC) before placing authorization-sensitive state in this field.

Parameters:

Name	Type	Description	Default
`input_requests`	`dict[str, dict[str, Any]] \| None`	Map of input request identifiers to client input request descriptors.	`None`
`request_state`	`str \| None`	Opaque integrity-protected state token round-tripped through the client.	`None`

Attributes:

Name	Type	Description
`input_requests`	`dict[str, dict[str, Any]] \| None`	Map of input request identifiers to client input request descriptors.
`request_state`	`str \| None`	Opaque integrity-protected state token round-tripped through the client.

to_result ¶

to_result()

Return the MCP wire result.

PromptMessage ¶

An MCP PromptMessage with a user or assistant role and one content block.

Parameters:

Name	Type	Description	Default
`role`	`Literal['user', 'assistant']`	Message speaker role (`"user"` or `"assistant"`).	required
`content`	`dict[str, Any]`	MCP content block dictionary for the prompt message.	required

Attributes:

Name	Type	Description
`role`	`Literal['user', 'assistant']`	Message speaker role (`"user"` or `"assistant"`).
`content`	`dict[str, Any]`	MCP content block dictionary for the prompt message.

user ¶

user(text)

Create a user text message.

assistant ¶

assistant(text)

Create an assistant text message.

to_mcp_dict ¶

to_mcp_dict()

Return the wire dictionary.

Discovery Registry¶

Registry ¶

Central registry for MCP tools, resources, and prompts.

This class decouples metadata storage and discovery from the route handlers themselves, avoiding issues with slots or object mutation.

Note

Tools and resources are stored as bare BaseRouteHandler values because every entry has a single underlying handler. Prompts use PromptRegistration instead — a prompt may originate from either a standalone @mcp_prompt callable or a route handler, so the dataclass carries the fn | handler union plus the per-prompt metadata (title, description, arguments, icons) that can't live on a bare callable.

Attributes:

Name	Type	Description
`subscription_manager`	`SubscriptionManager`	Return the configured subscription manager.
`tools`	`dict[str, BaseRouteHandler]`	Get registered tools.
`resources`	`dict[str, BaseRouteHandler]`	Get registered resources.
`templates`	`dict[str, ResourceTemplate]`	Get registered resource templates, keyed by resource name.
`prompts`	`dict[str, PromptRegistration]`	Get registered prompts.

register_change_callback ¶

register_change_callback(callback)

Register a callback to be invoked when the registry changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[], None]`	The callback function.	required

unregister_change_callback ¶

unregister_change_callback(callback)

Unregister a change callback.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[], None]`	The callback function to remove.	required

set_subscription_manager ¶

set_subscription_manager(manager)

Set the subscription manager for notifications.

register_tool ¶

register_tool(name, handler)

Register a tool.

Parameters:

Name	Type	Description	Default
`name`	`str`	The tool name.	required
`handler`	`BaseRouteHandler`	The route handler.	required

register_resource ¶

register_resource(name, handler)

Register a resource.

Parameters:

Name	Type	Description	Default
`name`	`str`	The resource name.	required
`handler`	`BaseRouteHandler`	The route handler.	required

register_resource_template ¶

register_resource_template(name, handler, template)

Register an RFC 6570 Level 1 URI template for a resource.

Parameters:

Name	Type	Description	Default
`name`	`str`	The resource name (same key as `register_resource`).	required
`handler`	`BaseRouteHandler`	The route handler bound to the template.	required
`template`	`str`	The URI template string. Validated at registration; invalid templates raise `ValueError`.	required

register_prompt ¶

register_prompt(
    name, fn, *, title=None, description=None, arguments=None, icons=None
)

Register a standalone prompt function.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique prompt identifier.	required
`fn`	`Callable[..., Any]`	The callable to invoke on `prompts/get`.	required
`title`	`str \| None`	Optional human-readable display name.	`None`
`description`	`str \| None`	Optional description. Falls back to `fn.__doc__`.	`None`
`arguments`	`list[dict[str, Any]] \| None`	Explicit argument definitions. When `None`, derived from the function signature.	`None`
`icons`	`list[dict[str, Any]] \| None`	Optional list of icon objects for UI display.	`None`

register_prompt_handler ¶

register_prompt_handler(
    name,
    handler,
    *,
    title=None,
    description=None,
    arguments=None,
    icons=None,
    instructions=None,
)

Register a route-handler-based prompt.

Storage only — runtime dispatch and the messages-passthrough vs. normalize-on-return decision live in litestar_mcp.mcp.routes.handle_prompts_get. This function captures the handler reference plus any explicit overrides so the registry can render prompts/list entries without executing the handler.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique prompt identifier.	required
`handler`	`BaseRouteHandler`	The Litestar route handler.	required
`title`	`str \| None`	Optional human-readable display name.	`None`
`description`	`str \| None`	Optional description.	`None`
`arguments`	`list[dict[str, Any]] \| None`	Explicit argument definitions. When `None`, arguments are introspected from the handler's parsed handler signature at `prompts/list` render time (DI- and framework-injected parameters filtered out). Pass `[]` to advertise no arguments explicitly.	`None`
`icons`	`list[dict[str, Any]] \| None`	Optional list of icon objects for UI display.	`None`
`instructions`	`str \| None`	Grounding instructions prepended to prompt output.	`None`

publish_notification ¶

publish_notification(method, params)

Publish a JSON-RPC 2.0 notification to connected clients.

Parameters:

Name	Type	Description	Default
`method`	`str`	The notification method (e.g., 'notifications/resources/updated').	required
`params`	`dict[str, Any]`	The notification parameters.	required

notify_resource_updated ¶

notify_resource_updated(uri)

Notify clients that a resource has been updated.

Parameters:

Name	Type	Description	Default
`uri`	`str`	The URI of the updated resource.	required

notify_tools_list_changed ¶

notify_tools_list_changed()

Notify clients that the tool list has changed.

notify_prompts_list_changed ¶

notify_prompts_list_changed()

Notify clients that the prompt list has changed.

ResourceTemplate ¶

A declared RFC 6570 Level 1 URI template bound to a resource handler.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical resource name.	required
`template`	`str`	RFC 6570 Level 1 URI template string.	required
`handler`	`BaseRouteHandler`	Litestar route handler bound to the URI template.	required

Attributes:

Name	Type	Description
`name`	`str`	Logical resource name.
`template`	`str`	RFC 6570 Level 1 URI template string.
`handler`	`BaseRouteHandler`	Litestar route handler bound to the URI template.

PromptRegistration ¶

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.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique prompt identifier used in `prompts/get`.	required
`fn`	`Callable[..., Any] \| None`	The callable to invoke for standalone prompt functions.	`None`
`handler`	`BaseRouteHandler \| None`	The Litestar route handler for handler-based prompts.	`None`
`title`	`str \| None`	Optional human-readable display name.	`None`
`description`	`str \| None`	Optional LLM-facing description.	`None`
`arguments`	`list[dict[str, Any]] \| None`	Explicit argument definitions, or `None` to derive from the function or handler signature.	`None`
`icons`	`list[dict[str, Any]] \| None`	Optional list of icon objects for UI display.	`None`
`instructions`	`str \| None`	Optional grounding instructions prepended to rendered prompt messages.	`None`

Attributes:

Name	Type	Description
`name`	`str`	Unique prompt identifier used in `prompts/get`.
`fn`	`Callable[..., Any] \| None`	The callable to invoke for standalone prompt functions.
`handler`	`BaseRouteHandler \| None`	The Litestar route handler for handler-based prompts.
`title`	`str \| None`	Optional human-readable display name.
`description`	`str \| None`	Optional LLM-facing description.
`arguments`	`list[dict[str, Any]] \| None`	Explicit argument definitions, or `None` to derive from the function or handler signature.
`icons`	`list[dict[str, Any]] \| None`	Optional list of icon objects for UI display.
`instructions`	`str \| None`	Optional grounding instructions prepended to rendered prompt messages.

get_arguments ¶

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.

Handler Service & Request Context¶

MCPHandlerService ¶

Service class encapsulating the MCP JSON-RPC business logic.

run_task_attempt ¶

run_task_attempt(call, user)

Execute one task-augmented tool call attempt in a background worker.

server_discover ¶

server_discover(params, context)

Describe the modern protocol versions, capabilities, and extensions.

initialize ¶

initialize(params, context)

Negotiate MCP protocol version and return server capabilities and info.

ping ¶

ping(params, context)

Acknowledge an MCP ping health check.

notifications_initialized ¶

notifications_initialized(params, context)

Acknowledge an initialized notification.

build_tool_entries ¶

build_tool_entries()

Build the unpaginated list of advertised MCP tool specifications.

tools_list ¶

tools_list(params, context)

Return a paginated list of registered MCP tools matching active filters.

tools_call ¶

tools_call(params, context)

Invoke a registered MCP tool synchronously or promote it to a background task.

resources_list ¶

resources_list(params, context)

Return a paginated list of concrete MCP resources and visible skill files.

resources_templates_list ¶

resources_templates_list(params, context)

Return a paginated list of registered RFC 6570 resource URI templates.

resources_read ¶

resources_read(params, context)

Read the contents of a concrete resource, skill file, or URI-template resource.

skills_list ¶

skills_list(params, context)

List every skill in the catalog, one atomic entry per skill.

skills_get ¶

skills_get(params, context)

Return one skill's manifest by its skill:// URI.

resources_directory_read ¶

resources_directory_read(params, context)

List the files and subdirectories directly under a skill:// directory URI.

completion_complete ¶

completion_complete(params, context)

Return argument auto-completion suggestions for prompts or resource templates.

prompts_list ¶

prompts_list(params, context)

Return a paginated list of registered MCP prompts matching active filters.

prompts_get ¶

prompts_get(params, context)

Render a registered MCP prompt with caller-supplied string arguments.

tasks_get ¶

tasks_get(params, context)

Retrieve the current status and result of a background MCP task.

tasks_update ¶

tasks_update(params, context)

Supply interactive input responses to a task awaiting client input and resume execution.

tasks_cancel ¶

tasks_cancel(params, context)

Request cancellation of an in-flight MCP background task.

MCPRequestContext ¶

Request context threaded through tool and task execution.

Authentication lives in Litestar middleware; request.user and request.auth are the per-request source of truth for tool handlers. This struct only carries the scope identifiers used by MCP itself (client id, task-owner id, and the live request handle).

Parameters:

Name	Type	Description	Default
`client_id`	`str`	Identifier of the connected MCP client or transport session.	required
`owner_id`	`str \| None`	Authenticated task-owner identifier, or `None` for anonymous callers.	required
`request`	`Request[Any, Any, Any] \| None`	Inbound Litestar HTTP `Request`, or `None` for stdio/background invocations.	`None`
`protocol_version`	`str`	Negotiated MCP protocol version string for the current request.	`'2026-07-28'`
`client_capabilities`	`dict[str, Any] \| None`	Client capabilities dictionary advertised during initialization or via request `_meta`.	`None`
`client_info`	`dict[str, Any] \| None`	Client implementation metadata (`name`, `version`) supplied by the caller.	`None`
`input_responses`	`dict[str, Any] \| None`	Multi-round-trip input responses supplied by the client for an interactive tool call.	`None`
`request_state`	`str \| None`	Opaque round-tripped state token accompanying `input_responses`.	`None`
`progress_token`	`str \| int \| None`	Optional progress correlation token extracted from request `_meta.progressToken`.	`None`
`progress_reporter`	`Callable[[dict[str, Any]], Awaitable[None]] \| None`	Optional async callback used to emit `notifications/progress` frames for this request.	`None`

Attributes:

Name	Type	Description
`client_id`	`str`	Identifier of the connected MCP client or transport session.
`owner_id`	`str \| None`	Authenticated task-owner identifier, or `None` for anonymous callers.
`request`	`Request[Any, Any, Any] \| None`	Inbound Litestar HTTP `Request`, or `None` for stdio/background invocations.
`protocol_version`	`str`	Negotiated MCP protocol version string for the current request.
`client_capabilities`	`dict[str, Any] \| None`	Client capabilities dictionary advertised during initialization or via request `_meta`.
`client_info`	`dict[str, Any] \| None`	Client implementation metadata (`name`, `version`) supplied by the caller.
`input_responses`	`dict[str, Any] \| None`	Multi-round-trip input responses supplied by the client for an interactive tool call.
`request_state`	`str \| None`	Opaque round-tripped state token accompanying `input_responses`.
`progress_token`	`str \| int \| None`	Optional progress correlation token extracted from request `_meta.progressToken`.
`progress_reporter`	`Callable[[dict[str, Any]], Awaitable[None]] \| None`	Optional async callback used to emit `notifications/progress` frames for this request.

report_progress ¶

report_progress(progress, total=None, message=None)

Report progress correlated to the request's supplied progress token.

get_mcp_request_context ¶

get_mcp_request_context()

Return the context for the currently executing MCP handler.

Primitives, Controllers & Skills API¶

Route & Function Decorators¶

mcp_tool ¶

mcp_resource ¶

mcp_prompt ¶

validate_tool_descriptions ¶

Class-Based Controllers¶

PromptController ¶

qualify_prompt_name ¶

prompt ¶

SkillController ¶

qualify_prompt_name ¶

get_tools ¶

get_instructions ¶

to_agent_skill ¶

Agent Skills (io.modelcontextprotocol/skills)¶

SkillSource ¶

list_skills ¶

get_skill ¶

read_file ¶

FilesystemSkillSource ¶

list_skills ¶

get_skill ¶

read_file ¶

Skill ¶

from_content ¶

build ¶

get_file ¶

list_directory ¶

to_entry ¶

to_resources ¶

SkillFile ¶

from_content ¶

to_manifest_entry ¶

to_resource ¶

SkillCatalog ¶

from_config ¶

list_skills ¶

get_skill ¶

get ¶

get_file ¶

list_directory ¶

resource_entries ¶

read_file ¶

SkillIntegrityError ¶

Content Blocks & Return Helpers¶

MCPToolResult ¶

to_result ¶

MCPResourceLink ¶

to_content_block ¶

MCPBlobResource ¶

to_content_block ¶

MCPInputRequiredResult ¶

to_result ¶

PromptMessage ¶

user ¶

assistant ¶

to_mcp_dict ¶

Discovery Registry¶

Registry ¶

register_change_callback ¶

unregister_change_callback ¶

set_subscription_manager ¶

register_tool ¶

register_resource ¶

register_resource_template ¶

register_prompt ¶

register_prompt_handler ¶

publish_notification ¶

notify_resource_updated ¶

notify_tools_list_changed ¶

notify_prompts_list_changed ¶

ResourceTemplate ¶

PromptRegistration ¶

get_arguments ¶

Handler Service & Request Context¶

MCPHandlerService ¶

run_task_attempt ¶

server_discover ¶

initialize ¶

Agent Skills (`io.modelcontextprotocol/skills`)¶