Connect Rippling to Claude: Manage Custom Objects and Records

If you need to connect Rippling to Claude to automate custom object management, worker provisioning, or complex HR workflows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Rippling'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 Rippling to ChatGPT or explore our broader architectural overview on connecting Rippling to AI Agents.

Giving a Large Language Model (LLM) read and write access to an enterprise HRIS and IT management platform like Rippling is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Rippling's specific data structures and rate limits. Every time Rippling updates an endpoint or adds a new custom object, 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 Rippling, connect it natively to Claude, and execute complex operations against custom objects and worker records using natural language.

The Engineering Reality of the Rippling 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 Rippling's APIs is painful. You are not just integrating a flat directory list - you are dealing with deeply nested graph permissions, dynamic schemas, and strict data governance.

If you decide to build a custom Rippling Claude integration, you own the entire API lifecycle. Here are the specific challenges you will face:

Dynamic Custom Object Routing Rippling relies heavily on Custom Objects to model company-specific data (e.g., parking spot allocations, custom hardware requests, external contractor tracking). These are not static endpoints. The API requires a dynamic custom_object_api_name parameter in the path for every operation. Hardcoding static MCP tools for these objects is impossible because the schema and names vary wildly between different Rippling tenants. Truto handles this by exposing generic custom object tool endpoints that instruct Claude on how to pass the correct custom_object_api_name as an argument based on previous discovery calls.

Silent Field Redactions Due to Entitlements Rippling enforces strict role-based access control (RBAC). When you query a worker profile, Rippling does not simply omit fields you lack access to or fail the request. Instead, it returns a 200 OK but silently redacts sensitive fields (like compensation or SSNs), appending a __meta.redacted_fields array explaining the reason. If your MCP server does not expose this metadata to Claude, the LLM will hallucinate missing data or falsely assume a worker does not have a manager assigned. Truto's tools explicitly include this metadata in the return schemas so the model understands when data was purposefully withheld.

Strict Rate Limiting Without Safety Nets Rippling enforces strict API quotas. If your AI agent gets stuck in a loop scraping directory data or batch updating custom objects, Rippling will return an HTTP 429. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (whether that is Claude, LangChain, or your custom agent) is fully responsible for handling the retry and exponential backoff logic.

How to Generate a Rippling MCP Server

Instead of building a standalone Node.js or Python server to map Rippling's documentation to JSON-RPC 2.0 schemas, you can use Truto to auto-generate a hosted MCP server.

Truto's MCP servers derive tool definitions dynamically from the integration's internal resource definitions and documentation schemas. When a customer connects their Rippling instance, Truto automatically exposes those resources as fully documented MCP tools over a secure JSON-RPC endpoint.

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

Method 1: Via the Truto UI

For internal tooling and manual setups, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to the integrated account page for the connected Rippling tenant.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server name, allowed methods (e.g., read, write), and optional expiration date.
5. Click Save, and immediately copy the generated MCP server URL. This URL contains a secure, hashed cryptographic token.

Method 2: Via the Truto API

For production workflows, you should provision MCP servers dynamically when an AI session begins. This ensures you can apply strict permissions and time-to-live (TTL) constraints.

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

curl -X POST "https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rippling Custom Objects MCP",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response returns the secure endpoint URL:

{
  "id": "mcp_8a7b6c5d",
  "name": "Rippling Custom Objects MCP",
  "config": { "methods": ["read", "write"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/t_9f8e7d6c5b4a3..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you need to connect it to your Claude environment. Because Truto MCP servers are fully self-contained, you do not need to manage local OAuth tokens or write custom integration code.

Method A: Via the Claude UI

If you are using Claude's enterprise or web interface that supports native custom connectors (or ChatGPT's Advanced Settings):

1. Open your model settings and navigate to Integrations (or Settings -> Connectors -> Add).
2. Select Add MCP Server.
3. Give the server a descriptive name (e.g., "Rippling HRIS").
4. Paste the Truto MCP server URL (https://api.truto.one/mcp/t_...).
5. Click Add. The model will immediately execute a handshake, call the tools/list protocol method, and populate its context with Rippling capabilities.

Method B: Via the Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally for development, you configure the connection via the claude_desktop_config.json file. Because Truto provides a remote HTTP endpoint rather than a local standard input/output script, you use the official SSE (Server-Sent Events) transport wrapper.

Locate your configuration file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Truto server using the npx command for the remote MCP client:

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

Restart Claude Desktop. The model now has direct read and write access to the Rippling tenant.

Hero Tools for Rippling Management

Truto automatically generates highly specific, documentation-driven tools for Rippling. Instead of a single generic "make API request" tool that the LLM has to figure out, Truto maps endpoints to distinct operational tools. Here are the highest-leverage tools available for custom object and worker management.

list_all_rippling_custom_object_records

This tool retrieves paginated records for a specific custom object definition. It requires the custom_object_api_name parameter to route the request properly.

Contextual usage: Use this when Claude needs to audit existing custom HR workflows, such as retrieving all assigned company vehicles or tracking external hardware requests.

"Get all the records from the custom object named 'hardware_requests' and find the ones that were created this month."

create_a_rippling_custom_object_record

This tool inserts a new row into a specific custom object table. It accepts the custom_object_api_name and an arbitrary JSON body representing the custom fields.

Contextual usage: Essential for AI agents that act as IT provisioning bots or HR assistants handling non-standard requests.

"Create a new record in the 'parking_allocations' custom object for user ID 8f7e6d. Set the spot_number to 42 and status to 'active'."

update_a_rippling_custom_object_record_by_id

Modifies an existing custom object record. It requires both the custom_object_api_name and the specific record id.

Contextual usage: Used by AI agents when resolving IT tickets or updating the status of an ongoing HR workflow tracked in a custom object.

"Update the hardware_request record ID 1024. Change the fulfillment_status to 'shipped' and add a note that the laptop is en route."

get_single_rippling_worker_by_id

Retrieves the complete profile of a worker, including employment type, compensation, department, and team data. It handles Rippling's strict RBAC by explicitly surfacing the __meta.redacted_fields array if the integrated account lacks permissions for specific sensitive data.

Contextual usage: The fundamental building block for any employee-centric workflow. Claude uses this to gather context before taking administrative action.

"Pull the complete worker profile for employee ID 5543. Tell me what department they are in and if any fields were redacted from your view."

list_all_rippling_supergroups

Retrieves organizational supergroups. Supergroups in Rippling are complex logic constructs used to group employees based on attributes (e.g., 'All full-time engineers in California').

Contextual usage: Used when Claude needs to understand organizational boundaries or verify if a user should have access to specific software based on their group inclusion.

"List all the supergroups in the system. Find the one that corresponds to the engineering department and give me its ID."

list_all_rippling_business_partners

Retrieves external business partners, contractors, or client groups associated with the Rippling tenant.

Contextual usage: Useful for AI agents handling procurement, contractor onboarding, or external lifecycle management.

"Pull a list of all active business partners. Filter the list to show only contractors managed by Sarah Connor."

For the complete tool inventory and detailed JSON Schema requirements, refer to the Rippling integration page.

Workflows in Action

Connecting tools is just the prerequisite. The real value of an MCP server is orchestrating multi-step workflows. Because the tools are strictly typed via JSON Schema, Claude knows exactly how to chain the outputs of one API call into the inputs of the next.

Scenario 1: IT Admin Custom Hardware Provisioning

An IT administrator wants to process a hardware request using an AI agent via Claude.

"Check if employee ID 8892 is a full-time worker. If they are, create a new record in the 'hardware_requests' custom object requesting a Macbook Pro M3. Set the status to 'pending_approval'."

Tool Execution Order:

1. get_single_rippling_worker_by_id: Claude calls this with id: "8892" to retrieve the worker profile.
2. Claude parses the employment_type from the JSON response to verify full-time status.
3. create_a_rippling_custom_object_record: Claude calls this with custom_object_api_name: "hardware_requests" and a JSON body containing {"equipment_type": "Macbook Pro M3", "status": "pending_approval", "worker_id": "8892"}.

Result: The LLM successfully provisions a custom IT asset workflow while validating HR policy prerequisites, returning a plain text confirmation to the admin.

Scenario 2: Supergroup Audit and Contextual Redaction

A compliance officer uses Claude to audit group memberships.

"Look up the supergroup named 'Production Access'. Find out who the app owner is, then retrieve that owner's worker profile. Let me know if any of their contact info is redacted."

Tool Execution Order:

1. list_all_rippling_supergroups: Claude fetches the list of groups and searches the response array for name: "Production Access", extracting the app_owner_id.
2. get_single_rippling_worker_by_id: Claude takes the app_owner_id and fetches the worker profile.
3. Claude inspects the __meta.redacted_fields array in the response to check if phone_numbers or emails are listed.

Result: The LLM navigates the relational mapping between supergroups and workers, explicitly reporting back on RBAC limitations rather than hallucinating missing data.

Security and Access Control

Exposing an HRIS and IT system to an LLM requires strict security guardrails. Truto's MCP architecture provides multiple layers of access control built directly into the server generation process.

• Method Filtering: You can restrict a Rippling MCP server to only allow read operations. If Claude attempts to hallucinate a create or update call, the server rejects it at the protocol level.
• Tag Filtering: By passing tags: ["directory"] during creation, you can limit the MCP server to only expose tools related to basic worker lookups, hiding sensitive custom objects and business partner endpoints.
• require_api_token_auth: By default, possessing the MCP URL grants access. By setting require_api_token_auth: true, the MCP router applies middleware that forces the client to also send a valid Truto API token in the Authorization header. This ensures that even if an MCP URL is leaked, it cannot be used outside of an authenticated session.
• expires_at: For temporary contractor access or single-session AI agents, you can set an ISO datetime for expiration. Truto stores this in a distributed key-value store and schedules edge alarms to automatically destroy the token and database records when the TTL expires.

Automating Rippling using Claude Desktop or custom LangChain agents unlocks massive operational leverage for IT and HR teams. By offloading the authentication state, schema management, and API normalization to a managed MCP server, your engineering team can focus on designing the actual AI prompts and workflow logic. You stop worrying about how to parse __meta.redacted_fields and start building agents that manage your workforce at scale.