Connect ChartHop to Claude: Automate Compensation, Bands, and Stock

If your team needs to connect ChartHop to Claude to automate compensation band analysis, model future organizational structures, or streamline time-off approvals, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and ChartHop's 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-charthop-to-chatgpt-manage-org-structure-jobs-and-people/ or explore our broader architectural overview on /connect-charthop-to-ai-agents-sync-time-off-policies-and-ledger-data/.

Giving a Large Language Model (LLM) read and write access to a specialized organizational management system like ChartHop is an engineering challenge. You have to handle OAuth 2.0 or API key token lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with ChartHop's domain-specific data constraints around effective dating and asynchronous snapshots. Every time ChartHop updates an endpoint or deprecates a field, 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 ChartHop, connect it natively to Claude Desktop, and execute complex organizational planning workflows using natural language.

The Engineering Reality of the ChartHop 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. ChartHop is built to manage complex, temporal organizational structures, compensation models, and access controls. Its API reflects that complexity.

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

Effective Dating and Asynchronous Snapshots ChartHop is built on a temporal data model. When you update an organizational structure - like creating a new compensation band or moving a job under a new manager - you are often creating an effective-dated change. Many ChartHop endpoints do not return a standard 200 OK with the updated resource. Instead, they return a 202 Accepted because ChartHop is rebuilding the organizational snapshot in the background. An LLM expects synchronous confirmation. Your MCP server must explicitly document this behavior in the tool description so Claude knows a 202 response means the operation was scheduled, not that it failed to return a body.

Complex Query Filtering and Scenarios ChartHop data exists across multiple dimensions. A "Job" might exist in the current active organization, or it might only exist in a proposed future hiring "Scenario". Querying the API requires passing strict scenario_id and date parameters to fetch the correct context. If an LLM calls a listing endpoint without understanding this, it will fetch the wrong data. Generating proper JSON schemas for MCP tools is critical to guide the LLM to provide the correct query arguments.

Rate Limits and 429 Handling When dealing with bulk reporting or compensation audits, LLMs can generate rapid bursts of API calls. ChartHop enforces strict rate limits. It is important to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream ChartHop API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your LLM orchestration framework (or the agent itself) is entirely responsible for detecting the 429 error, reading the reset header, and applying a retry/backoff strategy.

Dynamic Custom Fields vs. Standard Schema ChartHop relies heavily on custom fields. A person's record might contain standard fields like name and startDate, but custom data like "T-Shirt Size" or "Bonus Target" lives inside dynamic attributes or fieldValues objects. The MCP server must dynamically map the API documentation to the tools it exposes so the LLM understands how to navigate these nested key-value structures without hallucinating properties.

Creating the ChartHop MCP Server

Truto dynamically generates MCP tools based on ChartHop's underlying resource documentation. Because Truto uses proxy APIs, tool calls execute directly against ChartHop's native schemas without a lossy unified mapping layer in between. You can generate a dedicated MCP server for a specific ChartHop tenant in two ways: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For internal tooling and one-off agent deployments, generating the server URL from the dashboard is the fastest path.

1. Log in to your Truto dashboard and navigate to the integrated account page for the connected ChartHop instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict methods to read-only, filter by specific tool tags like "compensation").
5. Copy the generated secure MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz).

Method 2: Via the API

For production applications, multi-tenant AI products, or dynamic agent provisioning, you should create the MCP server programmatically. Truto exposes a REST endpoint to generate secure, short-lived, or filtered MCP servers on the fly.

Make a POST request to /integrated-account/:id/mcp with your configuration.

