Connect ICIMS to Claude: Process Candidate Data and Resume Files

If your team needs to connect ICIMS to Claude to automate candidate sourcing, parse resume files, or orchestrate complex hiring workflows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and the underlying ICIMS REST API. 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 /connect-icims-to-chatgpt-manage-talent-profiles-and-hiring-workflows/, or explore our broader architectural overview on /connect-icims-to-ai-agents-automate-job-postings-and-sourcing/.

Giving a Large Language Model (LLM) read and write access to a sprawling enterprise applicant tracking system like ICIMS is a serious engineering challenge. You have to handle fragmented data schemas, map arbitrary custom fields, and deal with an API that relies heavily on complex search queries and abstract workflow links rather than straightforward nested JSON.

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

The Engineering Reality of the ICIMS 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 specialized B2B APIs is painful. ICIMS is built to manage massive global talent pools, complex organizational hierarchies, and highly customized compliance data. Its API reflects that deep enterprise complexity.

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

Custom Field Obfuscation ICIMS does not use standard, human-readable semantic keys for custom data. Instead, custom fields are exposed as arbitrary system IDs - for example, field17236. When building an MCP server, you cannot simply pass a raw ICIMS payload to Claude and expect the model to infer what field17236 means. You have to actively fetch the schema definition for that specific customer's platform (icims_schemas_get_profile_schema), map the IDs to human-readable descriptions, and inject those into the MCP tool definitions dynamically so the LLM knows exactly which fields to update.

Abstract Workflow Entities (Base vs. Associated Profiles) In ICIMS, a candidate is not simply an object nested inside a job requisition. Instead, they are entirely separate profiles (Person and Job) linked by abstract "Workflow" entities. A Recruiting workflow links a base profile (the Job) to an associated profile (the Person). To figure out who applied to a job, your agent cannot just call GET /jobs/123/candidates. It must query the icims_applicant_workflows_search endpoint using highly specific filter schemas, return the workflow IDs, fetch the workflows, and then resolve the associated Person profiles. This requires orchestration across multiple endpoints.

Complex Search Filter Schemas Finding records in ICIMS relies on a dedicated Search API that uses strict, highly nested JSON structures. You must pass exact filter arrays, specific operator strings, and pagination parameters formatted precisely as the API expects. Writing an MCP tool that securely translates a user's natural language request - like "Find me all software engineers in London who applied last week" - into a valid ICIMS search payload requires strictly enforced JSON Schemas at the tool generation layer.

Core Architecture: Documentation-Driven Dynamic Tools

Truto solves these problems by dynamically generating MCP tools based on live integration documentation and schemas.

When a customer connects their ICIMS account, Truto's MCP Router does not serve a static, hardcoded list of tools. Instead, it generates tool definitions on the fly during the tools/list initialization phase. It reads the integration's internal configuration, pulls the exact JSON Schemas for both the query parameters and request bodies, and merges them into a flat input namespace for the LLM.

Because ICIMS heavily utilizes pagination for search results and candidate lists, Truto automatically injects limit and next_cursor properties into the query schemas for list operations. The description for next_cursor explicitly instructs Claude to pass cursor values back exactly as received. When Claude calls a tool, the MCP router splits the flat argument object back into the correct query and body parameters and delegates the request to the proxy API execution layer.

Handling API Rate Limits ICIMS enforces strict rate limits on search queries and profile retrievals. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors automatically. If the ICIMS API returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller (Claude or your custom agent framework). Truto standardizes the upstream rate limit data into IETF-compliant headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller is entirely responsible for reading these headers and implementing its own retry or backoff logic.

How to Generate Your ICIMS MCP Server

Every MCP server in Truto is scoped to a single integrated account. This ensures that when Claude executes a tool, it operates strictly within the permissions of the authenticated ICIMS instance. The server URL contains a cryptographically hashed token that authenticates the connection automatically.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal tooling or quick agent deployment.

