Connect Totango to Claude: Sync Objectives and Touchpoints

If your team uses ChatGPT, check out our guide on connecting Totango to ChatGPT or explore our broader architectural overview on connecting Totango to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling customer success platform like Totango is a significant engineering challenge. You have to manage complex authentication lifecycles, map massive nested JSON schemas into tools that an LLM can actually understand, and handle asynchronous bulk data ingestion patterns. Every time Totango updates an API schema or changes a standard metric calculation, you have to update your server code, redeploy, and validate the LLM's behavior.

If you want to connect Totango to Claude to automate SuccessPlay triggers, sync touchpoint notes, or orchestrate outcome success plans, you need a Model Context Protocol (MCP) server. 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.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Totango, connect it natively to Claude Desktop, and execute complex customer success workflows using natural language.

The Engineering Reality of the Totango 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 enterprise APIs is painful. Totango is built to ingest massive amounts of telemetry data, organize complex customer hierarchies, and drive automated engagement. Its API reflects that complexity.

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

Asynchronous Bulk Ingestion and Status Polling Many of Totango's core endpoints - such as updating account attributes (update_a_totango_accounts_attribute_by_id) or pushing usage data (update_a_totango_usage_by_id) - do not process data synchronously. When you send a payload, the API returns a batch_id and a 202 Accepted status. The data is not yet live. An LLM expects synchronous confirmation. If Claude updates an account attribute and immediately tries to query that account to verify the change, the data will be stale. Your MCP implementation must explicitly expose polling tools (like get_single_totango_status_by_id) and prompt the LLM to wait for a percentComplete of 100 before proceeding.

Schema Immutability on Acceptance When you push users, accounts, or collection data into Totango via its bulk APIs, the updates are irreversible once the batch is accepted. You cannot "undo" an accepted payload. This is highly dangerous when an autonomous AI agent is generating the payload. If Claude hallucinates a nested attribute structure and fires it to Totango, the corrupted data enters the queue. You must strictly constrain the JSON Schema injected into the MCP tool definition so Claude cannot send invalid keys.

Strict Payload Limits on Qualitative Data Customer Success Managers (CSMs) live in Touchpoints. When generating tools to create or update these notes, developers often overlook Totango's hard limits. Touchpoint content is capped at exactly 12,000 characters. If an LLM attempts to dump a massive call transcript into a touchpoint tool without summarizing it first, the API will reject it with a 400 Bad Request. You must build explicit instructions into the tool description telling the model to truncate or summarize inputs before execution.

Architecting the Managed MCP Translation Layer

Truto eliminates the need to build a custom MCP server by acting as the translation layer between Claude and Totango.

When you connect a Totango instance, Truto reads the underlying API definitions and documentation records, automatically deriving a strict JSON Schema for every available operation. These definitions are presented to Claude via a JSON-RPC 2.0 endpoint (/mcp/:token).

The key architectural advantage here is dynamic, documentation-driven tool generation. Tools are not hardcoded. Truto iterates over every endpoint defined in the integration configuration and checks for corresponding documentation records. If an endpoint lacks documentation, it is dropped. This acts as a quality gate, ensuring Claude only sees tools with explicit descriptions and complete query/body schemas.

Furthermore, Truto flattens the input namespace. When Claude calls a tool, it provides a single flat JSON object of arguments. Truto's MCP router dynamically splits these arguments into query parameters and body payloads based on the underlying Totango API schema, executes the request against the proxy API, and packages the result back into an MCP-compliant response block.

Generating the Totango MCP Server

To expose Totango to Claude, you must first generate an MCP server URL. This URL contains a cryptographic token that securely identifies the specific Totango tenant and the configuration filters applied to it. You can generate this URL via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For internal tooling and manual agent setup, the UI is the fastest path.