curl -X POST https://api.truto.one/admin/integrated-accounts/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ChartHop Comp Auditor Agent",
    "config": {
      "methods": ["read", "update"],
      "tags": ["bands", "jobs", "people"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a fully provisioned MCP server URL. The token in this URL is cryptographically hashed and mapped to the specific tenant and configuration in Truto's edge storage.

{
  "id": "mcp_srv_892kln",
  "name": "ChartHop Comp Auditor Agent",
  "url": "https://api.truto.one/mcp/d7f8g9h0j1k2..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you can connect it to your Claude environment. Since the URL encapsulates the tenant routing and authentication, you do not need to configure OAuth or API keys on the client side.

Method A: Via the Claude Desktop UI (or ChatGPT)

If you are using Claude's web interface (if supported in your tier) or setting up a custom GPT in ChatGPT:

1. Open your AI client settings (e.g., Settings -> Integrations -> Add MCP Server in Claude, or Settings -> Connectors -> Add in ChatGPT).
2. Name the integration (e.g., "ChartHop Prod").
3. Paste the Truto MCP URL.
4. Click Add. The client will automatically send an initialize JSON-RPC request to discover all available ChartHop tools.

Method B: Via Manual Config File (Claude Desktop)

If you are running Claude Desktop locally and want to connect it via the configuration file, you will use the official MCP SSE transport module. Truto provides an HTTP SSE endpoint out of the box.

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

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

Restart Claude Desktop. The agent will read the config, establish an SSE connection to Truto, and pull down the ChartHop tool definitions.

Hero Tools for ChartHop Workflows

Truto automatically derives tools from the ChartHop API documentation, ensuring strict adherence to parameter types and required fields. Here are the most powerful tools your AI agent can leverage for organizational management.

1. list_all_chart_hop_people

This tool retrieves the core directory of employees in a ChartHop organization. It supports search, date filtering (to view the roster at a specific point in time), and configurable field selection. It is the starting point for almost all HR-related AI workflows.

"Claude, pull a list of all active people in the ChartHop organization, focusing on their names and start dates."

2. list_all_chart_hop_bands

Accessing compensation bands is critical for pay equity analysis and financial modeling. This tool returns the compensation bands for an organization, which can be filtered by job tier, job level, or effective date. The LLM can use this data to audit if employees fall outside their designated bands.

"Fetch all compensation bands for the engineering department. I need to see the baseCompMin, baseCompMid, and baseCompMax for Job Level 3."

3. list_all_chart_hop_jobs

Jobs in ChartHop represent the seats in the organization, whether they are filled, vacant, or planned for a future scenario. This tool allows the LLM to query the reporting structure, search for open headcount, and filter by scenario.

"Retrieve the list of all jobs currently marked as open headcount in the Q4 Hiring Plan scenario."

4. update_a_chart_hop_job_by_id

When remodeling an organization, the agent must update job parameters. This tool modifies an existing job record. Because ChartHop handles structural changes asynchronously, this tool often returns a 202 Accepted response. The LLM is prompted via the tool schema to understand that the snapshot is building.

"Update job ID 'job_12345' to change the title to 'Senior Backend Engineer' and set the target compensation to the new band. Acknowledge that the change might take a few moments to reflect in the active snapshot."

5. list_all_chart_hop_timeoffs

This tool retrieves time-off requests, filterable by person and date range. Agents can use this to build out-of-office summaries, check pending approvals, or audit leave balances against organizational policies.

"List all pending time-off requests for the next 30 days so I can prepare an approval summary for the executive team."

6. chart_hop_timeoffs_approve

Agents can act on operational workflows by approving pending time-off requests. This tool takes the organization ID and the specific time-off ID. It returns an empty 204 response on success.

"Approve the pending time-off request ID 'to_9876' for next week."

7. create_a_chart_hop_band

For financial planning scenarios, an agent might need to draft new compensation bands based on market research. This tool creates a new comp band. It requires parameters like label, color, baseInterval, and jobLevel.

"Create a new compensation band labeled 'Data Science L4 - US Remote' with a base interval set to monthly and attach it to job level 4."

To view the complete inventory of available ChartHop tools, query parameters, and detailed JSON schemas, visit the ChartHop integration page.

Workflows in Action

Connecting ChartHop to Claude via MCP unlocks powerful, multi-step organizational workflows that previously required manual data exporting and spreadsheet crunching.

Scenario 1: Compensation Equity Audit

An HR business partner wants to ensure that all current employees in a specific department are being paid within their designated compensation bands. The LLM acts as an analytical auditor.

"Claude, pull all the active compensation bands for the engineering team. Then, get a list of all engineering personnel and their current base compensation. Cross-reference their pay against the bands and highlight anyone who is currently falling below the baseCompMin or above the baseCompMax."

Execution Steps:

1. Claude calls list_all_chart_hop_bands to retrieve the minimum, midpoint, and maximum base compensation values for all engineering job levels.
2. Claude calls list_all_chart_hop_people to retrieve the current employee roster, looking specifically at their attached job roles and current base pay attributes.
3. The agent processes the two datasets in its context window, mapping employees to their respective bands.
4. Claude generates a formatted markdown table highlighting outliers and suggesting corrective compensation adjustments based on the target midpoints.

sequenceDiagram
  participant Claude as Claude Desktop
  participant MCP as Truto MCP Server
  participant ChartHop as ChartHop API

  Claude->>MCP: Call list_all_chart_hop_bands
  MCP->>ChartHop: GET /v1/org/{orgId}/compband
  ChartHop-->>MCP: Return band schema
  MCP-->>Claude: JSON Array of bands

  Claude->>MCP: Call list_all_chart_hop_people
  MCP->>ChartHop: GET /v1/org/{orgId}/person
  ChartHop-->>MCP: Return personnel data
  MCP-->>Claude: JSON Array of people

Scenario 2: Future Headcount Planning

A department head is planning next quarter's budget and wants to adjust the reporting structure in a future scenario.

"Claude, pull the list of jobs in the 'Q3 Reorg' scenario. Find the vacant 'Marketing Manager' role and update it to report to the 'VP of Growth' instead of the 'CMO'."

Execution Steps:

1. Claude calls list_all_chart_hop_jobs, passing the specific scenario_id for 'Q3 Reorg' in the query parameters to ensure it is not mutating the active organization.
2. The agent identifies the job_id for the vacant Marketing Manager and the job_id for the VP of Growth.
3. Claude calls update_a_chart_hop_job_by_id, passing the Marketing Manager's ID and updating the manager relationship to point to the VP of Growth.
4. The agent receives a 202 Accepted response and informs the user that the job update has been scheduled and the scenario snapshot is currently building in ChartHop.

flowchart TD
  A["Claude requests jobs<br>for specific scenario"] -->|list_all_chart_hop_jobs| B["Truto MCP Server"]
  B -->|"GET /v1/org/{id}/job"| C["ChartHop API"]
  C -->|Return Job Array| B
  B -->|JSON payload| A
  A -->|update_a_chart_hop_job_by_id| B
  B -->|"PATCH /v1/org/{id}/job/{jobId}"| C
  C -->|202 Accepted| B
  B -->|Success context| A```

### Scenario 3: Time-Off Triage and Delegation

A manager wants to quickly review and approve pending vacation requests before the end of the week.

> "Claude, check all pending time-off requests for my direct reports. If their requested dates don't overlap with the major product launch next week, approve them."

**Execution Steps:**
1. Claude calls `list_all_chart_hop_timeoffs` to gather all pending requests.
2. The agent analyzes the `startDate` and `endDate` fields against the user's provided constraint (the product launch week).
3. For each non-overlapping request, Claude iterates and calls `chart_hop_timeoffs_approve`, passing the specific `timeoff_id`.
4. Claude provides a summary to the user detailing which requests were approved and which were held back due to the launch constraint.

## Security and Access Control

Exposing sensitive HR and compensation data to an AI model requires strict governance. Truto's MCP architecture provides several layers of security to ensure agents only access what they are permitted to see:

*   **Method Filtering:** When creating the MCP token, you can restrict operations. Setting `config.methods` to `["read"]` ensures the agent can query compensation bands and directories but cannot execute `create`, `update`, or `delete` operations.
*   **Tag Filtering:** You can restrict the server to specific domains. Using `config.tags` like `["timeoff"]` ensures the LLM only has access to time-off tools, completely hiding compensation and job structures.
*   **Extra Authentication Layer:** By enabling `require_api_token_auth: true`, possession of the MCP URL is no longer sufficient. The connecting client must also pass a valid Truto API token in the Authorization header, preventing unauthorized use if the URL is leaked.
*   **Automatic Expiration:** For temporary access (e.g., a one-off audit task), you can set `expires_at` during server creation. Truto utilizes edge storage expiration mechanisms to automatically invalidate the token at the exact second requested, ensuring zero stale access.
*   **No Data Retention:** Truto acts purely as a proxy. Tool execution calls are passed directly to ChartHop. Truto does not cache your organizational structure, compensation data, or employee records.

## Moving Beyond Manual HR Operations

Connecting ChartHop to Claude shifts organizational planning from a manual, spreadsheet-heavy chore into a conversational, intent-driven workflow. By leveraging a managed MCP server, your engineering team avoids the headache of building OAuth flows, managing ChartHop's complex API schemas, and handling token refreshes.

With Truto handling the infrastructure, you can focus on building sophisticated AI agents that understand your company's temporal data structures, audit compensation fairly, and automate routine HR tasks securely.