Skip to main content

litestar-mcp-server

pypi python docs pipeline license

Documentation · API reference · Changelog · Issues · Source


Overview

A small MCP server for Litestar, with no SDK: tools with titles, read or destructive hints and scopes, over streamable HTTP.

Install

pip install litestar-mcp-server

Requires Python 3.12+.

Quickstart

from dataclasses import dataclass
from litestar import Litestar
from litestar.di import Provide
from litestar_mcp_server import (
    Arguments, Effect, McpConfig, McpServer, Tool, mcp_handlers, object_schema, string,
)

@dataclass(frozen=True, slots=True)
class Ctx:  # whatever your tools need about the caller
    user: str

async def add_note(ctx: Ctx, args: Arguments) -> str:
    return f"added {args.string('text')!r} for {ctx.user}"

server = McpServer(
    config=McpConfig(name="notes", version="0.1.0"),
    tools=[Tool(
        name="add_note", title="Add a note", effect=Effect.ADDITIVE,
        description="Add a note for the signed-in user.",
        input_schema=object_schema({"text": string("the note")}, required=("text",)),
        handler=add_note, scope="notes:write",
    )],
)

async def build_ctx() -> Ctx:  # a normal Litestar dependency
    return Ctx(user="demo")

app = Litestar(mcp_handlers(server, dependencies={"mcp_context": Provide(build_ctx)}))

Add guards=[...] for authentication and scopes=lambda request: ... so a tool's scope is checked. With litestar-oauth-server those are bearer_guard(...) and verified_token(request).scopes. See examples/basic.py.

Why litestar-mcp-server

An MCP endpoint for a SaaS product is a small thing: JSON-RPC over one POST route. The official SDK mounts a second web stack with its own auth and lifespan. This library is the small thing, as a normal Litestar route, so auth, dependency injection and logging are the ones your app already has. It also makes the connector-directory rules hard to forget: every tool needs a title of at most 64 characters and an effect, and the hints come from the effect.

Key features

  • Stateless streamable HTTP (2025-11-25, 2025-06-18, 2025-03-26): one JSON object per POST, 405 on GET.
  • Effect.READ, ADDITIVE or DESTRUCTIVE per tool, giving readOnlyHint: true, or readOnlyHint: false with destructiveHint.
  • title at the top level and in annotations.
  • Per-tool scope, and per-caller visible (operator tools do not exist for others).
  • A tool can return text, images, sound or any binary file (Blocks of TextContent, ImageContent, AudioContent, EmbeddedResource).
  • Failures reach the agent as readable results; unexpected errors never leak details.
  • A cap on result size, so a tool cannot dump a database.
  • Typed argument getters, tiny JSON Schema helpers, frozen dataclasses throughout.
  • No SDK and no pydantic: Litestar and msgspec only.

Not included: resources, prompts, SSE streams, sessions. Tools only.

Contributing

Developer setup, the dev loop, and the release process live in CONTRIBUTING.md. In short: uv sync && make install-hooks, then make check runs the same gate CI runs.

License

MIT © 2026 Jorge Cardona (see LICENSE).

Metadata

Release files for litestar-mcp-server 0.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for litestar-mcp-server 0.0.4
File Size Uploaded Provenance Actions
litestar_mcp_server-0.0.4.tar.gz 17.4 kB Without provenance Details for litestar_mcp_server-0.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for litestar-mcp-server 0.0.4
File Interpreter ABI Platform Actions
litestar_mcp_server-0.0.4-py3-none-any.whl Python 3 none any Details for litestar_mcp_server-0.0.4-py3-none-any.whl

Total release size: 31.7 kB

Release files / litestar_mcp_server-0.0.4.tar.gz

Download URL litestar_mcp_server-0.0.4.tar.gz
Size 17.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a4543540f50ea07ea04a4ecb9597c11e24cb5f457369c36de4f49f454b443d9b
BLAKE2b-256 checksum
How to use checksums
4373ac9e59c4f0b3996da54dd0dd274915cc03b84bcf47ca3a20edf14a48b6b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / litestar_mcp_server-0.0.4-py3-none-any.whl

Download URL litestar_mcp_server-0.0.4-py3-none-any.whl
Size 14.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8a8a7f968ed58bca6f2b52d2d99c55f4ff1650b743ca6886b8b917baacc983a9
BLAKE2b-256 checksum
How to use checksums
0458df439f7c7a6b86743a7e85e7bfcb647ad588c1d035294321e7dc8c2a01be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for litestar-mcp-server 0.0.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page