Connect SmartRecruiters to ChatGPT: Manage Jobs and Candidates

If you need to connect SmartRecruiters to ChatGPT to automate applicant tracking, manage job postings, or review candidate screening answers, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and the SmartRecruiters REST API. You can either spend weeks building and hosting this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds.

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

Giving a Large Language Model (LLM) read and write access to an enterprise Applicant Tracking System (ATS) like SmartRecruiters is a massive engineering challenge. You have to handle complex nested data models, strict state machine transitions for candidate statuses, and disparate endpoints for attachments and screening answers. Every time you want to expose a new SmartRecruiters feature to ChatGPT, your custom server code must be updated, redeployed, and tested.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for SmartRecruiters, connect it natively to ChatGPT, and execute complex hiring workflows using natural language.

The Engineering Reality of the SmartRecruiters 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, implementing it against the SmartRecruiters API is exceptionally painful.

If you decide to build a custom MCP server for SmartRecruiters, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with this ATS:

Fragmented Candidate Data Models

Unlike simpler CRMs where a GET /candidates/{id} request returns everything you need, the SmartRecruiters candidate model is highly fragmented. Fetching a candidate's base profile gives you their name and contact info. To see their screening answers, you must query a separate endpoint using both the candidate_id and the job_id. To get their attachments or resumes, you must query another endpoint. If you want to check their compliance status, you have to query the consent endpoints. A custom MCP server must manually define separate JSON-RPC tools for all of these sub-resources, or build heavy orchestration logic to aggregate them into a single payload.

Strict State Machine Validation on Status Updates

Updating a candidate's status in SmartRecruiters is not a simple string update. The API enforces strict pipeline rules. If an LLM attempts to move a candidate to REJECTED or WITHDRAWN, the API requires a valid rejection reason ID. If a hiring pipeline has mandatory sub-statuses, skipping them will result in a REQUIRED_SUB_STATUS_OMITTED error. If you do not map these requirements perfectly into your MCP tool schemas, ChatGPT will confidently generate invalid payloads, resulting in endless HTTP 400 errors.

Rate Limits and Pagination Cursors

SmartRecruiters enforces strict rate limits to protect its infrastructure. Truto does not retry, throttle, or apply backoff on rate limit errors. When the SmartRecruiters API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto does normalize the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller - in this case, your agent framework or custom ChatGPT script - is responsible for handling the retry and backoff logic.

Additionally, SmartRecruiters pagination relies on nextPageId cursors. Truto automatically injects cursor instructions into the auto-generated tool schemas, explicitly commanding the LLM to pass the cursor value back exactly as received, preventing the model from hallucinating pagination logic.

Step-by-Step: Connecting SmartRecruiters to ChatGPT

Truto's architecture derives MCP tool definitions dynamically from the integration's resource configurations and documentation records. This means the tools are generated on the fly - no hardcoded schemas required.

Here is how you spin up an MCP server for SmartRecruiters and connect it to ChatGPT.

Step 1: Connect SmartRecruiters via Truto

Before generating an MCP server, you must authenticate the SmartRecruiters account.

1. In the Truto dashboard, navigate to Integrated Accounts -> New Integrated Account.
2. Select SmartRecruiters from the integration list.
3. Complete the OAuth flow or enter the required API credentials.
4. Once connected, note your integrated_account_id. Truto will handle the token refresh lifecycle automatically in the background.

Step 2: Generate the MCP Server

Truto scopes every MCP server to a single integrated account using a secure, hashed token. You can create this server via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

1. Navigate to the integrated account page for your SmartRecruiters connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., filter to specific methods like read or specific tags like candidates).
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456).

Method B: Via the API For programmatic setups, make a POST request to the Truto API to generate the server. This allows you to restrict the server to specific operations using methods and tags.

curl -X POST https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SmartRecruiters Hiring Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["candidates", "jobs", "interviews"]
    }
  }'

