Connect Lumos to Claude: Automate Access Reviews & Identity Logs

If you need to connect Lumos to Claude to automate access reviews, audit identity logs, and manage app permissions, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Lumos's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Lumos to ChatGPT or explore our broader architectural overview on connecting Lumos to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling enterprise identity governance platform like Lumos is an engineering challenge. You have to handle API key management, map massive JSON schemas to MCP tool definitions, and deal with Lumos's specific asynchronous job handling. Every time Lumos updates an endpoint or deprecates a field, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Lumos, connect it natively to Claude, and execute complex governance workflows using natural language.

The Engineering Reality of the Lumos API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against vendor APIs is painful. You are not just integrating a generic database - you are integrating an identity governance platform with highly specific data models.

If you decide to build a custom MCP server for Lumos, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Job Polling Lumos handles heavy operations asynchronously. If you create an account upload using POST /apps/{app_id}/accounts/upload, the API does not return the completed state. It returns a job ID. You must then poll a separate endpoint to get the job state. If you expose these raw parameters to Claude without context, the model will frequently assume the job is finished immediately or hallucinate the final state. Truto's standardized schemas help LLMs understand exactly what data is returned, but your agent prompt must explicitly instruct the LLM to poll job status endpoints when dealing with asynchronous tasks.

Complex Access Review State Machines Creating an access review in Lumos is not a single-step CRUD operation. When you create an access review with specific apps, the review starts in an IN_PREPARATION state while Lumos takes account and entitlement snapshots. It only transitions to IN_PROGRESS once snapshotting completes. If your LLM tries to immediately modify scope filters on an IN_PROGRESS or COMPLETED review, the Lumos API will reject the request. Your MCP server must accurately expose these state constraints to the LLM to prevent persistent tool call errors.

Strict Scope Filtering Validation When adding apps to access reviews, Lumos requires highly specific scope filters. You cannot just pass arbitrary strings. You must first query the list_all_lumos_access_reviews_scope_options endpoint, find the exact matching option groups, and copy the item's value and name verbatim into your payload. Models are notoriously bad at adhering to strict enum-style object validation unless the JSON schema explicitly demands it. Truto parses Lumos's documentation dynamically to generate accurate query and body schemas, ensuring Claude knows exactly what shape the payload must take.

Rate Limits and 429 Handling Lumos enforces API rate limits to protect its infrastructure. A critical architectural note: Truto does not retry, throttle, or apply exponential backoff on rate limit errors. When the upstream Lumos API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to the caller. Truto normalizes upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - in this case, the Claude client or your custom AI agent framework - is entirely responsible for detecting the 429, reading the headers, and executing the retry and backoff logic.

How to Generate a Lumos MCP Server with Truto

Truto dynamically generates MCP tools based on the resources and documentation available for the Lumos integration. Because the server is hosted at the edge, it requires zero local configuration beyond passing the URL to Claude.

You can create an MCP server for Lumos in two ways: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal IT teams and admins looking to spin up an agent quickly.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Lumos account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read-only methods or specific tags).
6. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4...

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can generate MCP servers programmatically. Make an authenticated POST request to the Truto API:

