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. Pass a target (URL or hostname). The SDK extracts the domain, posts JSON {"domain"} to LIME OAuth, caches JWTs per domain, pools sessions per URL, and on MCP 401 invalidates that domain only then retries once.

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)  # target=
        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

Comparison with Official MCP SDK

The official mcp package (PyPI: mcp) is the protocol SDK: transports, ClientSession, JSON-RPC types, server tooling (FastMCP), and generic OAuth helpers. lime-agents-sdk depends on it and wraps the client path for LIME agent workers — site login, LIME OAuth token issuance, session pooling, and typed facade methods.

Choose mcp alone when you need full control over transports, non-LIME OAuth (authorization code + PKCE, dynamic client registration), MCP servers, or stdio/SSE transports. Choose lime-agents-sdk when your worker already has a LIME X-Agent-Token and you want MCP tool calls with minimal boilerplate.

Side-by-side

Minimal example — list tools + call

Official mcp (streamable HTTP + Bearer you obtained yourself):

import asyncio

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://mcp.example.com/mcp"
ACCESS_TOKEN = "..."  # you fetch and refresh this


async def main() -> None:
    async with httpx.AsyncClient(
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
        timeout=30.0,
    ) as http:
        async with streamable_http_client(MCP_URL, http_client=http) as (read, write, _):
            async with ClientSession(read, write) as session:
                await session.initialize()
                tools = (await session.list_tools()).tools
                if tools:
                    await session.call_tool(tools[0].name, {"text": "hi"})


asyncio.run(main())

lime-agents-sdk (LIME OAuth + pool + facade):

import asyncio

from lime_agents import LimeAgent

MCP_URL = "https://mcp.example.com/mcp"


async def main() -> None:
    async with LimeAgent() as agent:  # LIME_AGENT_TOKEN from env
        tools = await agent.list_tools(MCP_URL)
        if tools:
            await agent.call_tool(MCP_URL, tools[0].name, {"text": "hi"})


asyncio.run(main())

When to use which SDK

Use mcp directly if you are:

• building an MCP server (FastMCP, stdio/SSE/streamable HTTP transports),
• implementing custom OAuth (authorization code + PKCE, dynamic client registration),
• integrating with an OAuth provider other than LIME.

Use lime-agents-sdk if you already have a LIME agent with X-Agent-Token and you want:

• ~5× less code for MCP tool calls (see examples above),
• automatic OAuth lifecycle — issue, cache, lazy refresh, and Bearer injection with no TokenStorage,
• session pooling and safe same-URL concurrency without writing lock/reconnect logic,
• 401 recovery and LIME platform retries built in,
• optional headless site login (login()) in the same client.

lime-agents-sdk does not replace mcp for server authors or non-LIME OAuth — it composes mcp for the LIME machine-token model.

Details: MCP OAuth & pool (source) · Read the Docs

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.

Versioning

See CHANGELOG.md. 1.0.0 introduces Zero-Touch target (breaking).