The API validates that the integration has tools available, generates a secure token, and returns a ready-to-use URL.

Step 3: Connect the MCP Server to ChatGPT

Now that you have your secure Truto MCP URL, you need to register it with ChatGPT. You can do this through the ChatGPT UI or via a configuration file if you are running a custom client.

Method A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Ensure Developer mode is enabled (available on Pro, Plus, Business, Enterprise, and Education plans).
3. Under MCP servers / Custom connectors, click to add a new server.
4. Set the Name to something descriptive like "SmartRecruiters (Truto)".
5. Paste the Truto MCP URL into the Server URL field and save.

ChatGPT will immediately ping the endpoint, perform the MCP initialization handshake, and load the SmartRecruiters tools.

Method B: Via Manual Config File (for custom clients/desktop) If you are using a local agent or a desktop client that requires an MCP config file, you can use the official SSE transport package. Create or update your mcp_config.json file:

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

SmartRecruiters Hero Tools for ChatGPT

When ChatGPT connects to the Truto MCP server, it executes a tools/list request. Truto reads the SmartRecruiters API documentation records and dynamically compiles them into JSON-RPC 2.0 tool schemas.

Here are the highest-leverage tools ChatGPT can use to automate your ATS.

List All SmartRecruiters Jobs

Tool name: list_all_smart_recruiters_jobs Searches SmartRecruiters jobs by title keyword, location, status, or hiring team member. This is the entry point for pipeline reporting and finding open requisitions.

"Find all active engineering jobs in the New York office that were updated this week."

Get Single SmartRecruiters Candidate by ID

Tool name: get_single_smart_recruiters_candidate_by_id Retrieves the core details of a candidate profile, including their contact information and creation dates. Required before attempting to fetch job-specific data like screening answers or attachments.

"Pull the profile details for candidate ID 10934850."

Get Candidate Screening Answers

Tool name: smart_recruiters_candidates_screening_answers Retrieves the answers a candidate submitted for a specific job's screening questions. This tool requires both the candidate_id and the job_id, which the LLM manages automatically using data from previous tool calls.

"Get the screening answers submitted by candidate 10934850 for the Senior Frontend Developer role (Job ID 55512)."

Update Candidate Job Status

Tool name: smart_recruiters_candidates_update_status Moves a candidate through the hiring pipeline for a specific job assignment. If moving to a rejected state, the LLM must provide the required sub-status or rejection reason ID based on the schema requirements.

"Move candidate 10934850 to the 'Interview' stage for Job ID 55512."

List Job Hiring Team

Tool name: smart_recruiters_jobs_hiring_team Returns the list of team members responsible for a specific job requisition, including the hiring manager and assigned recruiters. Useful for identifying who needs to be notified when a candidate advances.

"Who is the hiring manager assigned to the Senior Frontend Developer requisition?"

List SmartRecruiters Offers

Tool name: list_all_smart_recruiters_offers Searches the offer database across the company. You can filter this to check the status of extended offers or view aggregate compensation data for recent hires.

"Show me all offers that are currently in the 'Pending Approval' status."

List SmartRecruiters Users

Tool name: list_all_smart_recruiters_users Retrieves the directory of SmartRecruiters users in your company, including their system roles, language, and SSO login mode. Helpful for auditing access or finding internal employee IDs.

"List all active SmartRecruiters users who have the ADMINISTRATOR role."

To view the complete inventory of available SmartRecruiters endpoints and schemas, visit the SmartRecruiters integration page.

Workflows in Action

Exposing individual ATS endpoints is useful, but the real power of MCP is how ChatGPT chains these tools together to execute multi-step hiring tasks. Here is how standard recruiting workflows operate in practice.

Scenario 1: Automated Screening and Pipeline Advancement

A recruiter wants to review a new batch of applicants and automatically advance those who meet baseline criteria.

"Review the screening answers for candidate 8475691 for the Data Engineer job (ID 99382). If they answered 'Yes' to the Python experience question, move their status to 'Phone Screen'."

