Connect Ada to Claude: Manage Article Libraries and End Users

If you need your AI agents to manage knowledge bases, triage end-user data, and execute live conversation handoffs, you need a stable connection between Claude and your Ada instance. If your team uses ChatGPT, check out our guide on connecting Ada to ChatGPT or explore broader agentic architectures in connecting Ada to AI Agents.

Giving a Large Language Model (LLM) read and write access to a complex enterprise CX platform like Ada requires an integration layer that can handle complex state machines, strict JSON schema validation, and asynchronous processing. You can either spend engineering cycles building and maintaining a custom Model Context Protocol (MCP) server, 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 managed MCP server for Ada, connect it natively to Claude, and execute complex support and content management workflows using natural language.

The Engineering Reality of the Ada API

A custom MCP server translates an LLM's tool calls into REST API requests. While the open MCP standard provides a predictable way for Claude to discover tools, implementing it against the Ada API presents specific engineering challenges.

If you build a custom MCP server for Ada, you own the entire API lifecycle. You must map massive JSON schemas to MCP tool definitions, handle authentication lifecycles, and deal with Ada's specific behavioral quirks. Here are the realities of integrating with Ada:

Asynchronous State Changes and Eventual Consistency Ada handles heavy operations - like deleting knowledge sources or bulk deleting articles - asynchronously. When you issue a delete command for a knowledge source, the API immediately returns a 204 No Content response, indicating the request was accepted. However, the actual deletion happens in the background. If Claude immediately attempts to verify the deletion by querying the list of sources, the source might still appear, causing the model to hallucinate a failure or attempt the deletion again. Your integration layer must account for this eventual consistency.

Strict Conversation State Machines Ada conversations are not simple message logs; they operate on strict state machines. A conversation exists in active, handoff, or ended states. You cannot append messages or trigger certain actions if the conversation is in the wrong state. Ending a handoff to return control to the AI Agent requires calling specific endpoints (/v2/conversations/{conversation_id}/end_handoff) that also trigger CSAT logic and process leftover blocks. Exposing these complex state requirements to Claude without strict schema guidance often results in invalid requests and 400 Bad Request errors.

Mutually Exclusive Filters and Strict Timestamps Ada enforces rigid querying parameters. For example, when listing exported conversations or messages, the created_since and updated_since filters are mutually exclusive. Furthermore, if you omit an end date, the API strictly enforces a 7-day window from the start date. Timestamps must be exact ISO 8601 UTC strings ending with a literal 'Z'. If your MCP server simply passes Claude's raw timestamp generations, the Ada API will reject them. Truto normalizes these requirements into strict JSON schemas within the MCP tool definitions, guiding Claude to produce valid payloads.

Rate Limits and 429 Handling It is critical to note how rate limits function in this architecture. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Ada API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - Claude Desktop or your custom agent framework - is entirely responsible for reading these headers and implementing retry and exponential backoff logic. Do not expect the MCP server to magically absorb these limits.

How to Generate an Ada MCP Server with Truto

Truto eliminates the need to hand-code MCP tool definitions. Instead, it dynamically derives tools from the integration's resource definitions and human-readable documentation. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring only curated, high-quality endpoints are exposed to Claude.

Each MCP server is scoped to a single connected Ada instance (an integrated account). The server URL contains a cryptographically signed token that authenticates requests, meaning the URL alone is sufficient to connect your client.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For teams testing configurations manually, the UI provides a straightforward generation path.

1. Navigate to the integrated account page for your Ada connection in the Truto dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict to specific tags like "knowledge" or "conversations").
5. Copy the generated MCP server URL.

Method 2: Via the REST API

For production deployments, you can dynamically provision MCP servers for your users via the Truto API. This validates that the integration is AI-ready, generates a secure token stored in a distributed key-value 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/<your_integrated_account_id>/mcp \
  -H "Authorization: Bearer <your_truto_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Knowledge Admin MCP",
    "config": {
      "methods": ["read", "write"],
      "tags": ["knowledge"]
    }
  }'

The API returns a payload containing the secure connection URL:

