Connect Raken to Claude: Manage Safety Compliance and Site Resources

If you need to connect Raken to Claude to automate daily reporting, audit job site safety compliance, or track workforce and material logs, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Raken's REST API. You can either engineer and maintain this middleware 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 Raken to ChatGPT or explore our broader architectural overview on connecting Raken to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling construction management ecosystem like Raken presents distinct architectural challenges. You must handle OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Raken's domain-specific data constraints. Every time Raken updates an endpoint or deprecates a field, you are responsible for updating your server code, redeploying, and testing the integration.

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

The Engineering Reality of the Raken 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 over JSON-RPC, the reality of implementing it against specialized B2B APIs is painful. Raken is built to manage complex, multi-layered construction projects involving shifting labor classifications, material logs, and compliance observations. Its API reflects that complexity.

If you decide to build a custom Raken MCP server, here are the specific integration challenges you will face:

Strict 31-Day Date Range Caps Almost all list endpoints in Raken - such as list_all_raken_project_notes, list_all_raken_work_logs, and list_all_raken_observations - enforce a strict 31-day maximum range for date filters like changedSince/changedUntil or fromDate/toDate. If a user asks Claude to "summarize all safety observations for the last quarter," a naive MCP implementation will simply pass a 90-day range to the API, resulting in an immediate 400 Bad Request error. Your MCP server must enforce chunking logic or strictly guide the LLM via tool schemas to request data in rolling 30-day windows.

Nested Work Logs and Time Cards In Raken, labor tracking is not a flat structure. Time cards are inextricably linked to work logs, and the actual work descriptions live on the work log (workLogUuid), not the time card itself. An AI agent attempting to reconcile payroll or audit worker hours cannot just query a single time_cards endpoint and understand the context. It needs to coordinate requests between work logs and time cards, mapping the relationships accurately. A managed MCP server exposes these as distinct, documented tools, allowing the LLM to traverse the relational hierarchy programmatically.

Null-Driven PATCH Semantics Updating resources in Raken (projects, materials, shifts, members) relies on strict PATCH semantics where providing a null value actively removes the field, rather than just ignoring it. If an LLM hallucinates a payload and includes "address": null while trying to update a project status, it will wipe the project's address data entirely. Your MCP server must ensure that update schemas strictly forbid arbitrary null values unless explicitly requested by the user.

Generating a Raken MCP Server with Truto

Truto eliminates the need to build a custom Raken integration from scratch. Instead, Truto's architecture uses a dynamic, documentation-driven approach. It reads the Raken API resource definitions and automatically derives MCP-compatible tools. Only endpoints that have corresponding, high-quality documentation records are exposed as AI tools, ensuring the LLM receives accurate instructions, query parameters, and body schemas.

Each MCP server in Truto is scoped to a single integrated account (a specific tenant's connected Raken workspace). The server is accessed via a cryptographic token URL, meaning no additional authentication code is required on the client side.

You can generate this MCP server in two ways: via the Truto UI for rapid prototyping, or programmatically via the API for scalable deployments.

Method 1: Via the Truto UI

For IT admins or developers testing workflows, the UI provides an instant connection:

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Raken workspace.
2. Click on the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can optionally restrict the server to specific HTTP methods (e.g., read only) or specific tags (e.g., safety, labor).
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For platform engineers embedding AI capabilities into multi-tenant applications, you can provision Raken MCP servers dynamically. The Truto API validates the integrated account, provisions the server token in a globally distributed edge key-value store, and returns the endpoint URL.

Make a POST request to the /integrated-account/:id/mcp endpoint:

const response = await fetch('https://api.truto.one/integrated-account/<raken_account_id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TRUTO_API_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Raken Safety Audit Agent",
    config: {
      methods: ["read"], // Restrict the LLM to GET/LIST operations only
      tags: ["observations", "daily_reports"]
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); // The URL you will feed to Claude

Connecting the Raken MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your AI client. The process differs slightly depending on whether you are using a consumer chat interface or deploying a custom agent via a configuration file.

Method A: Via the Claude or ChatGPT UI

If you are using Claude's web or desktop interface (or ChatGPT), you can add the Truto URL as a custom connector:

For Claude:

1. Open Claude and navigate to Settings.
2. Select Integrations or Connectors.
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP URL into the Server URL field and click Add.

For ChatGPT:

1. Go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, add a new server.
4. Name it (e.g., "Raken Data") and paste the Truto MCP URL.
5. Save and return to the chat. The tools will immediately populate.

Method B: Via Manual Config File (Claude Desktop / Custom Agents)

For developers building local agents or configuring Claude Desktop directly, you configure the MCP server using Server-Sent Events (SSE). Add the Truto endpoint to your claude_desktop_config.json (or equivalent MCP configuration file):

{
  "mcpServers": {
    "raken-integration": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/<YOUR_TRUTO_TOKEN>"
      ]
    }
  }
}

