Connect Hightouch to Claude: Control ID Resolution & Decision Logic

If you need to connect Hightouch to Claude to automate Identity Resolution (IDR) pipelines, review and approve sync drafts, or orchestrate complex decision engine flows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Hightouch'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 /connect-hightouch-to-chatgpt-sync-data-models-marketing-sends/ or explore our broader architectural overview on /connect-hightouch-to-ai-agents-manage-events-syncs-destinations/.

Giving a Large Language Model (LLM) read and write access to a Reverse ETL platform like Hightouch is an engineering challenge. You are not just building standard CRUD wrappers. You are giving an AI agent control over the data pipelines that sync your data warehouse directly to your downstream marketing, sales, and support tools. Every time Hightouch updates a complex configuration schema or adds a new parameter to a decision engine flow, 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 Hightouch, connect it natively to Claude Desktop, and execute complex data orchestration workflows using natural language.

The Engineering Reality of the Hightouch API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable JSON-RPC 2.0 interface for models to discover tools, the reality of implementing it against Hightouch's API requires specific domain knowledge. If you decide to build a custom MCP server for Hightouch, here are the specific integration challenges you will face:

Asynchronous Identity Resolution Jobs Hightouch relies heavily on asynchronous processing for computationally expensive operations. When you trigger an Identity Resolution (IDR) run or request a model size calculation, the API does not return the result. It returns a job ID. An LLM has no inherent concept of waiting for a background worker. Your MCP server must expose specific polling tools (like get_single_hightouch_reprocess_status_by_id) and you must rely on the LLM's reasoning engine to recursively check that status until it indicates completion before moving to the next step.

Sync Draft Version Control Hightouch employs a strict review cycle for changes made to syncs in protected workspaces. You cannot simply patch a sync and have it apply immediately. The API creates a sync draft containing current and proposed states. To approve a draft, the API requires passing the expectedDraftVersion and expectedResourceVersion exactly as they were fetched. If either has changed, the approval fails. This prevents race conditions, but it means your MCP tool definitions must strictly guide the LLM to extract those version strings from the get_single_hightouch_sync_draft_by_id response and pass them into the approval tool unmodified.

Deeply Nested Configuration Payloads Creating Event Contracts or Sync Templates in Hightouch requires massive, deeply nested JSON payloads that define exact schemas, allowable fields, and mapping logic. LLMs frequently hallucinate or truncate deeply nested JSON objects if the JSON Schema definitions provided by the MCP server are incomplete or ambiguous. Your server must perfectly map Hightouch's open-ended configuration objects into strict, descriptive schemas so Claude knows exactly what shape the API expects.

How to Create the Hightouch MCP Server

Truto abstracts away the complexity of the Hightouch API. Instead of writing custom JSON-RPC handlers, Truto dynamically derives MCP tools directly from Hightouch's documentation and resource definitions.

You can generate an MCP server scoped specifically to your connected Hightouch account using either the Truto UI or the API.

Method 1: Via the Truto UI

This is the fastest method for testing and ad-hoc agent configuration.

1. Log into your Truto dashboard and navigate to your connected Hightouch Integrated Account page.
2. Click on the MCP Servers tab.
3. Click Create MCP Server.
4. Define your configuration. You can specify a human-readable name, set an expiration date for temporary access, or filter the server to only allow read methods if you want a read-only agent.
5. Click save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For production deployments where you need to programmatically provision MCP servers for your users, use the Truto API. The API validates the configuration, stores a hashed token in a low-latency KV store, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/<HIGHTOUCH_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hightouch Marketing Ops Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": null
  }'

The response contains the secure URL you will pass to Claude:

