lime-mcp-server-sdk — MCP OAuth JWT Verification (JWKS + RS256)

lime-mcp-server-sdk is the official Python server SDK for LIME MCP resource servers — verify MCP OAuth Bearer JWTs issued by LIME with JWKS + RS256, in-process caching, and zero-config defaults for production. Built for the Anthropic MCP ecosystem: agents authenticate with lime-agents-sdk; your server validates Authorization: Bearer tokens without hand-rolled PyJWT or metadata fetches on every request.

Use this package when you operate an external MCP resource server (FastMCP, custom HTTP /mcp, etc.). Not for site login passports (aud=lime-site-login) — use lime-sites-sdk on site backends.

📖 Python API (Read the Docs): lime-mcp-server-sdk.readthedocs.io
📖 Platform HTTP docs: lime.pics/docs#guide-mcpServerSdk
📦 This SDK: github.com/Mawyxx/lime-mcp-server-sdk
🌐 Platform: https://lime.pics

Why lime-mcp-server-sdk?

MCP OAuth JWT flow (this SDK)

Security: MCP JWTs are rejected on LIME HTTP APIs. This SDK is for your MCP server only.

Installation

pip install lime-mcp-server-sdk

Latest from GitHub:

pip install git+https://github.com/Mawyxx/lime-mcp-server-sdk.git

Requirements: Python 3.10+ · import: lime_mcp_server · deps: PyJWT, cryptography, httpx

Quick start

Scenario A — Sync verify (middleware / request handler)

Story: Extract the Bearer token from an incoming MCP request and verify it before executing tools.

from lime_mcp_server import TokenVerifier

# Required: pin the hostname this RS serves (or set LIME_EXPECTED_DOMAIN).
verifier = TokenVerifier(expected_domain="autonomad.ai")


def authorize_mcp_request(authorization_header: str | None) -> str | None:
    if not authorization_header:
        return None
    token = authorization_header.removeprefix("Bearer ").strip()
    if not token:
        return None
    result = verifier.verify(token)
    if not result.is_valid:
        # Missing/invalid/mismatched domain, aud, exp, signature, …
        return None
    return result.agent_id  # alias for claims["sub"] — agent UUID

MCP OAuth identity is claim sub (UUID). There is no separate agent_id JWT claim.

Scenario B — Async FastMCP + JWKS warmup (production)

Story: Warm JWKS at startup so verification stays fast; use async verify in your MCP auth hook.

from contextlib import asynccontextmanager

from fastmcp import FastMCP
from lime_mcp_server import TokenVerifier

verifier = TokenVerifier(expected_domain="autonomad.ai")
mcp = FastMCP("my-tools")


@asynccontextmanager
async def lifespan(app):
    if not verifier.warmup(raise_on_failure=True):
        raise RuntimeError("JWKS warmup failed")
    yield


async def verify_bearer(authorization: str) -> str | None:
    token = authorization.removeprefix("Bearer ").strip()
    if not token:
        return None
    result = await verifier.verify_async(token)
    if not result.is_valid:
        # log result.error in production (invalid aud, expired, bad signature, …)
        return None
    return result.agent_id


# Wire verify_bearer into your MCP server's auth layer.
# Monorepo reference: github.com/Mawyxx/Lime — scripts/verify/lime_mcp_rs_auth.py

JwksCache.fetch_count tracks successful metadata + JWKS network fetches (ops/debug).

Features

• TokenVerifier — MCP Bearer JWT validation with mandatory domain binding
• JWKS caching — TTL (default 3600s), kid-mismatch refresh, min refresh interval, stale fallback on network errors
• Fast path after warmup — verify uses cached keys; no metadata round-trip per request
• RS256 — PyJWT + cryptography; rejects forbidden site-login claims (user_id, request_id, …)
• verify_async() — non-blocking verify for ASGI / FastMCP
• warmup() — prefetch OAuth metadata (RFC 8414) + Core JWKS at startup
• Typed claims — McpAccessTokenClaims TypedDict, py.typed, mypy strict

API reference (summary)

TokenVerifier

TokenValidationResult

Environment variables

Domain errors (stable strings): Missing domain claim, Invalid domain claim, Domain mismatch.

Low-level helpers (tests / advanced): verify_mcp_access_token, normalize_mcp_domain, JwksCache, FORBIDDEN_MCP_CLAIMS.

Related packages

Contributing

Issues and pull requests: github.com/Mawyxx/lime-mcp-server-sdk

git clone https://github.com/Mawyxx/lime-mcp-server-sdk.git
cd lime-mcp-server-sdk
pip install -e ".[dev]"
ruff check src tests
mypy src/lime_mcp_server
pytest --cov=lime_mcp_server --cov-fail-under=100

CI runs on Python 3.10–3.13 with 100% line coverage on src/lime_mcp_server.

Live integration (optional):

LIME_MCP_SERVER_INTEGRATION=1 LIME_AGENT_TOKEN=at_... pytest tests/integration/ -v

License

MIT — see LICENSE.