curl -X POST "https://api.truto.one/integrated-account/{integrated_account_id}/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lumos Compliance Agent",
    "config": {
      "methods": ["read", "write"],
      "require_api_token_auth": false
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API securely hashes the token, stores it in edge storage, and returns a ready-to-use JSON-RPC endpoint.

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you need to connect it to Claude. You can do this through the Claude Desktop UI or by manually editing the configuration file.

Method A: Via the Claude UI (Claude Desktop)

1. Open Claude Desktop.
2. Navigate to Settings -> Integrations.
3. Click Add MCP Server (or Custom Connector).
4. Paste the Truto MCP URL into the Server URL field.
5. Click Add.

Claude will immediately ping the server, complete the handshake protocol, and list the available Lumos tools.

Method B: Via Manual Configuration File

For developers managing their environments via config files, you can add the server directly to Claude's configuration file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

Add the following JSON snippet to your configuration, using the @modelcontextprotocol/server-sse package to handle the Server-Sent Events (SSE) transport layer:

{
  "mcpServers": {
    "lumos_prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_GENERATED_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The model now has direct, authenticated access to your Lumos environment.

Hero Tools for Lumos

Truto automatically maps Lumos's API endpoints to fully documented, schema-validated MCP tools. Here are the most critical operations for automating identity governance and access reviews.

List Identity Events

Retrieves a cursor-paginated collection of user identity events in Lumos, allowing your agent to audit changed fields (like title, team, or status changes) across the organization.

"Audit our identity logs. Find all identity events from the last 7 days where the changed_field was 'team' and summarize the user transitions."

Create an Access Review

Initiates a new access review campaign. If apps are provided, the review starts in IN_PREPARATION while snapshots are taken. Without apps, it starts directly in IN_PROGRESS.

"Start a new quarterly access review campaign named 'Q3 Engineering Access Audit'. Do not attach any apps yet, just initialize the campaign."

List All Tasks

Fetches Lumos tasks visible to the user. Admins can pass show_all_tasks=true to list tasks across the entire domain, filtering by category (like APPROVAL) or status.

"Pull all pending APPROVAL tasks assigned to the security group. Format them into a table showing the task ID, product area, and target user."

Create an AppStore Access Request

Allows the agent to generate an access request for a specific permission within the Lumos AppStore on behalf of a user.

"Create an access request for user ID 10293 for the GitHub 'Developer' role. Add a note stating this is required for the upcoming Q4 infrastructure migration."

List All Apps

Retrieves all apps in your Lumos company catalog. Essential for discovery workflows where the agent needs to find app IDs before managing settings or access requests.

"Search the Lumos catalog for 'Datadog'. I need the exact app ID and any custom attributes associated with the integration."

List All Activity Logs

Retrieves granular security and activity logs in Lumos. This is critical for investigating specific event hashes, actor behaviors, or system outcomes within a specific time window.

"Pull the activity logs for the past 24 hours. Filter for any events where the outcome was 'failed' and list the actors involved."

For the complete inventory of available Lumos tools, including payload structures, JSON schemas, and nested field definitions, view the Lumos integration page.

Workflows in Action

Connecting Claude to Lumos via MCP transforms static chat interfaces into autonomous security and IT operations engines. Here is how specific personas use these capabilities.

Workflow 1: JIT Access Provisioning (IT Helpdesk)

An employee messages an IT admin via Slack asking for temporary access to AWS for a database migration. Instead of manually navigating Lumos, the admin prompts Claude to handle the request.

"Create an access request for Sarah Jenkins for the AWS 'DB Admin' role. Set it to expire in 48 hours and note that it is for the Q2 database migration."

Execution Steps:

1. Claude calls list_all_lumos_users with a search_term of "Sarah Jenkins" to retrieve her exact Lumos user_id.
2. Claude calls list_all_lumos_apps searching for "AWS" to retrieve the correct app_id.
3. Claude calls create_a_lumos_appstore_access_request using the resolved user_id and app_id, passing the expiration and notes parameters.

Result: The LLM resolves the human-readable names to strict API UUIDs and successfully submits the access request, returning the generated request ID to the admin.

sequenceDiagram
    participant Admin as IT Admin
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Lumos as Lumos API

    Admin->>Claude: "Request AWS DB Admin for Sarah Jenkins for 48h"
    Claude->>MCP: Call list_all_lumos_users (Sarah Jenkins)
    MCP->>Lumos: GET /users?search_term=Sarah... 
    Lumos-->>MCP: Returns user_id
    MCP-->>Claude: user_id: 8f72a...
    Claude->>MCP: Call create_a_lumos_appstore_access_request
    MCP->>Lumos: POST /access-requests
    Lumos-->>MCP: 201 Created (Request ID: 99x2)
    MCP-->>Claude: Success payload
    Claude-->>Admin: "Access request 99x2 created. Expires in 48h."

Workflow 2: Automated SOC2 Compliance Auditing (Security Analyst)

A security analyst needs to verify that all access reviews for engineering tools were completed on time and check if there are any lingering pending approvals.

"Get the status of all access reviews created this quarter. Then, pull all pending approval tasks across the domain and summarize who the bottlenecks are."

Execution Steps:

1. Claude calls list_all_lumos_access_reviews to retrieve the list of recent campaigns and their status.
2. Claude calls list_all_lumos_tasks passing show_all_tasks=true, task_category=APPROVAL, and status=PENDING.
3. Claude analyzes the returned task array, groups the objects by the assignees field, and generates a summary report.

Result: The analyst receives a concise, formatted report of review statuses and a list of specific managers who need to be pinged to complete their pending approvals.

Security and Access Control

Giving an AI agent access to your identity governance platform requires strict security boundaries. Truto provides several mechanisms to lock down your Lumos MCP servers:

• Method Filtering: Restrict an MCP server to read-only operations. By setting methods: ["read"] during creation, the server will only expose list and get tools, completely preventing the LLM from mutating access policies or creating requests.
• Tag Filtering: Limit the LLM's scope to specific functional areas. If you tag Lumos resources in Truto (e.g., tagging access_reviews with "compliance"), you can generate an MCP server that only exposes compliance-related endpoints.
• Require API Token Auth: By default, the MCP token URL acts as the sole authentication factor. For higher security, set require_api_token_auth: true. The client connecting to the server must then also pass a valid Truto API token via a Bearer header.
• Expiring Servers: Use the expires_at field to create temporary, short-lived MCP servers. Once the timestamp is reached, Truto automatically deletes the edge storage records and database entries, instantly revoking the LLM's access to Lumos.

Streamlining Identity Governance with Agents

Integrating Lumos via a custom MCP server requires constant maintenance of complex schemas, asynchronous job handlers, and pagination logic. By using a managed infrastructure layer, you offload the boilerplate and guarantee your agents always have up-to-date, schema-validated access to your identity data.

Instead of wasting engineering cycles reading API documentation and updating JSON-RPC schemas, your team can focus on building intelligent security workflows, automated audits, and faster JIT access systems.