1. Log into your Truto dashboard and navigate to the specific ICIMS integrated account page.
2. Click on the MCP Servers tab.
3. Click Create MCP Server.
4. Name the server (e.g., "ICIMS Sourcing Agent").
5. Select your configuration options (filtering by tags like "candidates" or "jobs", specifying allowed methods like read or write, and setting an optional expiration date).
6. Copy the generated MCP server URL. You will only see this URL once.

Method 2: Via the API

For production deployments where you need to spin up AI agents dynamically for your customers, you can generate the MCP server programmatically.

Send 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_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production ICIMS Sourcing Server",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["recruiting", "profiles", "workflows"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will contain the secure URL you need to provide to your MCP client.

{
  "id": "mcp_srv_9x8y7z6w5v",
  "name": "Production ICIMS Sourcing Server",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["recruiting", "profiles", "workflows"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/t_8f7e6d5c4b3a2910..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude requires zero additional coding. The URL itself handles tool discovery, schema transmission, and API authentication.

Method A: Via the Claude UI

If you are using Claude Desktop or an enterprise workspace that supports visual configuration:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server.
2. Paste the Truto MCP URL into the Server URL field.
3. Click Add.

Claude will immediately perform the JSON-RPC initialization handshake and fetch the available ICIMS tools.

(Note: If you are configuring this for ChatGPT, the flow is similar: navigate to Settings -> Apps -> Advanced settings -> Developer mode -> Custom connectors, and paste the URL).

Method B: Via Manual Config File

If you are using the standard Claude Desktop app for local development, you configure the server via the claude_desktop_config.json file. Because Truto's MCP servers communicate over Server-Sent Events (SSE) via standard HTTP POST, you use the official @modelcontextprotocol/server-sse wrapper.

Edit your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop. The ICIMS tools are now available for your agent.

Security and Access Control

When granting an LLM access to sensitive hiring and compensation data, strict security boundaries are mandatory. Truto provides several mechanisms to lock down your ICIMS MCP server:

• Method Filtering: Use config.methods to restrict the server to specific operations. Passing ["read"] ensures the agent can only execute get and list methods, physically preventing it from modifying applicant data or creating rogue job profiles.
• Tag Filtering: Use config.tags to limit the server's scope to specific domains. For example, passing ["jobs"] restricts the agent to job requisition endpoints, hiding candidate profile data entirely.
• API Token Authentication: By default, the MCP token in the URL is the only authentication required. Setting require_api_token_auth: true forces the client to also provide a valid Truto API token via the Authorization header, adding a critical second layer of security.
• Automatic Expiration: The expires_at field sets a strict TTL (Time To Live). Truto stores this token in Cloudflare KV with a matching expiration timestamp and schedules a Durable Object cleanup alarm, ensuring access is irrevocably destroyed when time runs out.

Hero Tools for ICIMS Automation

Truto maps the complex ICIMS architecture into descriptive, snake_case tools with strictly enforced JSON schemas. Here are six high-leverage tools available for your agent.

icims_people_search

Executes complex search queries against the Person profile database. This tool accepts a nested filter schema and returns matching system IDs. Paging is handled by passing an id > last-id filter on subsequent requests.

"Search ICIMS for all candidate profiles where their primary skill includes 'React' and they are located in New York. Return their system IDs."

get_single_icims_person_by_id

Fetches a comprehensive Person profile using their system ID. This returns the detailed record, including contact information, employment history, and resolved custom fields.

"Retrieve the full candidate profile for the person with system ID 84920 and summarize their last three years of work experience."

icims_applicant_workflows_search

Searches the Recruiting workflow entities that link a Person to a Job. This is the primary method for finding which candidates applied to specific job requisitions, or finding which jobs a specific candidate is being considered for.

"Find all active applicant workflows linked to the Senior Backend Engineer job requisition (ID 4021) that were created in the last 7 days."

icims_profile_files_get_resume_text

Directly extracts the parsed plain text from a candidate's uploaded resume file. This bypasses the need to download and parse PDFs manually, allowing Claude to immediately analyze the raw text data.

"Extract the resume text for candidate ID 99214 and evaluate if they meet the hard requirements for the Data Scientist role based on their past project descriptions."

update_a_icims_job_by_id

Modifies a Job requisition profile using its system ID. The agent only sends the specific fields that need to be changed. This requires mapping custom field IDs against the schema endpoint.

"Update the job profile for system ID 4021. Change the status to 'On Hold' and add a note to the internal description field that hiring is frozen until Q3."

create_a_icims_person

Creates a new Person profile in a specific folder. The new profile's system ID is captured from the Location header of the response and returned to the agent.

"Create a new ICIMS candidate profile for Jane Doe (jane.doe@example.com) and place her in the 'Passive Sourced Talent' folder."

To view the complete list of available operations, schemas, and custom methods, view the ICIMS integration page.

Workflows in Action

When Claude has access to these granular tools, it can orchestrate highly complex sequences of operations autonomously. Here are two real-world workflows.

Scenario 1: Candidate Sourcing and Resume Analysis

A recruiter wants to find passive candidates in the system for a new engineering role and automatically screen their resumes against specific technical requirements.

"Search our ICIMS database for candidates tagged with 'Kubernetes' and 'Go'. For the top 5 results, pull their resume text, evaluate their actual experience with container orchestration, and give me a summary of the strongest candidate."

Tool Execution Sequence:

1. icims_people_search: Claude constructs the search filter payload targeting the specific skill fields and executes the query to retrieve system IDs.
2. get_single_icims_person_by_id: The agent iterates through the returned IDs to fetch basic profile information (names, current roles).
3. icims_profile_files_get_resume_text: Claude fetches the raw parsed resume text for each candidate.
4. The model analyzes the unstructured text data in its context window, scores the candidates against the prompt criteria, and outputs the final strategic recommendation.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant ICIMS as ICIMS API

    User->>Claude: "Find Kubernetes candidates and analyze resumes"
    Claude->>Truto: Call icims_people_search(filters)
    Truto->>ICIMS: POST /search/people
    ICIMS-->>Truto: Returns system IDs [8192, 8195]
    Truto-->>Claude: Returns IDs to context
    
    rect rgb(235, 232, 226)
    note right of Claude: Loop over top candidates
    Claude->>Truto: Call icims_profile_files_get_resume_text(8192)
    Truto->>ICIMS: GET /people/8192/fields/resume/text
    ICIMS-->>Truto: Returns parsed plain text
    Truto-->>Claude: Returns text
    end

    Claude-->>User: Outputs analysis and candidate recommendation

Scenario 2: Job Requisition Update & Applicant Sync

A hiring manager needs to pause a role and notify the recruitment team about the pipeline status.

"Put the Product Marketing Manager role (ID 3341) on hold. Then, check how many candidates currently have an active applicant workflow linked to that job, and list their names."

Tool Execution Sequence:

1. update_a_icims_job_by_id: Claude issues the update payload to change the job's status field to the 'On Hold' parameter.
2. icims_applicant_workflows_search: The agent queries the workflow endpoint, filtering by the specific job_id (3341) and status 'Active', returning a list of workflow IDs.
3. get_single_icims_applicant_workflow_by_id: (Iterative) Claude pulls the workflow details to find the associated person_id for each applicant.
4. get_single_icims_person_by_id: (Iterative) The agent fetches the person profiles to extract the names and compile the final report.

Wrap-Up

Connecting ICIMS to Claude transforms an ATS from a static database into an active, intelligent partner. By utilizing an MCP server, you abstract away the pain of ICIMS's fragmented workflows, complex search schemas, and custom field masking. Instead of forcing your engineers to write point-to-point scripts for every new HR request, you give your LLM the exact tools it needs to execute complex sourcing and data management tasks dynamically.

With Truto handling the token lifecycle, schema generation, and secure execution routing, your team can focus on building intelligent agent behaviors rather than maintaining brittle ATS integration code.