Connect Gorgias to Claude: Sync Customer Data and Support Macros

If you are engineering an AI-driven support operation, you need to connect your Gorgias instance to your Large Language Model (LLM) framework. You can achieve this using a Model Context Protocol (MCP) server, which translates LLM tool calls into executed REST API requests. You can either build and maintain the necessary infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses OpenAI, check out our guide on connecting Gorgias to ChatGPT or explore our broader architectural overview on connecting Gorgias to AI Agents.

Giving Claude read and write access to a specialized e-commerce helpdesk like Gorgias is an intense engineering challenge. You must handle OAuth 2.0 token lifecycles, map deep, nested JSON schemas to MCP tool definitions, and deal with vendor-specific rate limits and asynchronous job handling. Every time Gorgias updates an endpoint or deprecates a legacy field, you are responsible for updating your server code, redeploying, and testing the integration to ensure your AI agents do not fail silently.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Gorgias, connect it natively to Claude, and execute complex support triage workflows using natural language prompts.

The Engineering Reality of the Gorgias API

A custom MCP server is a self-hosted translation layer. While the open MCP standard provides a predictable, standardized way for models like Claude 3.5 Sonnet to discover and utilize tools, the reality of implementing it against vendor APIs is consistently painful. You are not just building to the MCP spec - you are building to the Gorgias API spec.

If you decide to build a custom MCP server for Gorgias from scratch, you own the entire API lifecycle. Here are the specific, localized challenges you will face when working with the Gorgias ecosystem:

Asynchronous Job Processing Gorgias leans heavily on asynchronous background jobs for intensive tasks, bulk updates, and complex data exports. When an LLM triggers one of these endpoints, the API does not return the finished result. It returns a job_id. Your MCP server must be intelligent enough to instruct the LLM that the operation is pending, provide the job_id, and expose a secondary polling tool so the LLM can check the status. Building this state-awareness into a custom MCP server requires writing complex, custom instruction layers. Truto exposes these job endpoints directly and explicitly documents the asynchronous behavior in the tool description, ensuring the LLM knows exactly how to handle the status lifecycle.

Separation of Tickets, Messages, and Tags In Gorgias, a ticket is merely a container. The actual context of the conversation lives in messages, and metadata lives in separate tag objects. If an LLM needs to understand why a customer is angry, it cannot just fetch the ticket object - it must fetch the ticket, iterate through the associated messages, and evaluate the applied tags. Gorgias requires you to interact with specific endpoints like list_all_gorgias_messages or create_a_gorgias_ticket_tag. Passing these deeply nested, interrelated schemas back and forth to Claude without blowing up the context window requires aggressive schema trimming and normalization.

Explicit Rate Limiting Mechanics Gorgias enforces strict rate limits based on your subscription tier. When an AI agent gets stuck in a loop trying to summarize 500 tickets simultaneously, the API will aggressively return 429 Too Many Requests. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors automatically. When the Gorgias 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 - your application or the LLM framework - is entirely responsible for reading these headers and implementing intelligent retry or exponential backoff logic.

Instead of building all of this boilerplate from scratch, you can use Truto to handle the authentication, schema mapping, and tool generation dynamically.

How to Generate a Gorgias MCP Server with Truto

Truto dynamically generates MCP tools based on the existing documentation and resource definitions of your connected integrations. This means the tool generation is documentation-driven - if an endpoint exists and is documented, it becomes an available AI tool.

You can generate an MCP server for your connected Gorgias account in two ways: via the Truto dashboard or programmatically via the API.

Method 1: Via the Truto UI

For teams managing integrations manually or testing agent workflows, the UI provides a fast path to a working server.

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select the specific Gorgias connection you want to expose to Claude.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure your server by giving it a name, selecting allowed methods (e.g., restricting it to read operations for safety), and applying any tag filters.
6. Click save and copy the generated MCP server URL. It will look something like https://api.truto.one/mcp/a1b2c3d4e5f6....

Method 2: Via the Truto API

For engineering teams building multi-tenant AI products, you need to provision MCP servers dynamically. You can hit the Truto REST API to validate the integration, generate a secure token, and retrieve the server URL programmatically.

Endpoint: POST /integrated-account/:id/mcp

Request Body:

{
  "name": "Gorgias Triage Agent",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["support", "crm"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

The API will securely hash the token, store it in high-speed KV storage for rapid authentication routing, and return the ready-to-use URL:

{
  "id": "mcp_8f7d6e5c",
  "name": "Gorgias Triage Agent",
  "config": { "methods": ["read", "write", "custom"], "tags": ["support", "crm"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP server URL, connecting it to Claude requires zero custom code. Because the URL contains a cryptographic token that securely identifies the exact Gorgias tenant, no additional OAuth configuration is needed on the client side.

Method A: Via the Claude UI (Custom Connectors)

If you are using Claude Desktop or the Claude Web interface on an eligible plan (Free, Pro, Team, or Enterprise), you can add the server directly via the interface.

1. Copy your MCP server URL from Truto.
2. In Claude, navigate to Settings -> Connectors -> Add custom connector.
3. Paste the URL into the configuration field and click Add.
4. Claude will immediately send an initialize JSON-RPC request to the URL, discover the available Gorgias tools, and make them available for natural language prompting.

Method B: Via Manual Config File

For advanced users, local development, or specific agent frameworks, you can connect to the remote Truto URL using Claude Desktop's configuration file. Because Truto's MCP servers communicate over HTTP POST, you will utilize the standard SSE (Server-Sent Events) transport wrapper provided by the MCP specification.

Open your claude_desktop_config.json file (typically located in your application support or appdata folder) and add the following block:

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

Restart Claude Desktop. The client will establish a connection to Truto, and you are ready to start automating support ops.

Gorgias Hero Tools for Claude

Truto generates dozens of tools for the Gorgias integration. Instead of overwhelming the LLM with generic endpoints, we derive tools specifically mapped to the high-leverage actions support teams actually perform. Here are the hero tools you should prioritize in your AI workflows.

list_all_gorgias_tickets

This tool retrieves a paginated list of support tickets. It is the primary discovery mechanism for triage agents. It supports aggressive filtering, allowing Claude to search by customer_id, status, trashed state, or specific ticket_ids. This tool handles the pagination parameters (limit, next_cursor) implicitly, instructing Claude to pass cursors back unchanged to iterate through large queues.

"Find all unassigned tickets created in the last 24 hours that are currently marked as open."

get_single_gorgias_ticket_by_id

When Claude needs deep context, this tool fetches the absolute state of a specific ticket. The returned payload includes the ticket ID, current status, channel data, associated customer information, applied tags, and the internal metadata required to make routing decisions. It acts as the anchor point before attempting to write data back to Gorgias.

"Analyze ticket ID 847291. Summarize the customer's core complaint and tell me which agent is currently assigned."

create_a_gorgias_message

Tickets are containers; messages are the actual communication. This tool allows Claude to draft and insert a message into an existing ticket thread. It requires the ticket_id and accepts rich payloads, including body_html or body_text, the sender's identity, and channel specifics. This is the execution tool for AI auto-replies.

"Draft a polite response to ticket 847291 apologizing for the shipping delay, and send it as a public reply via email."

get_single_gorgias_customer_by_id

Support is impossible without context. This tool retrieves a comprehensive profile of a specific customer using their ID. It returns essential e-commerce context, including their email, external IDs (useful for cross-referencing Shopify data), timezone, language preferences, and historical integration data.

"Look up the profile for customer ID 99283. What timezone are they in, and do they have any special VIP tags in their external data?"

list_all_gorgias_macros

Gorgias Macros are powerful, pre-configured actions that apply tags, update statuses, and insert template text simultaneously. This tool allows Claude to discover the exact macros available in the workspace. By retrieving the macro library, the LLM can decide which pre-approved business logic to apply to a specific ticket without hallucinating tag names.

"List all available macros related to 'Refunds' or 'Returns' so I can see what our standard operating procedures are."

update_a_gorgias_ticket_field_by_id

Enterprise teams use custom fields to track specific product lines, RMA numbers, or escalation tiers. This tool allows Claude to specifically target and mutate custom data on a ticket without overwriting the entire object. It requires the ticket_id and the specific field definitions.

"Update the custom field 'Escalation Tier' on ticket 847291 to 'Level 2' and change the 'Defect Type' field to 'Hardware'."

To view the complete inventory of available Gorgias tools, JSON schemas, and parameter definitions, refer to the Gorgias integration page.

Workflows in Action

Giving Claude access to individual tools is useful, but the true power of MCP lies in orchestrating multi-step workflows. Here is how specialized personas can execute complex operations using natural language.

Scenario 1: Automated Triage & Macro Application

Persona: Support Operations Lead

A massive influx of tickets has hit the queue regarding a specific product defect. The operations lead wants the AI agent to find relevant tickets, apply the correct organizational tags via a macro, and draft the initial response.

"Find the most recent open ticket from sarah@example.com complaining about the broken zipper. Read the ticket, apply the standard 'Defect Return' macro, and then send a public reply to the customer with instructions on how to print their return label."

Step-by-step execution:

1. Claude calls list_all_gorgias_tickets with a search filter for the customer's email to locate the exact ticket ID.
2. Claude calls get_single_gorgias_ticket_by_id to read the context and confirm it matches the zipper complaint.
3. Claude calls list_all_gorgias_macros to search for the exact ID of the 'Defect Return' macro.
4. Claude calls update_a_gorgias_ticket_by_id to apply the macro logic and update the ticket status to 'pending'.
5. Claude calls create_a_gorgias_message to insert the finalized HTML response into the thread.

Result: The customer receives a standardized response immediately, and the ticket is correctly categorized in the Gorgias backend without human intervention.

Scenario 2: Customer Data Enrichment & Survey Auditing

Persona: CX Data Analyst

The CX team needs to audit a VIP customer who recently threatened to churn, ensuring their profile is updated to reflect negative satisfaction scores.

"Look up customer ID 104857. Check all of their recent satisfaction surveys. If they gave us a score of 3 or lower on any survey, update their customer profile notes to flag them as a 'High Churn Risk' and append the date."

Step-by-step execution:

1. Claude calls get_single_gorgias_customer_by_id to retrieve the current state of the customer's profile and their existing notes.
2. Claude calls list_all_gorgias_surveys filtering by customer_id to pull their historical CSAT data.
3. The LLM evaluates the JSON response, iterating through the score fields. It identifies a recent score of 2.
4. Claude calls update_a_gorgias_customer_by_id to patch the customer profile, appending " [FLAG: High Churn Risk based on recent CSAT - 2026-10-14]" to the note field.

Result: The customer profile is immediately enriched with actionable intelligence based on cross-referenced survey data, preparing the account management team for intervention.

Security and Access Control

Exposing an enterprise helpdesk to an AI agent requires strict governance. Truto MCP servers implement multiple layers of security to ensure Claude only accesses what it should.

• Method Filtering: You can enforce strict boundary conditions by configuring the server to only accept read operations (like get and list). If Claude attempts to hallucinate a delete command, the MCP router instantly blocks the execution.
• Tag Filtering: By leveraging integration tool tags, you can restrict the MCP server to specific functional domains. For example, setting config.tags: ["support"] ensures Claude can access tickets and macros, but absolutely cannot access or mutate billing or account settings.
• require_api_token_auth: By default, the cryptographically hashed URL acts as the authentication vector. For highly secure environments, enabling this flag forces the MCP client to also pass a valid Truto API token via a Bearer header. This guarantees that possessing the URL is not enough; the caller must be a fully authenticated user.
• expires_at: For temporary agent tasks or external contractors, you can append an ISO datetime to the server creation request. Truto utilizes Cloudflare KV expirations and Durable Object alarms to permanently delete the server token the second it expires, eliminating stale access vectors.

Moving Past Manual Support Workflows

Connecting Gorgias to Claude transforms your helpdesk from a static repository of angry emails into a programmable, reasoning-capable engine. By utilizing a managed MCP layer like Truto, you bypass the brutal engineering realities of token refresh failures, unhandled rate limit spikes, and brittle schema mappings.

Instead of wasting engineering sprints writing boilerplate API wrappers to parse Gorgias job statuses or ticket pagination, your team can focus on orchestrating sophisticated agent workflows that actually reduce resolution times and improve customer satisfaction.

Current relatedPosts: ["managed-mcp-for-claude-full-saas-api-access-without-security-headaches","connect-zendesk-to-claude-manage-help-center-content-knowledge","the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026"]