When Claude initializes, it performs a JSON-RPC handshake with the Truto router, parsing all available Raken endpoints, extracting descriptions, and translating the YAML documentation records into standard JSON Schema arrays for tool calling.

Essential Raken Tools for Claude

The Truto MCP server exposes Raken's vast REST API as distinct, isolated tools. Each tool includes strict parameter definitions and automatically injected cursor descriptions for pagination handling.

Here are the highest-leverage hero tools for Raken automation:

list_all_raken_projects

Retrieves the foundational project data needed for almost all downstream API calls. This tool is heavily used by the LLM to look up the specific projectUuid required by labor and materials endpoints. It returns high-level data like start dates, end dates, statuses, and addresses.

"List all active projects in Raken and find the UUID for the 'Downtown Highrise' site."

list_all_raken_daily_reports

Fetches the core record of truth for a construction site. Daily reports contain vital metadata regarding who created the report, who signed it, and when it was completed. This is crucial for verifying compliance and identifying which sites are falling behind on documentation.

"Fetch all daily reports for the Downtown Highrise project from the last two weeks. Tell me if any reports from last week are missing signatures."

list_all_raken_work_logs

Retrieves work logs for a specific project within a defined date window (capped at 31 days). This tool returns total hours, work descriptions, and subcontractor information. Claude uses this to reconcile labor output and analyze on-site productivity.

"Pull the work logs for the electrical subcontractor on the Southside site for this week. What was their total logged hours?"

list_all_raken_observations

Accesses the safety and compliance observations recorded in the field. This tool allows filtering by category, priority, and status, making it incredibly powerful for safety managers auditing high-priority risks across multiple projects.

"Find all high-priority safety observations created across our projects in the last 14 days that are still marked as unresolved."

list_all_raken_material_logs

Tracks material usage and inventory deployment on a specific project. It returns quantities, associated cost codes, and delivery dates. This tool is vital for financial reconciliation and preventing budget overruns on raw materials.

"Retrieve the material logs for the West End Residential project for the month of October. Summarize the total quantity of concrete delivered."

create_a_raken_member

Automates the provisioning of new workers or administrative team members. It handles the assignment of roles (e.g., ROLE_WORKER) and binds them to specific projectUuids. For team members, supplying an email address triggers an automatic Raken invite.

"Create a new worker profile for John Doe, assign him the role of Worker, and add him to the Downtown Highrise project."

For the complete tool inventory, detailed JSON schemas, and parameter requirements, view the Raken integration page.

Workflows in Action

When you connect Raken to Claude, the LLM stops being a simple chatbot and becomes an autonomous site management assistant capable of executing multi-step API orchestrations.

Workflow 1: Safety and Compliance Audit

Persona: Safety Director / Project Manager

"Find all observations for the Downtown Highrise project from the last two weeks, check if any daily reports are missing signatures, and flag open safety issues."

Execution Steps:

1. list_all_raken_projects: Claude searches for "Downtown Highrise" to extract the projectUuid.
2. list_all_raken_observations: Claude queries observations using the projectUuid, strictly setting a date range within the last 14 days, and filters for open or high-priority items.
3. list_all_raken_daily_reports: Claude fetches the daily reports for the same date window and checks the signedBy and signedAt payload fields.

Result: The user receives a comprehensive audit report highlighting exact safety violations, detailing which subcontractors are involved, and explicitly listing which site managers failed to sign their daily reports.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Raken as Raken API

    Claude->>Truto: Call list_all_raken_projects
    Truto->>Raken: GET /projects
    Raken-->>Truto: Return project list
    Truto-->>Claude: Return project UUIDs
    Claude->>Truto: Call list_all_raken_observations (with UUID)
    Truto->>Raken: GET /observations?projectUuid=...
    Raken-->>Truto: Return safety observations
    Truto-->>Claude: Return safety findings
    Claude->>Truto: Call list_all_raken_daily_reports (with UUID)
    Truto->>Raken: GET /daily-reports?projectUuid=...
    Raken-->>Truto: Return report signature metadata
    Truto-->>Claude: Return signature gaps

Workflow 2: Workforce and Labor Reconciliation

Persona: Payroll Administrator / Field Admin

"Pull the work logs for the electrical team on the Southside site for this week. I need to know the total hours logged and cross-reference them with the time cards."

Execution Steps:

1. list_all_raken_projects: Claude identifies the projectUuid for "Southside site".
2. list_all_raken_work_logs: Claude queries the work logs for the current week, filtering for the electrical subcontractor to extract the workLogUuid.
3. list_all_raken_time_cards: Claude uses the parent projectUuid to fetch time cards, matching the output against the workLogUuid to verify that individual worker hours match the aggregated work log totals.

Result: The AI instantly reconciles the data, pointing out discrepancies (e.g., "The work log states 40 hours for electrical, but the individual time cards only sum to 32 hours."), saving payroll administrators hours of manual cross-referencing.

Handling Raken Rate Limits and Retries

When scaling Raken automation Claude, rate limits become a critical architectural factor. Truto does not retry, throttle, or apply backoff on rate limit errors.

If your AI agent makes too many concurrent requests to the Raken API (e.g., iterating heavily over hundreds of daily reports in a loop) and triggers an HTTP 429 Too Many Requests, Truto passes that exact error back to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset).

It is entirely the responsibility of the calling client or the LLM orchestration framework (like LangGraph or CrewAI) to catch these 429s, read the ratelimit-reset header, and implement exponential backoff.

Security and Access Control

Exposing B2B software to an autonomous AI agent requires stringent access control. A managed Truto MCP server allows you to tightly scope exactly what an agent can and cannot do in Raken.

• Method Filtering: By defining config.methods: ["read"] during server creation, you completely remove tools like update_a_raken_project_by_id or create_a_raken_member. The LLM physically cannot mutate data.
• Tag Filtering: You can restrict the server to specific operational domains. Setting tags: ["safety"] ensures the agent only sees observation and compliance endpoints, completely walling off financial or payroll data.
• Time-to-Live (TTL): Passing an ISO datetime to the expires_at field generates a temporary MCP server. When the timestamp hits, a distributed alarm service automatically cleans up the database record and purges the token from the edge key-value storage. The server self-destructs.
• API Token Auth: By enabling require_api_token_auth, possessing the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header, enforcing a strict secondary layer of identity verification.

Architecting for Scale

Connecting Raken to Claude using a managed MCP server removes the heavy lifting of OAuth token refreshes, pagination edge cases, and continuous API schema maintenance. By transforming Raken's documentation into dynamic, strict JSON schemas, Truto ensures that LLMs interact with construction data predictably and safely.

Instead of wasting engineering cycles updating custom middleware every time Raken modifies a payload, your team can focus on building higher-order, agentic workflows that actually improve job site safety and operational efficiency.