# What is the Rippling MCP

> Concepts, security model, and capabilities before you install a client.

## Overview

The Rippling MCP is a first-party Model Context Protocol (MCP) connection that lets you work with your organization’s Rippling data and workflows through a controlled, governed interface.

Instead of giving AI applications broad API keys or unrestricted database access, the Rippling MCP provides a controlled, governed interface. It allows AI clients to carry out specific, approved workplace tasks (such as looking up organizational reporting lines, requesting time off, or drafting a new hire) while strictly enforcing your company’s security policies and role-based permissions.

* * *

## How the Rippling MCP works

To understand how information flows securely between your AI application and Rippling, it helps to understand the four primary components involved in an MCP interaction:

```text
+---------------+      +--------------+      +--------------+      +------------+
| AI client     | ---> | Rippling MCP | ---> | MCP          | ---> |  Rippling  |
|               |      | Gateway      |      | server       |      |  platform  |
+---------------+      +--------------+      +--------------+      +------------+
```

-   **AI client:** The application that sends tool call requests to the Rippling MCP.
-   **Rippling MCP Gateway:** Before any request reaches Rippling, the MCP Gateway acts as the security checkpoint and verifies the request against your company’s MCP Gateway policies, checks the user’s identity, and determines if the requested tool is allowed.
-   **MCP server:** The first-party service hosted by Rippling that exposes curated, approved tools to the AI client.
-   **Rippling platform:** The system of record containing your organization's HR, IT, and payroll data. This is where approved actions are ultimately carried out according to your company’s standard business rules and manager approval flows.

### Rippling MCP vs. Rippling AI

The Rippling MCP and Rippling AI are different ways to work with the same company data.

|  | Rippling MCP | Rippling AI |
| --- | --- | --- |
| What it is | A secure connection bridge that allows external AI tools to interact with your Rippling data | Rippling’s built-in AI assistant, available in the app or via the MCP |
| What you receive | Structured data that your AI agent can immediately pass into another step or tool | A direct, plain-text summary or answer |
| What it can modify | Approved actions (e.g., time-off requests, draft hires), subject to Rippling’s normal review rules | Can take action when used inside the Rippling app, but returns read-only answers when queried via the MCP using `ask_ai` |
| When to use | Your AI needs to execute multi-step workflows, perform precise actions, or pass real data between tools | You have open-ended questions across products where you need Rippling to search, group, and calculate the data for you |

> **Note:**
> The **MCP Gateway** is the admin control panel for who can connect to the Rippling MCP and which tools they receive access to. It is not a method to query Rippling data directly.

* * *

## Access & permissions

Access to the Rippling MCP is governed through a dual-layer permission model:

-   **MCP Gateway policy:** Controls which tools, actions, or categories of access are available through the Rippling MCP. Configured using Supergroups.
-   **Rippling permissions:** Controls what you are normally allowed to see or do in Rippling.

To use an action, you must have access to it through the MCP Gateway policy and have the required Rippling permissions for the underlying data or action.

For example, an employee might be allowed to use a tool that looks up their own information, while an HR admin might have access to broader people operations tools if their Rippling role allows it and the MCP Gateway policy permits it.

Expected access behavior:

1.  Employees have no access until an admin creates an access policy.
2.  The connection shows one tool called `code`. Actions trigger standard governance. For example, requesting time off through the Rippling MCP creates an official time-off request that enters your organization's standard manager approval queue.
3.  High-impact administrative actions (like hiring an employee) create a draft state in Rippling for human review rather than executing immediately.

> **Subscription requirement:**
> Tool calls to the Rippling MCP will not return any data unless your company is in an active Rippling AI trial or has an active Rippling AI subscription.

* * *

## Security & governance

The Rippling MCP combines multi-layer controls, isolated sandboxing, and data safeguards to ensure AI clients interact with Rippling safely without bypassing system permissions.

Access relies on several interworking layers:

-   **First-party connection:** Managed directly by Rippling to guarantee native governance.
-   **User identity:** Operates using the connected employee’s explicit Rippling identity. The AI client never acts as an unrestricted service account, global admin, or static API key.
-   **Granular policy control:** Admins use MCP Gateway policies to govern exactly who can connect which tools to Rippling.
-   **Enforced permissions:** Normal Rippling role-based access rules still apply—users cannot access data or perform actions via MCP that they cannot access in Rippling directly.
-   **Explicit authorization:** Users must explicitly authorize the connection when connecting to the Rippling MCP.

### Data protection & redaction

The Rippling MCP only exposes approved tools and scoped responses - it never provides raw database access or open API endpoints.

High-risk sensitive data is never exposed through the Rippling MCP, including:

-   Social Security numbers (SSNs)
-   Home addresses
-   Personal email addresses
-   Tax IDs

### Sandboxing

Tool execution takes place in an isolated sandbox environment:

-   **Zero network egress:** The sandbox cannot make outbound external network calls and can only interact with allowed Rippling actions.
-   **Credential isolation:** Authentication, API keys, retries, metrics, and logging occur entirely outside the sandbox so credentials are never exposed to the execution runtime.

### Access lifecycle

MCP Gateway gives admins real-time lifecycle management over the Rippling MCP. When a worker is offboarded in Rippling, access is automatically revoked—preventing orphaned agent keys or lingering access. Admins can also instantly revoke specific tools company-wide at any time.

* * *

## Tools & actions

Available actions depend on your organization’s MCP Gateway configuration and your Rippling permissions. Supported actions include:

-   Search people and manager relationships
-   Request time off
-   View leave balances
-   Create a draft new hire
-   Create and manage custom objects

The Rippling MCP is designed for approved, scoped actions. It does not support unrestricted browsing or raw database access.

* * *

## Rate limits

To maintain system reliability and prevent runaway loops from external scripts, the Rippling MCP enforces fixed rate and concurrency limits per authenticated user.

### Usage thresholds

Rate and concurrency limits apply **per authenticated user**:

| Feature | Limit | Behavior |
| --- | --- | --- |
| Function calls | **50** calls per **60-second** window | Tracked independently per tool bucket (e.g., reaching the limit on `lookup_person` will not block `search_people`). |
| `ask_ai` starts | **5** new runs per rolling **60-second** window | Applies strictly to newly initiated runs. Operates on a separate budget from standard function calls. |
| `ask_ai` concurrency | **10** active runs | Caps parallel active runs. |

> **Note:**
> Calling `code` itself does not consume the 50-call budget. However, tools invoked inside a script count against its specific function bucket. For example, a single `code` program calling `lookup_person` 20 times counts as 20 calls against `lookup_person`.

### Handle rate limits

When a limit is reached, the Rippling MCP returns a structured tool error rather than dropping the connection.

**Function limits:**

-   Pause execution until the rolling 60-second window resets.
-   Avoid tight-loop retry routines.
-   _Example_: If a program calls `lookup_person` 50 times in 60 seconds, further `lookup_person` calls for that user fail until the window resets. Calls to other functions (like `search_people`) can continue.

**`ask_ai` limits:**

-   A sixth `start` inside the same minute fails with `RATE_LIMITED`. Wait and retry.
-   An eleventh run while ten are still active fails with `CONCURRENCY_LIMITED`. Wait for a run to finish, or cancel one, then retry.

* * *

## See also

-   [Set up the Rippling MCP](https://developer.rippling.com/documentation/rippling-platform/rippling-mcp/setup)
-   [Rippling MCP Tools](https://developer.rippling.com/documentation/rippling-platform/rippling-mcp/tools)
-   [MCP Troubleshooting & FAQs](https://developer.rippling.com/documentation/rippling-platform/rippling-mcp/troubleshooting)

Source: https://developer.rippling.com/documentation/rippling-platform/rippling-mcp/overview

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.