{
  "id": "ada-mcp-8f92a",
  "name": "Ada Knowledge Admin MCP",
  "config": { "methods": ["read", "write"], "tags": ["knowledge"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890abcdef..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your Claude environment. All communication happens over HTTP POST utilizing JSON-RPC 2.0 messages.

Method A: Via the Claude UI

If you are using Claude Desktop or Claude for Enterprise, you can add the connector directly through the graphical interface.

1. Copy the MCP server URL generated by Truto.
2. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
3. Paste the URL and click Add.

Claude will perform an initialization handshake, fetching the list of available Ada tools. No further configuration is required.

Method B: Via Manual Configuration File

For developers running custom environments or local agents, you can configure the server using a JSON configuration file. Add the following to your claude_desktop_config.json file, using the @modelcontextprotocol/server-sse package to handle the Server-Sent Events transport:

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

Hero Tools for Ada Automation

When Claude connects to the Ada MCP server, it gains access to specific tools derived directly from Ada's REST APIs. Here are the most high-leverage tools available for automating your CX operations.

Get End User Data

Tool Name: get_single_ada_end_user_by_id

This tool retrieves a specific Ada end user by their unique identifier. It returns the user's profile data, external IDs, and timestamps. This is foundational for any agent tasked with analyzing customer history or resolving identity discrepancies.

"Retrieve the profile data for Ada end user ID 'usr_01H9X...' and tell me what timezone they are currently assigned to in their metadata."

List Knowledge Articles

Tool Name: list_all_ada_knowledge_articles

This tool lists knowledge articles within your Ada instance, allowing filtering by ID, enabled status, language, knowledge source, or tags. It returns a paginated list of up to 100 articles per page, including the article name, content, and URL.

"List all active knowledge articles in Spanish related to the 'billing' tag, and summarize the key troubleshooting steps for failed payments."

Update Knowledge Source

Tool Name: update_a_ada_knowledge_source_by_id

This tool updates the name and configuration of an existing knowledge source. It requires the source ID and returns the updated status. This is critical for agents managing data ingestion pipelines into Ada.

"Update the knowledge source ID 'ks_892b' to have the name 'Q3 Product Documentation Hub' and confirm the new status."

Retrieve Conversation Context

Tool Name: get_single_ada_conversation_by_id

This tool fetches a single Ada conversation by its ID. It returns the current state (e.g., active, handoff, closed), the associated channel, end user ID, and conversation metadata. Claude uses this to understand the context of an interaction before taking action.

"Fetch the details for conversation ID 'conv_55Xq' and tell me if the conversation is currently in a handoff state."

Send a Conversation Message

Tool Name: create_a_ada_conversation_message

This tool appends a new message to an existing Ada conversation. It requires the conversation ID, the author, and the content payload. Claude can use this to draft replies, leave internal notes, or communicate directly with the end user.

"Add an internal note to conversation 'conv_55Xq' stating that the user's account has been successfully upgraded, authored by 'System Admin'."

Execute Conversation Handoff

Tool Name: create_a_ada_conversation_end_handoff

This tool ends a handoff state for a specific conversation, returning control back to the Ada AI Agent without closing the entire conversation. It automatically triggers CSAT logic for the human agent and processes any leftover workflow blocks.

"The human agent has resolved the issue for conversation 'conv_55Xq'. Execute the end handoff process to return the user to the automated bot flow."

For the complete inventory of available tools, query schemas, and response formats, visit the Ada integration page.

Workflows in Action

Once Claude is connected to the Ada MCP server, you can orchestrate complex, multi-step workflows. Here are concrete examples of how an AI agent navigates the Ada API.

Workflow 1: Knowledge Base Audit and Cleanup

Content managers frequently need to audit outdated articles across various knowledge sources. Claude can automate this discovery and cleanup process.

"Find all English knowledge articles currently associated with the 'Legacy V1' knowledge source. Summarize their titles for me, and if there are fewer than 5, go ahead and delete the knowledge source entirely."

1. list_all_ada_knowledge_sources: Claude queries the available sources to find the ID corresponding to "Legacy V1".
2. list_all_ada_knowledge_articles: Using the retrieved source ID, Claude requests all articles filtered by English and that specific source.
3. delete_a_ada_knowledge_source_by_id: Seeing there are only 3 articles, Claude executes the delete command on the knowledge source (which also handles deleting the related articles asynchronously).

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

    Claude->>Truto: call_tool("list_all_ada_knowledge_sources")
    Truto->>Ada: GET /v2/knowledge/sources
    Ada-->>Truto: 200 OK (Source List)
    Truto-->>Claude: JSON Tool Result
    
    Claude->>Truto: call_tool("list_all_ada_knowledge_articles", { source_id: "ks_123" })
    Truto->>Ada: GET /v2/knowledge/articles?knowledge_source_id=ks_123
    Ada-->>Truto: 200 OK (Article List)
    Truto-->>Claude: JSON Tool Result

    Claude->>Truto: call_tool("delete_a_ada_knowledge_source_by_id", { id: "ks_123" })
    Truto->>Ada: DELETE /v2/knowledge/sources/ks_123
    Ada-->>Truto: 204 No Content
    Truto-->>Claude: JSON Tool Result

Workflow 2: CX Ticket Context and Resolution

Support engineers often need to jump into a conversation, understand the user's history, leave a resolution message, and close out the state.

"Look up conversation 'conv_99Y', fetch the profile of the end user involved to check their subscription tier, send a message confirming their refund has been processed, and then end the handoff to return them to the bot."

1. get_single_ada_conversation_by_id: Claude retrieves the conversation data, isolating the end_user_id.
2. get_single_ada_end_user_by_id: Claude queries the user profile to verify the subscription tier in the metadata.
3. create_a_ada_conversation_message: Claude constructs the message payload and posts it to the conversation thread.
4. create_a_ada_conversation_end_handoff: Claude executes the state transition, ending the handoff and triggering CSAT.

Security and Access Control

Giving an LLM direct access to your Ada platform carries inherent risks. Truto provides several mechanisms to lock down the MCP server at the token level, ensuring Claude only performs authorized actions.

• Method Filtering (config.methods): You can restrict the MCP server to read-only operations by passing methods: ["read"] during creation. This allows Claude to list articles and view conversations, but prevents it from creating, updating, or deleting any records.
• Tag Filtering (config.tags): If your integration configuration groups endpoints by functional tags (e.g., "knowledge", "conversations"), you can pass tags: ["knowledge"] to expose only article and source management tools, hiding all conversation and user data endpoints.
• Extra Authentication (require_api_token_auth): By default, the MCP server URL acts as a bearer token. For higher security, setting this flag requires the caller to also pass a valid Truto API token in the Authorization header, preventing usage if the URL is leaked.
• Ephemeral Servers (expires_at): You can assign an ISO datetime to the expires_at property. The token is stored in a distributed key-value store, and an asynchronous scheduled alarm automatically deletes the server configuration when time expires, ideal for temporary debugging sessions.

Connect Ada and Claude Today

Building AI agents that can reliably operate your Ada environment requires taming complex pagination, asynchronous operations, and strict state transitions. Truto handles the REST boilerplate, authentication, and schema generation, giving Claude native, secure access to your CX infrastructure.

:::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"} Let's discuss how Truto can power your enterprise AI agent architecture. :::