Connect Dvinci to Claude: Manage hiring requests and job postings

If you need to connect Dvinci to Claude to automate applicant tracking, triage hiring requests, manage job postings, or oversee candidate communications, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Dvinci's REST APIs. 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 connecting Dvinci to ChatGPT or explore our broader architectural overview on connecting Dvinci to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling Applicant Tracking System (ATS) like Dvinci is an engineering challenge. You have to handle API authentication lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with strict ATS data validation rules. Every time Dvinci updates an endpoint or deprecates a legacy 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 Dvinci, connect it natively to Claude Desktop, and execute complex hiring workflows using natural language.

The Engineering Reality of the Dvinci 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 ATS APIs is painful. Dvinci is built to manage complex hiring funnels, compliance documents, and organizational hierarchies. Its API reflects that domain complexity.

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

Complex State Transitions for Applications Dvinci enforces strict validation around state transitions. An LLM cannot simply patch an application's status to an arbitrary string like "hired". Status changes often require specific internal enum values or distinct endpoints (like dvinci_applications_change_status or dvinci_applications_move_job_opening). A managed MCP server exposes these specific operational tools with strictly defined schemas, explicitly guiding Claude to provide the correct payload structure rather than guessing the ATS logic.

Handling Resumes and Attachments ATS workflows revolve around documents. Querying a candidate profile is straightforward, but downloading their resume requires interacting with specialized attachment endpoints. You must parse document metadata, handle binary streams, and manage PDF extraction routes (like dvinci_application_attachments_get_pdf). A custom MCP server must abstract this file handling so the LLM can safely request candidate context without crashing on raw binary outputs.

Rate Limits and 429 Error Handling When an AI agent is instructed to "review all applications from last week," it can aggressively loop through pagination cursors, quickly exhausting API quotas. Truto handles this structurally. It is important to note: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When Dvinci 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. This guarantees that your agent framework (or Claude) receives predictable rate limit context and can execute its own backoff logic reliably.

How to Generate the Managed MCP Server

Rather than hand-coding tool definitions, Truto derives them dynamically from the integration's resource configurations and documentation records. A tool only appears in the MCP server if it has a corresponding documentation entry - acting as a quality gate to ensure only well-documented endpoints are exposed to the LLM.

Each MCP server is scoped to a single integrated account. The server URL contains a cryptographic token that encodes the account, tool filters, and expiration time. You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For ad-hoc agent tasks or testing, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Dvinci account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (name, allowed methods like read or write, and expiration date).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For production workflows where you deploy agents programmatically, you can generate MCP servers on the fly.

Make a POST request to /integrated-account/:id/mcp. The API will validate that the integration is AI-ready, generate a hashed token, store it securely, and return a ready-to-use URL.

// Example using TypeScript and fetch
const response = await fetch(
  'https://api.truto.one/integrated-account/<DVINCI_ACCOUNT_ID>/mcp',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TRUTO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Claude Dvinci Recruiter Bot',
      config: {
        methods: ['read', 'write'],
        tags: ['applications', 'jobs']
      },
      expires_at: '2026-12-31T23:59:59Z' // Optional TTL
    })
  }
);
 
const mcpServer = await response.json();
console.log(mcpServer.url); 
// Output: https://api.truto.one/mcp/<secure_token>

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to connect it to your Claude environment. Because the Truto MCP server is fully self-contained in the URL, no additional client-side authentication configuration is required unless you specifically enable it.

Method A: Via the Claude UI

If you are using the Claude desktop app or web interface with custom connector support:

1. Open Claude and navigate to Settings.
2. Click on Integrations or Connectors (depending on your tier).
3. Click Add MCP Server.
4. Paste the Truto MCP URL you generated.
5. Click Add.

Claude will immediately perform a handshake with the Truto server, listing the available Dvinci tools.

(Note: If your team uses ChatGPT, the process is similar: Settings -> Apps -> Advanced settings -> Enable Developer mode -> Add new custom connector).

Method B: Via the Claude Config File

For developers running Claude Desktop locally, you can register the MCP server by modifying the claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) transport package that allows local clients to connect to the remote Truto MCP URL.

Edit your configuration file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "dvinci-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<secure_token>"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The server-sse package will establish a persistent connection to Truto's JSON-RPC 2.0 endpoint.

Security and Access Control

Exposing your ATS to an AI agent requires strict governance. Truto provides four distinct mechanisms to secure your MCP server configuration:

• Method Filtering: Restrict the server to specific operation types. Set methods: ["read"] to allow only get and list operations, ensuring Claude cannot accidentally delete a candidate or publish a draft job posting.
• Tag Filtering: Group tools by functional area. Set tags: ["hiring_requests"] to restrict the server to only those endpoints, blocking access to sensitive core HR or payroll records.
• API Token Authentication: By enabling require_api_token_auth: true, possession of the MCP URL is no longer sufficient. The client must also pass a valid Truto API token in the Authorization header, adding a second layer of identity verification.
• Automatic Expiration: Set an expires_at datetime for short-lived access. Once expired, the underlying KV store automatically purges the token, and subsequent tool calls will be rejected immediately.

Dvinci Hero Tools for Claude

Truto automatically generates descriptive, snake_case tool names derived from Dvinci's API schemas, injecting necessary context (like descriptions and required parameters) directly into the LLM.

Here are 6 high-leverage tools your agents can use to manage Dvinci.

list_all_dvinci_hiring_requests

Retrieves a paginated list of hiring requests. Truto automatically injects limit and next_cursor schema properties, explicitly instructing the LLM on how to iterate through pages without modifying the cursor payload.

"Fetch the 10 most recent hiring requests that are currently in a 'pending approval' state."

get_single_dvinci_hiring_request_by_id

Fetches the complete nested schema for a specific hiring request, including budget metadata, department allocation, and justification notes. The id parameter is automatically enforced as a required field.

"Get the full details for the hiring request with ID req_83921. Who is the requested hiring manager?"

create_a_dvinci_job_opening

Creates a new job opening record in Dvinci. The tool schema enforces required fields like title, department, and location, preventing the LLM from submitting malformed POST requests.

"Draft a new job opening for a Senior Backend Engineer in the Engineering department based in Berlin, using the approved hiring request req_83921 as the baseline."

list_all_dvinci_applications

Retrieves the pipeline of candidates. This is critical for sourcing and triage operations, allowing the agent to filter by specific job openings or statuses.

"List all new applications submitted for the Senior Backend Engineer job opening this week."

dvinci_applications_change_status

Executes a state transition for a candidate. Because this relies on specific internal identifiers, the tool's schema guides the LLM to provide the correct format for the status update payload.

"Update the application status for candidate app_4492 to 'Interview Scheduled'."

list_all_dvinci_application_attachments

Fetches metadata for documents attached to an application, such as resumes, cover letters, or portfolio links.

"Check if candidate app_4492 has uploaded a cover letter attachment."

For the complete list of available operations, including onboarding records, person directories, and org unit management, view the Dvinci integration page.

Workflows in Action

By chaining these tools together, Claude can execute complex, multi-step ATS workflows autonomously.

sequenceDiagram
    participant User as Recruiter
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Dvinci as Dvinci API

    User->>Claude: "Triage new applications for the DevOps role."
    Claude->>Truto: call list_all_dvinci_applications
    Truto->>Dvinci: GET /applications?job=devops
    Dvinci-->>Truto: JSON Candidate List
    Truto-->>Claude: Context returned
    Claude->>Truto: call list_all_dvinci_application_attachments (per candidate)
    Truto->>Dvinci: GET /applications/{id}/attachments
    Dvinci-->>Truto: Attachment Metadata
    Truto-->>Claude: Context returned
    Claude-->>User: Summarizes candidate profiles and resumes

Scenario 1: Approving a Request and Posting a Job

An HR manager wants to move a headcount request forward and immediately draft the external posting.

"Check the status of hiring request req_9921. If it is approved, create a corresponding job opening in Dvinci for 'Product Manager' in the Product department."

1. get_single_dvinci_hiring_request_by_id: Claude queries the request ID to verify the internal approval status.
2. create_a_dvinci_job_opening: Confirming the approval, Claude maps the department and budget data into the request body and posts the new job opening.
3. Result: Claude replies with the ID of the newly created job opening and confirms the task is complete.

Scenario 2: Candidate Triage and Advancement

A recruiter needs to rapidly review a new inbound application and move them to the next stage if they meet basic criteria.

"Look up the most recent application for John Doe. Check his attachments, and if a resume is present, change his application status to 'Screening'."

1. list_all_dvinci_applications: Claude searches for applications matching the candidate's name to retrieve the specific application ID.
2. list_all_dvinci_application_attachments: Using the ID, Claude queries the attachments endpoint to verify a document tagged as 'resume' exists.
3. dvinci_applications_change_status: Validating the criteria, Claude issues a command to advance the candidate's stage.
4. Result: Claude confirms the status has been updated and notes the attachment ID for the resume.

Next Steps

Building custom MCP servers to parse ATS data models and manage OAuth lifecycles drains engineering resources. By using Truto, you replace manual integration coding with dynamically generated, fully authenticated tool sets that instantly surface your Dvinci environment to Claude.

Because Truto normalizes upstream API quirks and securely proxies requests, your developers can focus on prompt engineering and workflow design - not building boilerplate API connectors.