Connect JOIN to Claude: Search Candidates and Analyze Scorecards

If you need to connect JOIN to Claude to automate applicant tracking, extract resumes, coordinate hiring pipelines, or analyze interview scorecards, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between Claude's natural language tool calls and JOIN's REST APIs. You can either build and maintain this infrastructure yourself, dealing with constant endpoint deprecations and authentication drift, 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-join-to-chatgpt-manage-job-postings-and-applications/ or explore our broader architectural overview on /connect-join-to-ai-agents-automate-the-full-recruitment-lifecycle/.

Giving a Large Language Model (LLM) read and write access to a recruitment platform like JOIN is an engineering challenge. You have to handle fragmented API versions, map nested candidate schemas to MCP tool definitions, and deal with JOIN's unique file access patterns. Every time JOIN deprecates a query parameter or updates a resource, 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 JOIN, connect it natively to Claude, and execute complex recruiting workflows using natural language.

The Engineering Reality of the JOIN 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 like JOIN is painful. JOIN is built to manage massive amounts of unstructured candidate data, complex job board syndication, and multi-stage hiring pipelines. Its API reflects that complexity.

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

The Sparse Object Trap and Content Overrides JOIN employs an aggressive data-saving pattern on its collection endpoints. By default, querying the /jobs endpoint returns sparse models - dropping critical fields like description, salary, contactPerson, and attachments. To get the full payload, you must explicitly pass content=true. If your MCP server does not hardcode this override, Claude will hallucinate job details because it simply will not receive them in the JSON response. A managed MCP platform automatically intercepts these read requests and injects the necessary query parameters to ensure the LLM receives complete context.

File Access and Cryptographic Signatures Unlike standard SaaS applications where you can fetch an attachment with a standard Bearer token, downloading candidate resumes in JOIN requires specialized request crafting. When you pull an application, the payload contains a sig signature parameter attached to the file URLs. To actually download the file, your MCP server must extract this specific sig string and the external_file_name, then construct a secondary request to the download endpoint. An LLM cannot navigate this multi-step cryptographic retrieval process without heavily engineered tool schemas.

Mutually Exclusive Filters and Deprecations JOIN frequently iterates on its data models, leading to overlapping filtering logic. For example, when listing applications, the state filter is completely deprecated. Furthermore, you cannot arbitrarily combine filters - stageType can only be queried if hiringState is also explicitly passed. If your MCP server blindly passes LLM arguments to the query string, you will trigger HTTP 400 errors. The MCP translation layer must actively enforce these validation constraints before the request hits the network.

Strict Upstream Rate Limiting (HTTP 429) JOIN imposes strict rate limits to protect its infrastructure, especially on heavy analytical endpoints like candidate notes or scorecard retrieval. It is important to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream JOIN API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (the LLM framework or Claude Desktop) is entirely responsible for implementing retry and exponential backoff logic.

Step 1: Generate the JOIN MCP Server

To bypass these engineering hurdles, you can use Truto to generate a production-ready MCP server for JOIN. The server is dynamic - it derives its tool definitions directly from JOIN's documented API schema, ensuring that only curated, AI-ready endpoints are exposed to the model.

You can spin up this MCP server in two ways: via the Truto User Interface or programmatically via the API.

Method 1: Via the Truto UI

For teams managing integrations manually, the Truto dashboard provides a simple provisioning workflow:

1. Log into your Truto environment and navigate to the Integrated Accounts page.
2. Select your connected JOIN instance.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., allow read and write methods, set an optional expiration date, or filter by specific tags like candidates).
6. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz...).

Method 2: Via the Truto API

For platform engineers building AI features into their own software, MCP servers should be provisioned dynamically. You can create an MCP server scoped to a specific JOIN tenant using a single API call.

// POST /integrated-account/:id/mcp
const response = await fetch('https://api.truto.one/integrated-account/YOUR_JOIN_ACCOUNT_ID/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Claude Recruitment Assistant',
    config: {
      methods: ['read', 'write'],
      tags: ['recruitment', 'candidates']
    },
    expires_at: '2026-12-31T23:59:59Z'
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); 
// Pass this URL to your MCP client or AI agent