1. Log into Truto and navigate to the Integrated Accounts page.
2. Select your connected Totango account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., limit to read-only methods, specify tags, set an expiration date).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For enterprise platforms provisioning agents programmatically, you can generate MCP servers on the fly. Make an authenticated POST request to the /integrated-account/:id/mcp endpoint.

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Totango CSM Agent - Read Only",
    "config": {
      "methods": ["read"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API validates that the requested configuration matches at least one available tool, generates a hashed token backed by Cloudflare KV for high-speed edge lookups, and returns the server details:

{
  "id": "mcp_7x8y9z",
  "name": "Totango CSM Agent - Read Only",
  "config": { "methods": ["read"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Security and Access Control

Exposing an enterprise customer success platform to an LLM requires strict guardrails. Truto's MCP architecture provides several layers of access control baked directly into the server configuration:

• Method Filtering: The config.methods array allows you to restrict the server to specific operations. Passing ["read"] limits the LLM to get and list operations, ensuring it cannot overwrite customer objectives or accidentally trigger a SuccessPlay.
• Tag Filtering: The config.tags array allows you to scope the server to specific functional domains. If you only want the agent to analyze Touchpoints, you can restrict the tools to resources tagged with ["touchpoints"].
• Token Expiration: The expires_at field sets a strict TTL (Time To Live) on the server. Once the timestamp passes, Truto's durable objects automatically purge the token from edge KV storage, immediately cutting off LLM access.
• Secondary Authentication: 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 leaked URLs from being abused.

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your AI client. Claude supports MCP natively, requiring no middleware or custom wrappers.

Method 1: Via the Claude UI (Desktop/Web)

If you are using Claude Desktop (or ChatGPT via its Custom Connectors feature), you can add the server directly in the interface.

For Claude:

1. Open Claude Settings.
2. Navigate to Integrations -> Add MCP Server.
3. Paste your Truto MCP URL.
4. Click Add.

For ChatGPT:

1. Navigate to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, add a new server, name it (e.g., "Totango Agent"), and paste the Truto URL.

Method 2: Via Manual Configuration File

If you are configuring Claude Desktop manually or deploying a headless LangChain/LangGraph agent, you can configure the MCP connection using the Server-Sent Events (SSE) transport protocol.

Edit your claude_desktop_config.json file to include the @modelcontextprotocol/server-sse runner, passing the Truto URL as the target:

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

Restart Claude Desktop. The client will perform the MCP handshake (initialize), discover the Totango capabilities, and load the tools into its context window.

Totango Hero Tools for AI Agents

Truto automatically generates tools for every documented resource in the Totango API. Here are 6 high-leverage tools that enable complex customer success automation.

Search Accounts (totango_accounts_search)

This tool allows the LLM to query accounts matching specific criteria using Totango's elastic search syntax. It is the necessary first step in almost any workflow to retrieve the internal account_id required by other tools.

Contextual usage notes: The tool returns an envelope containing response.accounts.hits. The LLM should be instructed to parse this nested array to find the target account.

"Find the Totango account named 'Acme Corp' and return its internal account ID and current health score. Only search for active paying customers."

Create a Touchpoint (create_a_totango_touchpoint)

This tool creates a new touchpoint (note or meeting record) on an account timeline. It is heavily used for logging AI-generated summaries of customer calls or emails.

Contextual usage notes: The content field is strictly limited to 12,000 characters. Always instruct the LLM to summarize large blocks of text before calling this tool.

"Summarize the following email thread with the Acme Corp stakeholders into a concise update, then log it as a new touchpoint on their Totango account using their account ID."

Run a SuccessPlay (totango_successplays_run)

This tool triggers a manual SuccessPlay for a specific account. SuccessPlays in Totango automate task creation and team orchestration based on specific playbooks.

Contextual usage notes: The targeted SuccessPlay must be configured as "manual" and "active" within the Totango UI. The LLM needs the successplayId and accountId.

"The Acme Corp account just dropped below a health score of 40. Trigger the 'Escalation - Red Account' SuccessPlay to alert the enterprise support team."

Create an Objective (create_a_totango_objective)

This tool allows the agent to attach strategic objectives and success plans to a customer account. Objectives track the specific outcomes the customer bought your software to achieve.

Contextual usage notes: The agent can optionally include milestone arrays within the objectiveData payload. HTML markup is not supported in the objective descriptions.

"Create a new objective on the Acme Corp account titled 'Q3 Adoption Rollout' with a target completion date of September 30. Add two milestones: 'Complete Admin Training' and 'Migrate Legacy Data'."

Submit Usage Updates (update_a_totango_usage_by_id)

This tool submits bulk telemetry and product usage updates for users within an account. It is crucial for updating the metrics that drive Totango's health scores.

Contextual usage notes: This is an asynchronous endpoint. The tool accepts up to 1,000 usage records in a batch and returns a batch_id. The data will not be immediately queryable.

"Log 50 'report_exports' and 12 'dashboard_views' for the user john@acmecorp.com in Totango. Acknowledge the returned batch ID and confirm it has been queued."

List Account Events (list_all_totango_events)

This tool retrieves the historical timeline of an account, including past touchpoints, campaign events, and alerts. It provides the LLM with the context needed to answer questions about account history.

Contextual usage notes: Returns a paginated list of events. The LLM can use this to build a briefing document before a customer renewal call.

"Pull the last 30 days of events for the Acme Corp account. Summarize all touchpoints tagged as 'Support Escalation' and list any active tasks."

For the complete inventory of available Totango tools and their exact JSON schema requirements, visit the Totango integration page.

Workflows in Action

By chaining these dynamically generated tools together, Claude can execute multi-step business logic that previously required custom integration code or rigid Zapier flows.

Scenario 1: QBR Briefing and Objective Planning

A Customer Success Manager asks Claude to prepare for a Quarterly Business Review (QBR) and set the agenda based on recent account activity.

"I have a QBR with 'Stark Industries' tomorrow. Find their account, summarize their last 5 touchpoints to tell me what we've been working on, and then create a new objective on their account called 'Q4 Expansion Strategy'."

Step-by-step execution:

1. Claude calls totango_accounts_search with the query "Stark Industries" to retrieve the account_id.
2. Claude calls list_all_totango_events passing the account_id to pull the recent timeline.
3. The model analyzes the event JSON, filters for touchpoints, and generates a plain-text summary.
4. Claude calls create_a_totango_objective using the account_id, injecting the title "Q4 Expansion Strategy" into the payload.

Result: The CSM receives a concise briefing of recent account activity, and the new objective is instantly visible in the Totango UI, ready for the QBR.

sequenceDiagram
    participant CSManager as CS Manager
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Totango as Totango API

    CSManager->>Claude: "Prep QBR for Stark Ind..."
    Claude->>MCP: Call totango_accounts_search
    MCP->>Totango: GET /search/accounts
    Totango-->>MCP: Account ID: 98765
    MCP-->>Claude: Account Data
    
    Claude->>MCP: Call list_all_totango_events (ID: 98765)
    MCP->>Totango: GET /events?account_id=98765
    Totango-->>MCP: Event Array
    MCP-->>Claude: Timeline Data
    
    Claude->>MCP: Call create_a_totango_objective (ID: 98765)
    MCP->>Totango: POST /objectives
    Totango-->>MCP: Success
    MCP-->>Claude: Objective Created
    Claude-->>CSManager: "Briefing complete. Objective created."

Scenario 2: Processing Async Telemetry and Triggering Plays

An automated system or technical account manager asks the agent to log a massive spike in usage for a specific user and alert the team.

"Record that user jane@wayne-ent.com just triggered 500 'api_errors'. Once that batch is submitted, trigger the 'Technical Intervention' SuccessPlay (ID: sp_555) on their account so engineering investigates."

Step-by-step execution:

1. Claude calls totango_accounts_search to find the account associated with the user.
2. Claude calls update_a_totango_usage_by_id, passing the user's email, the api_errors module, and the count of 500.
3. The MCP server returns a batch_id and a 202 Accepted status.
4. Claude calls totango_successplays_run using the retrieved account_id and the provided successplayId (sp_555).

Result: The heavy usage data is queued for asynchronous ingestion by Totango's backend, while the SuccessPlay is immediately triggered, assigning a task to the engineering team.

Handling Totango Rate Limits

When exposing APIs to autonomous agents, rate limits are a critical failure point. LLMs can easily execute loops that burn through API quotas in seconds.

It is important to understand how the MCP translation layer handles this. Truto does not retry, throttle, or apply backoff logic on rate limit errors. If Claude calls a Totango tool and the upstream API returns an HTTP 429 Too Many Requests, Truto passes that 429 error directly back to Claude in the tool execution result.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. It is the responsibility of the caller (the LLM framework, LangChain wrapper, or Claude Desktop agent) to read these normalized headers, recognize the 429 error, and implement the necessary pause or backoff logic before attempting the tool call again.

The Autonomous Customer Success Engine

Connecting Totango to Claude fundamentally changes how Customer Success teams operate. Instead of clicking through tabs to log notes, build objectives, and run SuccessPlays, CSMs can orchestrate their entire book of business through conversational interfaces.

By leveraging a managed MCP server via Truto, engineering teams bypass the massive technical debt of building custom REST wrappers, maintaining OAuth tokens, and managing schema drift. You get secure, documentation-driven tools generated on the fly, ready for any MCP-compatible AI client.