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,ADDITIVEorDESTRUCTIVEper tool, givingreadOnlyHintordestructiveHint.titleat the top level and inannotations.- Per-tool
scope, and per-callervisible(operator tools do not exist for others). - A tool can return text, images, sound or any binary file (
BlocksofTextContent,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.
Links
- Documentation: https://cardona-oss.gitlab.io/litestar-mcp-server/
- Source: https://gitlab.com/cardona-oss/litestar-mcp-server
- Issues: https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues
- PyPI: https://pypi.org/project/litestar-mcp-server/
- Changelog: CHANGELOG.md
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.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| litestar_mcp_server-0.0.3.tar.gz | 17.2 kB | Without provenance | Details for litestar_mcp_server-0.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| litestar_mcp_server-0.0.3-py3-none-any.whl | Python 3 | none | any | Details for litestar_mcp_server-0.0.3-py3-none-any.whl |
Total release size: 31.4 kB
Release files / litestar_mcp_server-0.0.3.tar.gz
| Download URL | litestar_mcp_server-0.0.3.tar.gz |
|---|---|
| Size | 17.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3087bf4f69cd743891f668c31b5ff378ee3edb48020c5d8d9a458dced959d74c
|
|
BLAKE2b-256 checksum How to use checksums |
7b833785e6cbbaf301bb0417676181420874cb1a3e078e071415fa7f9b0e5733
|
| 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.3-py3-none-any.whl
| Download URL | litestar_mcp_server-0.0.3-py3-none-any.whl |
|---|---|
| Size | 14.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c553726f4cc1ca38d1be825bf53bc76c607fb392d5804f6e0b8b90dd18b951f7
|
|
BLAKE2b-256 checksum How to use checksums |
387d6941829a6c3599eab58be64c669592b7fdda58f5c32b7f03ed6acaca2449
|
| 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.3
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.