Skip to main content

levante-mcp-sdk

OAuth provider for FastMCP servers deployed through Levante. It wraps your MCP server with a RemoteAuthProvider that validates Levante-issued tokens: it verifies the JWT locally against Levante's JWKS and confirms the grant/membership via Levante's introspection endpoint (/api/v1/mcp/introspect), with a short-lived in-memory cache.

Part of the sdks-levante repository. The TypeScript SDK (@levante/mcp-sdk) will live in packages/mcp-sdk/ of the same repo.

Install

pip install levante-mcp-sdk                 # núcleo (solo cliente de introspección)
pip install "levante-mcp-sdk[mcp]"          # + adaptador SDK oficial de Anthropic (mcp)
pip install "levante-mcp-sdk[fastmcp]"      # + adaptador FastMCP v2 (standalone)
pip install "levante-mcp-sdk[jwt]"          # + verificación JWT local

Requires Python >=3.11. The core depends only on httpx; each framework is an optional extra.

Uso con el SDK oficial (mcp.server.fastmcp.FastMCP)

from mcp.server.auth.settings import AuthSettings
from mcp.server.fastmcp import FastMCP
from pydantic import AnyHttpUrl
from levante_mcp_sdk import LevanteConfig
from levante_mcp_sdk.integrations.mcp import LevanteTokenVerifier

cfg = LevanteConfig.from_env()
mcp = FastMCP(
    "my-mcp",
    token_verifier=LevanteTokenVerifier(cfg),
    auth=AuthSettings(
        issuer_url=AnyHttpUrl(cfg.issuer),
        resource_server_url=AnyHttpUrl(cfg.resource),
    ),
)

Uso con FastMCP v2 (standalone)

from fastmcp import FastMCP
from levante_mcp_sdk import LevanteAuthProvider

mcp = FastMCP(name="my-mcp", auth=LevanteAuthProvider.from_env())

LevanteAuthProvider.from_env() reads its configuration from environment variables. When the MCP is deployed through Levante with a levante.yaml, these are injected automatically; you can also set them manually for local development.

Configuration (environment variables)

A typical deployment only needs two variables: LEVANTE_API_KEY and LEVANTE_MCP_RESOURCE. The issuer defaults to the production platform URL, and the introspection endpoint is derived from it ({issuer}/api/v1/mcp/introspect). The remaining variables exist as overrides.

Variable Required Description
LEVANTE_API_KEY yes A real Levante API key (lv_sk_*) the MCP uses to authenticate against /introspect.
LEVANTE_MCP_RESOURCE yes Resource/audience for this MCP — its own public URL.
LEVANTE_ISSUER no (defaults to https://platform.levanteapp.com) OAuth issuer / platform URL. Override for local/staging.
LEVANTE_INTROSPECT_URL no (derived from issuer) Override the introspection endpoint if it isn't {issuer}/api/v1/mcp/introspect.
LEVANTE_JWKS_URI no (only [fastmcp]/[jwt]) JWKS URI for local JWT verification. Not used by the introspection-only path.
LEVANTE_MCP_BASE_URL no (defaults to resource, only [fastmcp]) RemoteAuthProvider base URL.
LEVANTE_REQUIRE_ORG_MEMBERSHIP no (true) If true, denies tokens whose user is no longer an org member.
LEVANTE_FAIL_OPEN no (false) If true, allows requests when introspection is unreachable. Leave false in production.
LEVANTE_CACHE_TTL_SECONDS no (45) TTL of the in-memory introspection cache.

Minimal example:

LEVANTE_API_KEY=lv_sk_...
LEVANTE_MCP_RESOURCE=https://crm-conquer.example.run.app
# Optional override (defaults to https://platform.levanteapp.com):
# LEVANTE_ISSUER=https://staging.levanteapp.com

LEVANTE_API_KEY must be a real key registered in Levante; it cannot be an arbitrary string.

Future enhancement: LEVANTE_JWKS_URI could be auto-discovered via GET {issuer}/.well-known/oauth-authorization-server (which returns jwks_uri). This is deliberately not done at startup to avoid a network call; the introspection-only path needs no JWKS at all.

How it works

  1. JWT verification (local, offline): the bearer token is verified against LEVANTE_JWKS_URI with the expected issuer and audience.
  2. Introspection (cached): the token is checked against LEVANTE_INTROSPECT_URL, which returns whether the grant is active and whether the user is still an org member.
  3. Membership gate: with LEVANTE_REQUIRE_ORG_MEMBERSHIP=true, a non-member is denied even if the JWT is otherwise valid.
  4. On success, Levante identity is attached to the token claims: levante_user_id, levante_org_id, levante_mcp_slug.

Revocations may take up to LEVANTE_CACHE_TTL_SECONDS to take effect on each running instance.

Build

uv build
uv run twine check dist/*

Publishing to PyPI is automated via .github/workflows/publish-python.yml on GitHub release: it checks the tag matches pyproject.toml's version and runs ruff + mypy + pytest + twine before publishing.

License

MIT

Metadata

Release files for levante-mcp-sdk 0.3.0

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

Source distribution (sdist)

Source distribution for levante-mcp-sdk 0.3.0
File Size Uploaded Provenance Actions
levante_mcp_sdk-0.3.0.tar.gz 109.5 kB With provenance Details for levante_mcp_sdk-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for levante-mcp-sdk 0.3.0
File Interpreter ABI Platform Actions
levante_mcp_sdk-0.3.0-py3-none-any.whl Python 3 none any Details for levante_mcp_sdk-0.3.0-py3-none-any.whl

Total release size: 119.3 kB

Release files / levante_mcp_sdk-0.3.0.tar.gz

Download URL levante_mcp_sdk-0.3.0.tar.gz
Size 109.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ee64f73144e86327f4b5cdb4ce593af7fe4c77e48171b32e53f3374bafb045a5
BLAKE2b-256 checksum
How to use checksums
9e029e4bcb4669f34c11312800d54aa37df1ee94b8620a1df99c82783ae4404d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.

Transparency log

Release files / levante_mcp_sdk-0.3.0-py3-none-any.whl

Download URL levante_mcp_sdk-0.3.0-py3-none-any.whl
Size 9.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca4888194caea6b08aaf6bb4fb306a32c0c441ebb4abc371fece14d173e36975
BLAKE2b-256 checksum
How to use checksums
f3e240ccfff43645f92e0e825e9a2f747ce617d62fd298bdd878a3c529cfac2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.

Transparency log

Security for levante-mcp-sdk 0.3.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for levante_mcp_sdk-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.

Transparency log

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