Connect Teamtailor to Claude: Sync Job Openings & Candidate Notes

If your team uses ChatGPT, check out our guide on connecting Teamtailor to ChatGPT or explore our broader architectural overview on connecting Teamtailor to AI Agents.

Applicant Tracking Systems (ATS) are state machines. Moving a candidate from "Screening" to "Interview" is rarely just a database update - it triggers emails, schedules events, and notifies hiring managers. If you want to connect Teamtailor to Claude to automate job postings, parse candidate profiles, or draft interview feedback, you need a reliable translation layer between Claude's LLM tool calls and Teamtailor's backend.

You can either build and host a custom Model Context Protocol (MCP) server yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

Giving a Large Language Model (LLM) write access to your recruiting pipeline is a significant engineering challenge. You have to handle complex nested schemas, manage OAuth token lifecycles, and program your agent to respect strict vendor rate limits. This guide breaks down exactly how to use Truto to generate a secure Teamtailor MCP server, connect it natively to Claude, and execute complex recruiting workflows using natural language.

The Engineering Reality of the Teamtailor API

A custom Teamtailor Claude integration requires building 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 an ATS API is painful.

If you build a custom Teamtailor MCP server, you own the entire API lifecycle. Here are the specific challenges you will face with Teamtailor:

The JSON:API Specification Teamtailor strictly adheres to the JSON:API specification. This standard is highly verbose and relies on heavily nested data structures. Instead of sending a simple flat JSON object to create a candidate, you must construct a payload with data, type, attributes, and relationships. LLMs historically struggle with deeply nested, highly structured payloads, frequently hallucinating key names or misplacing objects. Truto bridges this gap by deriving flat, descriptive tool schemas directly from API documentation records, allowing Claude to interact with a simplified flat input namespace while Truto ensures the final API request complies with the spec.

Complex Relationship Linking In Teamtailor, a Candidate and a Job are distinct entities. To link them, you must create a job-application. This requires passing the exact id of the candidate, the id of the job, and optionally the id of the stage or reject reason. If your agent invents an ID or uses an email address instead, the request will fail. Your MCP server must enforce strict schema validation to ensure the LLM maps relationships correctly.

Rate Limiting and Backoff Mechanics Teamtailor enforces strict rate limits to protect its infrastructure. If an over-eager AI agent tries to iterate through thousands of candidate profiles in a single session, it will hit an HTTP 429 Too Many Requests error. Truto does not absorb, throttle, or apply magical backoff on rate limit errors. When the Teamtailor API returns a 429, Truto passes that error directly back to the caller, while normalizing the rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). You are responsible for programming your agent or client logic to interpret these headers and apply exponential backoff. This design ensures your agent is aware of the failure and can decide whether to wait or summarize the data it has already retrieved.

How to Generate a Teamtailor MCP Server with Truto

Truto dynamically generates MCP tools based on Teamtailor's resource definitions and API documentation. Tools are never cached or pre-built. You can spin up an MCP server scoped specifically to your integrated Teamtailor account via the UI or the API.

Method 1: Via the Truto UI

If you prefer a visual workflow, you can generate a server in less than a minute:

1. Log into Truto and navigate to your Integrated Accounts.
2. Select your connected Teamtailor account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read tools, filter by specific tags, or set an expiration date).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For automated deployments, you can provision an MCP server programmatically. Truto validates that the integration is AI-ready, hashes a secure token, and returns the endpoint.

curl -X POST https://api.truto.one/integrated-account/<TEAMTAILOR_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recruiting Agent MCP",
    "config": {
      "methods": ["read", "write"],
      "tags": ["candidates", "jobs"]
    }
  }'

Response:

{
  "id": "mcp_12345",
  "name": "Recruiting Agent MCP",
  "config": { "methods": ["read", "write"], "tags": ["candidates", "jobs"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL is fully self-contained. The cryptographic token in the path authenticates the request and scopes it directly to your Teamtailor tenant.

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your AI client. You can do this visually if your client supports it, or via a local configuration file for Claude Desktop.

Method 1: Via the Claude UI

(Note: While Anthropic is rolling out direct URL additions, many clients like ChatGPT already support this natively. For instance, in ChatGPT: Settings -> Apps -> Advanced settings -> Developer mode -> Add Custom Connector).

For enterprise Claude environments supporting remote integrations:

1. Open your Claude Settings.
2. Navigate to Integrations or Connectors.
3. Click Add MCP Server.
4. Paste the Truto MCP URL and click Add.

Method 2: Via the Claude Desktop Config File

If you are running Claude Desktop locally, you must configure it to connect to Truto's remote endpoint. Since Claude Desktop typically spawns local processes via stdio, you need an adapter to connect to Truto's HTTP/SSE endpoint. You can use the official @modelcontextprotocol/server-sse wrapper.

Open your Claude Desktop configuration file:

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

Add the Teamtailor server configuration:

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

Restart Claude Desktop. The model will initialize the connection, perform the MCP handshake, and dynamically load the Teamtailor tools.

Teamtailor MCP Hero Tools

Truto exposes Teamtailor resources as distinct, callable tools. Each tool expects a flat JSON object; Truto handles the complex routing of query schemas versus body schemas. Here are the highest-leverage operations for recruiting workflows.

create_a_teamtailor_job

This tool provisions a new open role in your ATS. It requires the basic job attributes like title and body description. Claude can generate the job description internally and post it directly to Teamtailor.

"Claude, create a new Teamtailor job for a Senior Backend Engineer. Draft a highly technical 3-paragraph job description focusing on Node.js and distributed systems, and publish the job."

create_a_teamtailor_candidate

This is the core of sourcing workflows. You must provide an email address unless the sourced flag is set to true. The merge attribute is particularly powerful - if Claude finds a duplicate email, setting merge: true combines the new attributes with the existing candidate profile instead of throwing an error.

"Claude, parse this raw text from a LinkedIn profile for Jane Doe (jane@example.com). Create a sourced candidate in Teamtailor using her details and make sure to merge if a profile already exists."

create_a_teamtailor_job_application

In Teamtailor, a candidate does not belong to a job until a job_application entity is created. This tool establishes the relationship. Claude will need the id from the candidate creation step and the id of the target job to execute this successfully.

"Link candidate ID 10934 to the Senior Backend Engineer job ID 4552 by creating a new job application."

create_a_teamtailor_note

Recruiters and hiring managers spend hours documenting interview feedback. This tool allows Claude to attach notes directly to a candidate's profile. You must provide the candidate ID and the user ID of the person leaving the note.

"Summarize the following interview transcript with candidate ID 8842. Extract the pros, cons, and technical red flags, then save this summary as a note on their Teamtailor profile."

get_single_teamtailor_note_by_id

Useful for auditing historical feedback. Claude can retrieve a specific note to read past interviewer feedback before drafting a final hiring recommendation.

"Retrieve note ID 9921 to check the previous interviewer's comments regarding the candidate's system design skills."

create_a_teamtailor_upload

If you have resumes, portfolios, or cover letters stored externally, you can attach them to a candidate. This tool requires the candidate's ID and a publicly accessible URL of the file. Truto passes this to Teamtailor to handle the ingestion.

"Take the portfolio link (https://example.com/portfolio.pdf) for candidate ID 5521 and create a new upload on their profile."

To view the complete inventory of available tools, query parameters, and schema details, visit the Teamtailor integration page.

Workflows in Action

Exposing these tools to Claude enables complex, multi-step orchestration. Let's look at how specific personas use this setup in the real world.

Workflow 1: Sourcing and Pipeline Management (Recruiter)

Recruiters often receive referrals via email or Slack. Instead of manually copying and pasting details into Teamtailor, a recruiter can hand the raw context to Claude.

"Claude, my colleague just referred Alex Chen (alex.chen@test.com) for the Lead Designer role (Job ID 4410). His LinkedIn is linkedin.com/in/alexc, and he specializes in SaaS UI. Add him to Teamtailor, link him to the job, and leave a note that he was an internal referral."

Execution Steps:

1. Claude calls create_a_teamtailor_candidate, passing first-name: "Alex", last-name: "Chen", email: "alex.chen@test.com", and sourced: true. It receives Candidate ID 8112 in response.
2. Claude calls create_a_teamtailor_job_application, passing the relationships for Candidate ID 8112 and Job ID 4410.
3. Claude calls create_a_teamtailor_note, passing Candidate ID 8112 and the note text: "Internal referral. Specializes in SaaS UI. Profile: linkedin.com/in/alexc".

Result: The recruiter completely bypassed the ATS interface. The candidate is structured correctly, mapped to the right job pipeline, and context is preserved.

Workflow 2: Interview Synthesis (Hiring Manager)

Hiring managers rarely want to log into the ATS just to write feedback. They can drop their rough, unstructured interview notes into Claude and have the agent formalize and upload them.

"Claude, I just interviewed candidate ID 5991. The technical screen went well. They knew React deeply but struggled a bit on database indexing. Add a concise note to their profile summarizing this, and also attach this code sample link (https://pastebin.com/raw/xyz) to their profile."

Execution Steps:

1. Claude analyzes the rough input and formats a professional feedback summary.
2. Claude calls create_a_teamtailor_note with Candidate ID 5991 and the formatted text.
3. Claude calls create_a_teamtailor_upload passing Candidate ID 5991 and the pastebin URL to attach the code sample.

Result: The hiring manager's feedback is instantly synchronized to the ATS, and the technical evidence is permanently attached to the candidate file.

Security and Access Control

Exposing a production ATS to an LLM requires strict governance. Truto MCP servers enforce security at the token level, ensuring agents only access what they explicitly need.

• Method Filtering (config.methods): You can restrict an MCP server to strictly read-only operations by passing ["read"] during server creation. This prevents the LLM from accidentally deleting candidate notes or publishing bogus jobs.
• Tag Filtering (config.tags): Scope tools by domain. By passing ["jobs"], the server will only expose endpoints related to job creation and listing, completely hiding candidate PII from the agent.
• Dual Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By enabling require_api_token_auth: true, the MCP client must also pass a valid Truto API token in the Authorization header, preventing lateral movement if the URL leaks.
• Auto-Expiration (expires_at): For external contractors or temporary agents, you can pass an ISO datetime to expires_at. Truto's background alarm system will automatically purge the server and invalidate the token when time expires.

Architect Your Recruiting Workflows

Building an integration with Teamtailor requires mastering the JSON:API specification, complex relationship mapping, and unforgiving rate limits. Hardcoding this logic into a custom MCP server means you own the maintenance burden every time Teamtailor updates a schema.

Using Truto, you bypass the infrastructure boilerplate entirely. You get a fully managed, documentation-driven MCP server that translates Claude's natural language intent into spec-compliant REST calls, while preserving your control over error handling and backoff mechanics.

Stop wrangling API specs and start automating your pipeline.