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 or destructiveHint.
  • title at the top level and in annotations.
  • Per-tool scope, and per-caller visible (operator tools do not exist for others).
  • 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.1

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.1
File Size Uploaded Provenance Actions
litestar_mcp_server-0.0.1.tar.gz 15.6 kB Without provenance Details for litestar_mcp_server-0.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 29.0 kB

Release files / litestar_mcp_server-0.0.1.tar.gz

Download URL litestar_mcp_server-0.0.1.tar.gz
Size 15.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3169c5e1fa1a5f6b4ea147a188e1ee9d5b1353f94eec2fcdb05e5e362e87f75a
BLAKE2b-256 checksum
How to use checksums
94e0af32fdd9065cafb088ed50a7799cb79177caa0ad96f7fe71ad17836847ad
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.1-py3-none-any.whl

Download URL litestar_mcp_server-0.0.1-py3-none-any.whl
Size 13.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dea50068d0d6bfcb4d969c15ba4ac371da29b75f512e51117813472362b68074
BLAKE2b-256 checksum
How to use checksums
1514e95b2752bb8607f8c6de0dd56516dafe83b037343164914133abaf2461c2
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.1

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