---
title: "Connect Recruitee to Claude: Audit Office Locations and Team Admins"
slug: connect-recruitee-to-claude-audit-office-locations-and-team-admins
date: 2026-06-09
author: Uday Gajavalli
categories: ["AI & Agents"]
excerpt: "A complete engineering guide to connecting Recruitee to Claude using a managed MCP server. Automate HR workflows, audit locations, and analyze candidate notes."
tldr: "Learn how to expose Recruitee's API to Claude Desktop via a managed Model Context Protocol (MCP) server. This guide covers bypassing integration boilerplate, handling Recruitee's rate limits, and orchestrating complex HR workflows."
canonical: https://truto.one/blog/connect-recruitee-to-claude-audit-office-locations-and-team-admins/
---

# Connect Recruitee to Claude: Audit Office Locations and Team Admins


If you need to connect Recruitee to Claude to automate candidate note analysis, audit office locations, or orchestrate hiring team permissions, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's natural language tool calls and Recruitee's REST APIs. You can either build and maintain this infrastructure yourself, or use a [managed integration platform](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) like Truto to dynamically generate a secure, authenticated MCP server URL. 

If your team uses ChatGPT, check out our guide on [connecting Recruitee to ChatGPT](https://truto.one/connect-recruitee-to-chatgpt-analyze-interviews-and-candidate-notes/) or explore our broader architectural overview on [connecting Recruitee to AI Agents](https://truto.one/connect-recruitee-to-ai-agents-sync-hiring-feedback-and-offer-notes/).

Giving a Large Language Model (LLM) read and write access to an [Applicant Tracking System (ATS)](https://truto.one/what-are-ats-integrations-2026-architecture-strategy-guide/) like Recruitee is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map complex JSON schemas to MCP tool definitions, and deal with Recruitee's specific sub-resource routing. Every time an endpoint updates or a new custom field is added, 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 Recruitee, connect it natively to Claude Desktop, and execute complex HR workflows using natural language.

## The Engineering Reality of the Recruitee API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into HTTP requests. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a massive ATS API is painful. 

If you decide to build a custom MCP server for Recruitee, you own the entire API lifecycle. Here are the specific challenges you will face when mapping Recruitee to an LLM context:

**Scattered Candidate Context and Sub-Resources**
Recruitee's data model is highly relational. You cannot retrieve a candidate's complete profile, interview feedback, and offer notes in a single API call. Notes, interview results, and offer data are distinct sub-resources that require multiple chained API requests. If you expose raw endpoints to Claude, the model must perfectly understand this relational hierarchy to gather context. A managed MCP server provides these endpoints as distinct, clearly defined tools with schema hints, allowing the LLM to orchestrate the fetching logic without hallucinating relationship IDs.

**Strict Rate Limits Without Automatic Backoff**
Recruitee enforces rate limits to protect its infrastructure. A common mistake engineers make when building custom MCP servers is expecting the server to absorb these limits silently. 

It is important to understand a factual constraint here: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Recruitee API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. What Truto *does* do is normalize the upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. The caller - whether that is Claude Desktop or your custom agent framework - is strictly responsible for reading these headers and executing its own retry and exponential backoff logic.

**Dynamic Documentation-Driven Tooling**
Hardcoding tool definitions for Recruitee is a losing battle. Recruitee frequently adds new fields to candidate profiles and evaluation schemas. Truto solves this by deriving MCP tool definitions dynamically from documentation records and JSON Schema validation rules. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring Claude only sees highly curated, well-described endpoints.

## How to Generate a Recruitee MCP Server with Truto

Truto automatically generates an MCP server for any connected integrated account. Each server is fully self-contained - the URL alone contains a cryptographic token that handles routing, authentication, and token refreshes. You do not need to manage API keys on the client side.

You can create this server in two ways: via the Truto UI for rapid prototyping, or via the REST API for programmatic deployment.

### Method 1: Via the Truto UI

If you are setting up Claude Desktop for internal use, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to the **Integrated Accounts** page.
2. Select your connected Recruitee account.
3. Click the **MCP Servers** tab.
4. Click **Create MCP Server**.
5. Select your desired configuration (e.g., name the server "Recruitee Audit", restrict methods to `read`, or filter by specific tags).
6. Copy the generated MCP server URL. 

### Method 2: Via the Truto API

If you are provisioning AI workspaces for your enterprise customers, you will want to generate these servers programmatically. 

The API validates that the Recruitee integration has documented tools available, generates a secure, hashed token stored in the metadata registry, and returns a ready-to-use JSON-RPC URL.

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

```bash
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": "Recruitee Agent Tools",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'
```

**Expected Response:**

```json
{
  "id": "mcp_abc123",
  "name": "Recruitee Agent Tools",
  "config": { "methods": ["read", "write"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/tkn_789xyz..."
}
```

Save the `url` returned in the response. This is the only configuration your client needs.

## How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your LLM client. Claude will query the URL using the `tools/list` protocol method to discover the available Recruitee operations, and use `tools/call` to execute them.

You can connect the server using the Claude UI or by manually editing the configuration file.

### Method A: Via the Claude UI

If your organization is on a Claude Enterprise or Team plan (or if you are connecting to ChatGPT), you can use the graphical interface:

1. Open your LLM client (e.g., for Claude: **Settings -> Integrations -> Add MCP Server**; for ChatGPT: **Settings -> Connectors -> Add**).
2. Provide a recognizable name, such as "Recruitee Production".
3. Paste the Truto MCP URL generated in the previous step.
4. Click **Add**. The client will perform a handshake, retrieve the integration capabilities, and the tools will immediately become available in your chat interface.

### Method B: Via Manual Config File (Claude Desktop)

For developers running Claude Desktop locally, you can inject the server directly into the configuration file using the Server-Sent Events (SSE) transport wrapper.

Open your Claude Desktop config file. On macOS, this is located at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, it is at `%APPDATA%\Claude\claude_desktop_config.json`.

Add the following JSON payload, replacing the URL with your Truto endpoint:

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

Restart Claude Desktop. The application will boot the SSE wrapper, connect to the Truto router, and list your Recruitee operations as native tools.

## Hero Tools for Recruitee

Truto automatically maps Recruitee's endpoints into descriptive, snake_case tools that Claude can understand. The schemas are enhanced with descriptions that instruct the LLM on exactly how to format queries. 

Here are the highest-leverage hero tools for auditing and managing a Recruitee workspace.

### list_all_recruitee_interview_results

This tool retrieves the structural evaluation data submitted by hiring managers after an interview. It requires the `company_id` and returns an array of interview results including the `candidate_id`, `admin_id`, `kind`, and detailed evaluation metrics. This is critical for agents trying to summarize hiring consensus.

> "Claude, list all the interview results for company ID 1045. I need to know which admin submitted the lowest scores this week so we can review their evaluation criteria."

### list_all_recruitee_notes

Retrieves unstructured notes left on a specific candidate's profile. It requires the `company_id` and the candidate's `id`. The response includes the `body` of the note, `admin_id`, `created_at` timestamps, file `attachments`, and `visibility` rules. AI agents use this tool to compile a narrative history of a candidate's journey.

> "Get all the notes for candidate ID 88392 in company 1045. Summarize any concerns the hiring managers left regarding their system design skills, and list any files they attached."

### list_all_recruitee_locations

This is a powerful administrative tool. It lists all physical and remote locations configured in the Recruitee instance. It returns the `id`, `name`, `country_code`, `city`, `full_address`, and metadata like `active_offers_count` and `active_requisitions_count`. It is highly useful for capacity planning and HR compliance audits.

> "List all the office locations configured in our Recruitee account (company 1045). Cross-reference the active_requisitions_count for each location and tell me which office has the highest hiring volume right now."

### list_all_recruitee_offer_notes

Offer negotiation often involves sensitive back-and-forth communication. This tool retrieves notes attached specifically to an offer record. It requires `company_id` and `offer_id`, returning the `text`, `admin_id`, and nested replies. Agents use this to track negotiation status without exposing the underlying financial figures directly if restricted.

> "Check the offer notes for offer ID 44021. Provide a timeline of the negotiation based on the nested replies, and identify if the candidate asked for a higher equity package."

### list_all_recruitee_admins

Security and governance workflows rely on knowing who has access to the ATS. This tool lists all administrators in the Recruitee account. It requires the `company_id` and returns the admin's `id`, `name`, `email`, and `role`. It is essential for access reviews and routing approval requests.

> "Run an audit on our Recruitee admins for company 1045. List all users with a 'super_admin' role and flag any email addresses that do not belong to our primary corporate domain."

To view the complete inventory of available tools, query schemas, and response formats, visit the [Recruitee integration page](https://truto.one/integrations/detail/recruitee).

## Workflows in Action

Exposing individual endpoints is just the foundation. The real value of an MCP server is allowing Claude to chain these tools together to execute multi-step workflows. 

Here are two concrete, persona-specific examples of how HR ops teams and administrators can use Claude to automate Recruitee.

### Workflow 1: The Interview Debrief & Offer Readiness Check

**Persona**: Lead Technical Recruiter  
**Goal**: Before moving a candidate to the offer stage, ensure all interview feedback is positive, the negotiation notes are clear, and the correct hiring managers have signed off.

> "Claude, I'm preparing an offer for candidate ID 99201. Pull all their interview results to ensure they passed the technical loops. Then, check the general notes on their profile to see if the hiring manager (admin ID 552) left any final thoughts. Finally, check the offer notes for offer ID 44021 to summarize where we left off on salary expectations."

**Execution Steps:**
1. Claude calls `list_all_recruitee_interview_results` using the candidate ID filter to retrieve the structured scoring data.
2. Claude parses the results, confirming the technical loops were marked as passing.
3. Claude calls `list_all_recruitee_notes` for the specific candidate to retrieve unstructured feedback.
4. Claude filters the returned notes in-memory to find entries authored by admin ID 552.
5. Claude calls `list_all_recruitee_offer_notes` to retrieve the negotiation thread.

**Result**: Claude synthesizes the data from three different API endpoints into a single, comprehensive briefing document. It confirms the candidate passed the technical loops, highlights the hiring manager's final approval note, and summarizes the last recorded salary expectation, proving the candidate is ready for an official offer generation.

```mermaid
sequenceDiagram
    participant User
    participant Claude
    participant Truto MCP
    participant Recruitee API

    User->>Claude: Summarize offer readiness for candidate 99201
    Claude->>Truto MCP: call tool: list_all_recruitee_interview_results
    Truto MCP->>Recruitee API: GET /c/1045/interviews...
    Recruitee API-->>Truto MCP: 200 OK (Scores)
    Truto MCP-->>Claude: JSON Tool Result
    
    Claude->>Truto MCP: call tool: list_all_recruitee_notes
    Truto MCP->>Recruitee API: GET /c/1045/candidates/99201/notes
    Recruitee API-->>Truto MCP: 200 OK (Manager Notes)
    Truto MCP-->>Claude: JSON Tool Result
    
    Claude->>User: Renders unified debrief summary
```

### Workflow 2: Infrastructure & Capacity Audit

**Persona**: HR Operations / System Admin  
**Goal**: Analyze hiring volume across global offices and map it against the administrative team responsible for those regions.

> "Claude, I need a capacity report. List all our Recruitee office locations and rank them by active requisitions. Then, list all our Recruitee admins. Tell me if we have enough local admins in the 'London' office based on the requisition load."

**Execution Steps:**
1. Claude calls `list_all_recruitee_locations` to fetch the global office directory.
2. Claude parses the `active_requisitions_count` for each location and sorts the list descending.
3. Claude identifies the 'London' location object and notes its requisition count.
4. Claude calls `list_all_recruitee_admins` to fetch the user directory.
5. Claude cross-references the admin profiles (often using custom fields or title strings) against the London hiring load.

**Result**: The user receives a ranked list of offices by hiring volume, followed by an analysis indicating whether the London office has a disproportionately high number of open roles compared to the number of regional recruiters currently active in the system.

## Security and Access Control

Giving an LLM access to HR data requires strict governance. Truto's MCP architecture provides four layers of security to ensure Claude only accesses what it is explicitly authorized to touch.

*   **Method Filtering (`config.methods`)**: Restrict the server to specific operation types. Setting `methods: ["read"]` ensures Claude can only execute `get` and `list` tools. It physically prevents the LLM from creating, updating, or deleting candidate records, eliminating the risk of destructive hallucinations.
*   **Tag Filtering (`config.tags`)**: Integration resources are tagged by domain. You can configure the MCP server to only expose tools tagged with `directory` or `compliance`, hiding sensitive financial or offer-related tools from the model entirely.
*   **API Token Authentication (`require_api_token_auth`)**: By default, the MCP token URL acts as a bearer token. By enabling `require_api_token_auth: true`, you force the client to provide an additional Truto API token in the `Authorization` header. This ensures that even if the MCP URL is leaked in a log file, the tools cannot be executed without secondary credentials.
*   **Time-to-Live (`expires_at`)**: You can generate short-lived MCP servers for temporary workflows. By setting an ISO datetime in the `expires_at` field, Truto will automatically clean up the server and revoke access when the time expires, leaving no stale credentials behind.

## Moving Beyond the Basic Connector

Connecting an LLM to an ATS involves much more than wrapping a REST API in a JSON-RPC endpoint. It requires handling dynamic schemas, standardizing pagination, navigating complex sub-resources, and architecting secure authentication perimeters.

Truto handles the undifferentiated heavy lifting of API integrations. By deriving tools directly from documentation records and explicitly surfacing rate limit headers for intelligent backoff, Truto ensures your AI agents interact with Recruitee predictably and securely.

> Stop building custom integration layers. Let Truto handle the auth, pagination, and MCP tool generation for your AI agents.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)