lime-mcp-server-sdk

Verify LIME MCP passport JWTs on your resource server — local JWKS, no LIME hop on the hot path.

from lime_mcp_server import TokenVerifier

verifier = TokenVerifier(expected_domain="tools.example.com")

result = verifier.verify(bearer_token)  # Authorization: Bearer <jwt>
if result.is_valid:
    agent_id = result.agent_id  # claims["sub"] — then YOUR ACL

What the SDK handles: JWKS fetch · cache · RS256 · aud=mcp · issuer · domain pin · async verify.

Docs: Read the Docs · lime.pics/docs · Platform

Installation

pip install lime-mcp-server-sdk
# pin the hostname this RS serves:
export LIME_EXPECTED_DOMAIN=tools.example.com

Requirements: Python 3.10+ · PyJWT · cryptography · httpx
Config: expected_domain= or LIME_EXPECTED_DOMAIN. Zero JWKS boilerplate — not zero config.

Quick start (canonical) — verify Bearer

from lime_mcp_server import TokenVerifier

verifier = TokenVerifier(expected_domain="tools.example.com")


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:
        return None
    return result.agent_id  # then apply YOUR tool ACL

Copy-paste: examples/verify-middleware/.

Agent side issues the JWT with lime-agents-sdk (list_tools / call_tool). This package only verifies.

Mental model

TokenVerifier
├── verify(token) / verify_async(token)   ← primary
├── warmup()                              ← production startup
└── cache / refresh / invalidate          ← advanced

Never send X-Agent-Token to the MCP server. Agents send only Authorization: Bearer <passport>.

Production — async + JWKS warmup

from contextlib import asynccontextmanager

from lime_mcp_server import TokenVerifier

verifier = TokenVerifier(expected_domain="tools.example.com")


@asynccontextmanager
async def lifespan(app):
    verifier.warmup(raise_on_failure=True)  # raises on JWKS failure
    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:
        return None
    return result.agent_id

Example: examples/async-warmup/.

How the flow fits together

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

API surface (summary)

Result: is_valid, agent_id (sub), domain, error, valid_claims.

Env: LIME_EXPECTED_DOMAIN (or kwarg), LIME_BASE_URL (default https://lime.pics), cache/leeway knobs — see RTD.

Full reference: Read the Docs — API.

Related packages

Examples

Contributing

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

License

MIT — see LICENSE.