lime-agents-sdk — Cryptographic Passport for AI Agents (JWT + MCP OAuth)

lime-agents-sdk is the official Python agent SDK for LIME — an AI agent identity platform that issues cryptographic passports (signed JWTs) for autonomous workers. Agent runtimes authenticate with a single opaque X-Agent-Token, confirm site logins in one async call, and connect to MCP resource servers via MCP OAuth — without browsers, QR codes, or hand-rolled HTTP.

Use this package when you build agent workers (not site backends). Pair with lime-sites-sdk on the site side for login creation, SSE delivery, and passport verification.

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

Why lime-agents-sdk?

Two JWT flows (do not mix them)

LIME uses two different JWT artifacts. This SDK covers the agent worker side only.

The MCP JWT is signed with LIME Core keys (JWKS at GET /api/v1/core/.well-known/jwks.json). Default TTL is 300 seconds (5 minutes). The SDK caches it in your worker and performs lazy refresh on the next MCP call when the token is within ~30 seconds of expiry (mcp_token_refresh_skew, default 30) — there is no background refresh task. You send the JWT to remote MCP servers as Authorization: Bearer — not to the site backend. MCP JWTs are rejected on LIME HTTP APIs — only opaque X-Agent-Token works there.

Installation

pip install lime-agents-sdk

Latest from GitHub:

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

Requirements: Python 3.10+ · runtime deps: httpx, mcp

Quick start

Scenario A — Site login (headless agent authentication)

Story: A site backend starts a login request and hands request_id to your agent worker. The worker proves identity with PoW + approve. The site receives the signed agent passport JWT over SSE (handled by lime-sites-sdk). Your worker only runs the approve step.

import asyncio
import os

from lime_agents import LimeAgent, ApiError, PowTimeoutError

# LIME_AGENT_TOKEN=at_...  (from the LIME owner portal — server-side secret only)
REQUEST_ID = "lr_abc123"  # from your site backend / job queue


async def main() -> None:
    # One LimeAgent per worker process (reuse across jobs)
    agent = LimeAgent(agent_token=os.environ["LIME_AGENT_TOKEN"])

    try:
        result = await agent.login(REQUEST_ID)
        print(result.status)  # APPROVED after successful approve (site receives passport JWT via SSE separately)
        print(result.approved_agent_id)  # agent UUID from approve response (may be None on edge cases)
    except PowTimeoutError:
        print("PoW not solved in time — increase pow_timeout or retry")
    except ApiError as exc:
        print(f"[{exc.code}] {exc.message}")
    finally:
        await agent.aclose()


asyncio.run(main())

What login() does internally:

1. GET /api/v1/auth/requests/{request_id} — read PoW challenge (no auth)
2. Solve PoW in a thread pool (asyncio.to_thread)
3. POST /api/v1/modules/agent-login/requests/{request_id}/approve with X-Agent-Token + {"pow_nonce": "..."}

Site side (separate package): lime-sites-sdk → create_login_request() → SSE on_login → verify_passport() against Core JWKS.

Scenario B — MCP tools (MCP OAuth + streamable HTTP client)

Story: Your agent calls tools on an external MCP resource server. LIME issues a short-lived MCP JWT (~5 min) from your X-Agent-Token. The SDK attaches Authorization: Bearer, pools sessions per server URL, and retries on 401 after refresh.

import asyncio
import os

from lime_agents import LimeAgent, CallToolResult, Tool

MCP_ENDPOINT = "https://mcp.example.com/mcp"  # full streamable HTTP path, not just the host


async def main() -> None:
    async with LimeAgent(agent_token=os.environ["LIME_AGENT_TOKEN"]) as agent:
        # MCP JWT (~300s TTL) is fetched automatically on first list_tools / call_tool
        tools: list[Tool] = await agent.list_tools(MCP_ENDPOINT)
        print([t.name for t in tools])

        result: CallToolResult = await agent.call_tool(
            MCP_ENDPOINT,
            tools[0].name,
            {"text": "hello from LIME agent"},
        )
        if result.isError:
            print("tool error:", result.content)
        else:
            print(result.content)

        # Same agent, another MCP server — sessions cached per URL
        # await agent.call_tool("https://other-mcp.example.com/mcp", "get_weather", {"city": "Berlin"})


asyncio.run(main())

Credential lanes (never swap headers):

OAuth issuance: POST /api/v1/modules/oauth/token — header only, empty body (MCP OAuth ADR). Resource servers verify the JWT via Core JWKS — use lime-mcp-server-sdk on the server side.

Features

• One-call site login — await agent.login(request_id) wraps PoW fetch, solve, and approve with X-Agent-Token
• MCP OAuth built-in — issue, cache, and lazy-refresh 5-minute MCP JWTs on the next list_tools / call_tool when near expiry; no manual /oauth/token in app code
• Typed MCP client — list_tools, call_tool, read_resource, get_prompt, … with mcp.types models re-exported from lime_agents
• Automatic Proof-of-Work — SHA-256 solver with configurable pow_timeout and transient retry policy
• Production-ready LIME HTTP — httpx async client, exponential backoff on 408/429/5xx for platform calls (login, profile, OAuth issuance); MCP calls retry on 401 after token refresh
• Strict typing — ApprovalResult, AgentProfile, McpAccessToken, py.typed, mypy-clean public API

API reference (summary)

LimeAgent

Constructor highlights: agent_token / LIME_AGENT_TOKEN, base_url / LIME_API_BASE (default https://lime.pics/api/v1), timeout, max_retries, mcp_token_refresh_skew (default 30, lazy refresh window), serialize_mcp_per_url (default True).

Context manager: async with LimeAgent() as agent: calls aclose() on exit. For long-running workers, create one instance at startup and reuse it.

Environment variables

*Unless agent_token= is passed to the constructor.

Errors

All inherit from LimeError: AuthenticationError, PowTimeoutError, RateLimitError, ApiError, McpAuthenticationError, OAuthCapabilityError.

Related packages

Contributing

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

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

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

License

MIT — see LICENSE.