How ChatGPT executes this:

1. smart_recruiters_candidates_screening_answers: The agent calls this tool using the provided candidate and job IDs to fetch the raw JSON of the submitted questionnaire.
2. Reasoning Step: ChatGPT parses the JSON, locates the question regarding Python experience, and evaluates the candidate's answer.
3. smart_recruiters_candidates_update_status: Based on a positive evaluation, the agent constructs the payload to move the candidate to the 'Phone Screen' status and executes the API call.

The recruiter gets a confirmation message that the candidate was successfully evaluated and advanced in the ATS pipeline, saving them from clicking through the SmartRecruiters UI.

sequenceDiagram
    participant User as Recruiter
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server
    participant SR as SmartRecruiters API

    User->>ChatGPT: "Review screening answers for candidate 8475691..."
    ChatGPT->>Truto: Call: smart_recruiters_candidates_screening_answers
    Truto->>SR: GET /candidates/8475691/jobs/99382/screening-answers
    SR-->>Truto: JSON (Questionnaire data)
    Truto-->>ChatGPT: Tool response
    Note over ChatGPT: Evaluates Python question<br>Decision: Advance candidate
    ChatGPT->>Truto: Call: smart_recruiters_candidates_update_status
    Truto->>SR: POST /candidates/8475691/jobs/99382/status
    SR-->>Truto: 204 No Content
    Truto-->>ChatGPT: Success
    ChatGPT-->>User: "Candidate advanced to Phone Screen."

Scenario 2: Hiring Manager Status Sync

A hiring manager wants a quick brief on the status of their open requisitions and outstanding offers without logging into the ATS.

"Find all open jobs where I (user ID 44321) am on the hiring team. For those jobs, tell me if there are any pending offers."

How ChatGPT executes this:

1. list_all_smart_recruiters_jobs: The agent queries the jobs list, filtering by status=active and passing the user ID to check the hiring team parameters.
2. Reasoning Step: The agent extracts the Job IDs from the returned list of open requisitions.
3. list_all_smart_recruiters_offers: The agent loops through the identified Job IDs, calling the offers endpoint to fetch any offers currently linked to those specific roles.

The hiring manager receives a clean, summarized list of their active jobs alongside the exact status of any offers currently out to candidates.

Security and Access Control

Connecting an LLM to your ATS requires strict governance. Truto's MCP architecture provides multiple layers of security to ensure ChatGPT only touches the data it is supposed to.

• Method Filtering: You can restrict a server to safe operations. By configuring the MCP server with methods: ["read"], you guarantee the agent can only fetch data (e.g., list, get) and physically cannot execute create, update, or delete requests against SmartRecruiters.
• Tag Filtering: Limit the surface area of the integration. Setting tags: ["candidates", "interviews"] ensures the server only exposes tools related to candidates and interviews, hiding administrative endpoints like users or system roles.
• API Token Authentication: By default, the long MCP URL acts as a bearer token. For enterprise deployments, you can set require_api_token_auth: true. This forces the client to pass a valid Truto API token in the Authorization header, preventing unauthorized access if the URL is ever leaked.
• Ephemeral Servers: If you want to grant an external consultant or a temporary AI agent access to SmartRecruiters, you can pass an expires_at datetime during server creation. Truto schedules a cleanup alarm using Durable Objects that permanently destroys the KV storage and database records at the exact timestamp, ensuring zero lingering access.

Stop Hand-Coding Integration Logic

Building a custom MCP server for SmartRecruiters means writing custom API clients, managing complex OAuth token lifecycles, and constantly updating your schemas to match ATS changes. It is a massive drain on engineering resources.

Truto abstracts this entire layer. By deriving tools dynamically from documentation and mapping them to a normalized JSON-RPC protocol, Truto allows you to treat SaaS integrations as secure, plug-and-play components for your AI agents.