This endpoint validates that the integration has documentation-backed tools available, generates a secure hexadecimal token, and registers the server in a globally distributed key-value store. The resulting URL contains everything needed to authenticate the JSON-RPC 2.0 requests from Claude.

Step 2: Connect the MCP Server to Claude

Once you have your Truto MCP server URL, you must connect it to your LLM client. MCP uses a standard JSON-RPC protocol over Server-Sent Events (SSE) or stdio, meaning the client configuration is identical regardless of which SaaS tool you are integrating.

Option A: Via the Claude UI (Web / ChatGPT)

If your organization uses Claude Enterprise, Claude Team, or ChatGPT with developer features enabled, you can add the server directly via the interface:

1. Open Settings -> Integrations (or Connectors in ChatGPT).
2. Click Add Custom Connector or Add MCP Server.
3. Name the connection (e.g., "JOIN Recruitment Sync").
4. Paste the Truto MCP Server URL.
5. Click Save or Add.

The UI will immediately execute the initialize and tools/list handshake, populating your chat interface with JOIN's API capabilities.

Option B: Via Manual Config (Claude Desktop)

If you are running Claude Desktop locally for engineering workflows, you connect the server via your claude_desktop_config.json file. Because Truto MCP servers use HTTP/SSE transport, you must use the official @modelcontextprotocol/server-sse wrapper to bridge the connection.

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": {
    "join_production": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}

Restart Claude Desktop. The application will spawn the SSE proxy, read the tool schemas from Truto, and make them available in your prompt context.

Hero Tools for JOIN Automation

Truto automatically maps JOIN's resources into descriptive, snake_case tools. Below are the highest-leverage operations for recruitment automation.

list_all_join_jobs

Retrieves a complete list of all job postings. Truto automatically injects status=ONLINE,OFFLINE,ARCHIVED and content=true to ensure the LLM receives the full job descriptions, salaries, and office locations without having to guess the query parameters.

"Fetch all active software engineering jobs currently posted in our JOIN account and summarize their salary bands."

create_a_join_application

Adds a new candidate directly to an active job opening. This is highly useful for autonomous sourcing agents that scrape LinkedIn or GitHub and push high-value prospects straight into your applicant tracking system.

"Take this extracted resume data for Jane Doe, format it, and create a new application for the Senior Platform Engineer role (job ID 4912)."

list_all_join_candidates

Searches the global candidate directory across all jobs. This tool supports fuzzy searching by email or name and can embed candidate notes directly in the response, making it perfect for pipeline audits.

"Search our candidate database for anyone with the email domain @example.com and list what roles they applied for."

list_all_join_scorecards

Retrieves all interview feedback submitted for a specific application. It returns the reviewer's identity, overall recommendation, overall impression, and the specific answers to standardized interview questions.

"Pull all the interview scorecards for applicant ID 8831 and give me a summary of the technical team's feedback regarding their system design skills."

get_single_join_application_by_id

Fetches the complete metadata for an application, including the current pipeline stage, hiring state, and crucially, the array of attachments. This tool is required to extract the sig signature needed to download files.

"Get the application details for ID 9923 and locate the external file name and security signature for their resume attachment."

join_application_files_download

Downloads the raw binary file (typically a PDF) attached to an application. The LLM must pass the application_file_id, the external_file_name, and the sig obtained from the application details endpoint.

"Download the resume PDF using file ID 112, signature 'xyZ123', and name 'resume_final.pdf', then extract the text and summarize their work history."

To view the complete API schemas, parameters, and the full inventory of JOIN operations, visit the JOIN integration page.

Workflows in Action

When Claude is equipped with these tools, it can string together multi-step operations that traditionally required custom middleware. Here are two concrete workflows.

Workflow 1: Autonomous Resume Retrieval and Summarization

When a hiring manager asks Claude for a candidate summary, the LLM must navigate JOIN's signature-based file access architecture.

"Find the application for John Smith, download his resume, and summarize his AWS experience."

