Agent programmatic access (MCP)

When to use this guide

• Your agent calls third-party MCP tools protected by LIME federation.
• You already have agent_token from the LIME portal.
• You need machine-only auth — no browser, no refresh tokens in a UI.

Before you start

1. agent_token (at_…) in the agent process environment (LIME_AGENT_TOKEN).
2. URL of the MCP resource server you are calling.
3. HTTP client that can set Authorization: Bearer headers.

Who does what

Your code (agent worker)

Only what you implement in this role. No PoW, SSE, or token logic from the partner side — that is in a separate guide.

1. 1

   Human owner → Agent runtime

   Store agent_token securely

   Create an agent in the LIME dashboard and copy agent_token once into LIME_AGENT_TOKEN. This is the long-lived secret for your worker — not the MCP JWT.

   Tip: Do not send MCP JWT to LIME business APIs as X-Agent-Token.

2. 2

   Agent runtime

   Request an MCP access token

   POST /api/v1/modules/oauth/token with header X-Agent-Token and empty body {}. Response data.access_token is a JWT for external MCP servers (aud=mcp).

   Your agent — get MCP JWT from LIME

   Copy

   # client_credentials — authenticate with X-Agent-Token (same opaque value as LIME APIs)
   curl -sS -X POST "https://lime.pics/api/v1/modules/oauth/token" \
     -H "Accept: application/json" \
     -H "X-Agent-Token: {your_agent_token}"

3. 3

   Agent runtime

   Call the MCP server with Bearer

   Set Authorization: Bearer <access_token> on MCP HTTP/SSE requests. Cache the token until near exp; on 401 from MCP RS, fetch a fresh token.

   Your agent — call MCP with Bearer

   Copy

   # pip install lime-agents-sdk
   # Agent process -> mint MCP JWT and send Bearer to your MCP server
   import asyncio
   from lime_agents import LimeAgent
   
   MCP_URL = "https://your-mcp-server.example/mcp"
   
   async def main() -> None:
       agent = LimeAgent()  # LIME_AGENT_TOKEN
       token = await agent.get_mcp_access_token()
       print(token[:24], "...")
       tools = await agent.list_tools(MCP_URL)  # uses MCP OAuth bearer automatically
       print(len(tools))
       await agent.aclose()
   
   asyncio.run(main())

4. 4

   Agent runtime

   Refresh on 401

   MCP JWTs are short-lived. On 401 from the resource server, POST /oauth/token again — no user interaction.

   Tip: Do not send MCP JWT to LIME business APIs as X-Agent-Token.

Related endpoints

• POSTOAuth token (client_credentials)
• GETOAuth Authorization Server metadata