{
  "id": "mcp_8a9b0c1d2e",
  "name": "Hightouch Marketing Ops Agent",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the MCP Server to Claude

Because Truto issues standard Server-Sent Events (SSE) MCP URLs, you can connect them to any MCP-compliant client immediately. The URL contains the secure token, so no additional headers are required unless you enforce extra authentication.

Connecting via Claude Desktop (Manual Config File)

If you are using Claude Desktop or a custom LangChain/LangGraph architecture running locally, you connect via the configuration file. Truto provides an SSE transport adapter.

Open your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the server:

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

Restart Claude Desktop. The application will initialize the connection, read the available Hightouch tools, and make them available in your chat interface.

Connecting via the UI (ChatGPT / Claude Web)

If your organization uses ChatGPT Developer Mode or Claude's web interface (for Enterprise/Team plans that support remote MCPs), the process requires zero code.

For Claude Web:

1. Go to Settings -> Integrations -> Add MCP Server.
2. Paste your Truto MCP URL.
3. Click Add.

For ChatGPT:

1. Go to Settings -> Apps -> Advanced settings and ensure Developer mode is active.
2. Under Custom connectors, click add.
3. Name the connector "Hightouch (Truto)" and paste the Truto MCP URL.
4. Click Save.

Hightouch Hero Tools for Claude

Truto automatically generates descriptive, snake_case tools from Hightouch's documentation records. The server uses a flat input namespace, meaning the LLM passes all arguments in a single JSON object, and Truto intelligently routes them to the correct query parameters or request body fields based on the schema.

Here are 7 high-leverage tools available for your AI agents.

1. hightouch_idrs_trigger

Identity Resolution (IDR) is the foundation of organizing fragmented user data. This tool initiates a new IDR run for a specific graph in Hightouch. It returns an ID that must be used to poll for status.

"Trigger an Identity Resolution run for the graph ID graph_98765. Give me the run ID so we can track its progress."

2. get_single_hightouch_reprocess_status_by_id

Because IDR jobs are asynchronous, Claude must use this tool to check the job state. The tool returns the current status, queued time, and any associated errors. Claude is smart enough to use this in a loop if you instruct it to "wait until complete."

"Check the status of IDR run idr_12345 for graph graph_98765. If it is still processing, wait 10 seconds and check again until it is finished."

3. create_a_hightouch_run

This tool triggers a decision engine run for a specific decision engine flow. It forces the engine to evaluate the current audience against the flow's rules and queues the resulting actions.

"Trigger a decision engine run for flow ID flow_abc123. Let me know how many flows were successfully enqueued."

4. hightouch_sync_drafts_approve

This is a critical governance tool. When team members propose changes to a sync, a draft is created. Claude can review the draft, and if authorized, execute this tool to approve it. It requires passing the exact draft and resource versions to prevent overwriting parallel changes.

"Approve the sync draft draft_777 on sync sync_888. Make sure to pass expectedDraftVersion 'v2' and expectedResourceVersion 'v5' as required by the schema."

5. update_a_hightouch_sync_template_by_id

For platform engineers managing multiple workspaces, this tool allows updating the configuration of a base sync template. Any syncs created from this template will pick up the new configuration on their next run.

"Update sync template tpl_555. Change the schedule configuration to run every 15 minutes instead of every hour."

6. create_a_hightouch_model_size

Before launching a massive campaign, it is best practice to know the audience size. This tool starts a background job to compute the size of a specific model in the warehouse without extracting the raw rows.

"Start a model size calculation job for model ID mod_999. I need to know how many records are in this audience before we sync it."

7. hightouch_campaigns_trigger

This tool allows the agent to trigger an API-driven campaign send to a specific list of recipients. It is highly useful for integrating Hightouch directly into automated conversational workflows where an LLM determines the user needs a specific email or SMS.

"Trigger the API campaign camp_444 for the recipients defined in this JSON array. Tell me if there are any missing variables rejected by the endpoint."

To view the complete inventory of available tools, required properties, and JSON schemas, visit the Hightouch integration page.

Workflows in Action

Exposing individual tools to Claude is useful, but the true power of MCP lies in giving the LLM the ability to chain these operations together to solve complex problems. Here are two real-world workflows.

Scenario 1: Automating the Sync Draft Approval Cycle

Persona: Data Engineer / Analytics Engineer

Engineers often lock production syncs to prevent accidental overrides. When a marketer proposes a change to a destination mapping, it creates a draft. Claude can automate the review and approval of these drafts based on predefined safety rules.

"Fetch the pending sync draft draft_101 for sync sync_202. Compare the current state with the proposed state. If the only change is adding the field 'last_login_date' to the configuration mapping, approve the draft and then immediately trigger a run for the sync to push the new data."

Execution Steps:

1. Claude calls get_single_hightouch_sync_draft_by_id to retrieve the payload.
2. The LLM analyzes the current and proposed objects inside the response, verifying that the modification is isolated to the approved field.
3. Claude extracts the draftVersion and resourceVersion from the response.
4. Claude calls hightouch_sync_drafts_approve, passing the required IDs and version strings.
5. Once approved, Claude calls hightouch_syncs_trigger to force an immediate run of the updated sync.

flowchart TD
  A["LLM calls<br>get_single_hightouch_sync_draft_by_id"] -->|"Analyzes current vs proposed"| B["LLM extracts<br>version strings"]
  B --> C["LLM calls<br>hightouch_sync_drafts_approve"]
  C -->|"Approval successful"| D["LLM calls<br>hightouch_syncs_trigger"]
  D --> E["Returns sync run ID<br>to user"]

Scenario 2: Synchronized Identity Resolution and Campaign Delivery

Persona: Marketing Operations

Before triggering a critical campaign, you must ensure the underlying user graph has been resolved with the latest warehouse data. Because IDR is asynchronous, Claude handles the polling logic automatically.

"Trigger an identity resolution run for graph graph_505. Wait until the job completes. Once it finishes successfully, trigger the API campaign camp_808 for user 'john.doe@example.com'."

Execution Steps:

1. Claude calls hightouch_idrs_trigger with the graph ID.
2. The server returns a job ID.
3. Claude enters a self-directed loop, repeatedly calling get_single_hightouch_reprocess_status_by_id and evaluating the status field.
4. When the status changes to complete, Claude breaks the loop.
5. Claude calls hightouch_campaigns_trigger, passing the campaign ID and recipient payload.
6. Claude reports the final sendId back to the user.

sequenceDiagram
  participant User as User
  participant Claude as Claude Agent
  participant Truto as Truto MCP Server
  User->>Claude: Run IDR and trigger campaign
  Claude->>Truto: Call hightouch_idrs_trigger(graph_505)
  Truto-->>Claude: Returns job ID
  loop Until Status is Complete
    Claude->>Truto: Call get_single_hightouch_reprocess_status_by_id(job_id)
    Truto-->>Claude: Returns processing status
  end
  Claude->>Truto: Call hightouch_campaigns_trigger(camp_808, recipients)
  Truto-->>Claude: Returns sendId
  Claude-->>User: IDR finished, campaign sent successfully

Security and Access Control

When granting AI models access to your Reverse ETL pipelines, strict governance is non-negotiable. Truto's MCP architecture provides multiple layers of access control built directly into the token lifecycle:

• Method Filtering: Restrict the server to specific operation types. Pass methods: ["read"] during creation to generate an MCP server that only exposes get and list operations, ensuring Claude can query model sizes and run statuses without the ability to trigger syncs or update templates.
• Tag Filtering: Group and isolate tools. You can filter the generated tools by specific resource tags so the agent only sees tools relevant to its persona (e.g., exposing only destinations and syncs tools to a data engineering agent).
• Time-to-Live (TTL): Pass an ISO datetime string to expires_at to create temporary MCP servers. Cloudflare KV automatically invalidates the token, and an asynchronous durable object alarm cleans up the database record, ensuring no stale access points remain.
• Strict Authentication (require_api_token_auth): For maximum security, enable this flag. It forces the calling client to provide a valid Truto API Bearer token in addition to possessing the MCP server URL, preventing unauthorized access if the URL is ever leaked in configuration files.

Handling Rate Limits in Production

When orchestrating aggressive AI workflows, rate limits are a mathematical certainty. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors.

If Claude executes a rapid loop of tool calls and exhausts your Hightouch API limits, the upstream API will return an HTTP 429 Too Many Requests error. Truto passes this 429 error directly back to the calling agent without absorption.

To aid in graceful recovery, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification:

• ratelimit-limit: The total allowed requests in the current window.
• ratelimit-remaining: The number of requests left.
• ratelimit-reset: The timestamp when the quota resets.

The calling MCP client (your agent framework or Claude Desktop) is entirely responsible for reading these headers, implementing exponential backoff, and retrying the tool call.

Moving Beyond Point-to-Point Integration Scripts

Building a custom MCP server for a complex orchestration platform like Hightouch requires mapping dozens of endpoints, handling complex nested configuration schemas, and constantly maintaining version parity with the vendor's API.

By leveraging Truto's dynamic, documentation-driven MCP generation, you eliminate the integration codebase entirely. Your AI agents gain immediate, type-safe access to every supported Hightouch resource, while your engineering team maintains strict control over authentication, method exposure, and data governance.