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.2

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.2
File Size Uploaded Provenance Actions
litestar_mcp_server-0.0.2.tar.gz 16.3 kB Without provenance Details for litestar_mcp_server-0.0.2.tar.gz

Built distribution (wheel)

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

Total release size: 30.1 kB

Release files / litestar_mcp_server-0.0.2.tar.gz

Download URL litestar_mcp_server-0.0.2.tar.gz
Size 16.3 kB
Tags Source
SHA-256 checksum
How to use checksums
2e4ce8c283b63927da6dc18f365bc18d09b64d7f09a9f01adad856b45fb1ab40
BLAKE2b-256 checksum
How to use checksums
25826fdfea9ea2309e4d13bc27844b2f0e2556846f450f9002c03fea471b14f6
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.2-py3-none-any.whl

Download URL litestar_mcp_server-0.0.2-py3-none-any.whl
Size 13.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6b83bf4bb5110bbdae3169271244e0618ed0e20bf8079e0860c5bc8ab7bf32af
BLAKE2b-256 checksum
How to use checksums
6f110d23559d7495dabbbbbb8441cae7e81945353d7fc32af9ee297448477a8b
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.2

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