sequenceDiagram
    participant User as Hiring Manager
    participant Claude as Claude Assistant
    participant MCP as Truto MCP Server
    participant JOIN as JOIN API
    User->>Claude: "Find John Smith's resume..."
    Claude->>MCP: Call list_all_join_applications<br>(query: "John Smith")
    MCP->>JOIN: GET /applications
    JOIN-->>MCP: Returns app ID 7442
    MCP-->>Claude: App metadata
    Claude->>MCP: Call get_single_join_application_by_id<br>(id: 7442)
    MCP->>JOIN: GET /applications/7442
    JOIN-->>MCP: Returns attachments with `sig`
    MCP-->>Claude: JSON array with signature
    Claude->>MCP: Call join_application_files_download<br>(file_id, sig, file_name)
    MCP->>JOIN: GET /application-files/...
    JOIN-->>MCP: Raw PDF bytes
    MCP-->>Claude: File stream
    Claude->>User: "John has 5 years of AWS experience..."

1. Claude calls list_all_join_applications to find the candidate's ID.
2. It calls get_single_join_application_by_id to extract the sig signature and application_file_id.
3. It calls join_application_files_download to bypass the security wall and retrieve the raw PDF.
4. Claude parses the PDF text internally and returns the summary to the hiring manager.

Workflow 2: Interview Feedback Audits

Recruiting coordinators often need to aggregate feedback across multiple interviewers before a debrief meeting.

"Generate a debrief summary for the DevOps Engineer role. Find the top 3 candidates currently in the 'Interview' stage and summarize their scorecards."

sequenceDiagram
    participant User as Recruiter
    participant Claude as Claude Assistant
    participant MCP as Truto MCP Server
    participant JOIN as JOIN API
    User->>Claude: "Generate a debrief summary..."
    Claude->>MCP: Call list_all_join_jobs<br>(title: "DevOps Engineer")
    MCP->>JOIN: GET /jobs?content=true
    JOIN-->>MCP: Returns Job ID 901
    MCP-->>Claude: Job ID
    Claude->>MCP: Call list_all_join_applications<br>(job_id: 901, hiringState: "ACTIVE", stageType: "INTERVIEW")
    MCP->>JOIN: GET /applications
    JOIN-->>MCP: Returns candidate IDs
    MCP-->>Claude: Array of applicants
    Claude->>MCP: Call list_all_join_scorecards<br>(Loop for each app ID)
    MCP->>JOIN: GET /applications/{id}/scorecards
    JOIN-->>MCP: Returns JSON scorecards
    MCP-->>Claude: Reviewer feedback
    Claude->>User: Prints formatted debrief report

1. Claude calls list_all_join_jobs to resolve the job name to an ID.
2. Claude calls list_all_join_applications using the restrictive hiringState and stageType filters to find active candidates in the interview phase.
3. Claude iterates through the results, calling list_all_join_scorecards for each application ID.
4. Claude synthesizes the quantitative ratings and qualitative notes into a final markdown report.

Security and Access Control

Exposing an ATS to an AI agent requires strict governance. Truto's MCP architecture provides several layers of control that are enforced at the translation layer, before the request ever reaches JOIN:

• Method Filtering: You can restrict the server to specific operation types. Setting config.methods: ["read"] ensures the LLM can only query candidates and jobs, structurally preventing it from accidentally creating, updating, or archiving applications.
• Tag Filtering: Tools are automatically grouped by semantic tags (e.g., candidates, jobs, scorecards). You can configure the MCP server to only expose tools matching specific tags, reducing the LLM's context window and limiting its scope.
• Secondary API Authentication: By enabling require_api_token_auth, possession of the MCP URL is no longer sufficient. The LLM client must also pass a valid Truto API Bearer token in the request header, ensuring only authorized corporate systems can trigger workflows.
• Time-to-Live (TTL) Enforcement: You can assign an expires_at ISO datetime when generating the server. Once the timestamp passes, the distributed cache evicts the token, and background alarms instantly sever access - perfect for giving temporary agents access to interview data during a specific hiring sprint.

Strategic Wrap-Up

Connecting Claude to JOIN via an MCP server transforms applicant tracking from a manual administrative chore into a highly automated, conversational workflow. However, building that integration layer from scratch means taking on the burden of JOIN's specific data quirks - managing sig cryptography for file downloads, resolving sparse payloads with content=true, and handling strict 429 rate limits.

By leveraging a managed infrastructure like Truto, you offload the maintenance of REST schemas, authentication lifecycles, and tool generation. You can instantly provision secure, scope-limited MCP servers and focus your engineering efforts on building better AI agents, not maintaining HR tech integrations.