MCP Server

Introduction

The Model Context Protocol (MCP) is an open standard that allows you to securely connect Ada with external AI assistants, such as Claude Desktop and ChatGPT. Through MCP, you can query and analyze AI agent data conversationally, unlocking insights like CSAT trends and AR drivers without navigating dashboards.

What MCP can do today

• Connect Ada to external MCP clients like Claude Desktop and ChatGPT
• Query and analyze AI Agent data conversationally:
  • Retrieve Ada metrics (CSAT, AR rate, conversation volume, containment rate, etc.)
  • Access conversation transcripts and summaries for performance review
  • Pull conversation summaries and inquiry patterns across hundreds of conversations
  • Search knowledge articles and custom instructions before suggesting changes
• Make changes directly from your AI assistant:
  • Create and update knowledge articles
  • Create and update custom instructions
• Test and validate AI agent behavior:
  • Create, edit, and delete test cases to define expected agent behavior
  • Execute test runs to create simulated conversations and validate Agent responses against expected outcomes
  • Discover available communication channels configured for your AI Agent
• Retrieve and export test data:
  • Retrieve test cases and test run results for your AI Agent
  • Check daily test run quota usage
  • Export test cases and results as CSV

Tools available

get_ada_configuration

Fetches all entities (guidance, playbooks, actions, coaching, company description) along with comprehensive improvement guide resource. This tool is what enables the AI client to give improvement suggestions.

get_ada_metric

Retrieves:

• Metrics (Automated resolution rate, CSAT rate, engaged conversation volume, containment rate, and containment volume; can be filtered using get_available_filters and desired date ranges)
  • containment_rate — percentage (0–100) of conversations handled without escalating to a human agent
  • containment_volume — count of conversations handled without escalating to a human agent
• Conversation metadata
  • conversation_id - Unique identifier for the conversation
  • timestamp - When the conversation was engaged (earliest engagement time)
  • customer_inquiry_summary - AI-generated summary of what the customer was asking about
  • automated_resolution_status - Whether the conversation was “Resolved” or “Unresolved” by automation
  • automated_resolution_reason - Explanation for why the conversation received its resolution classification

get_available_filters

Returns available filter types and operators for conversation filtering:

• CSATSCORE - Filter by CSAT rating (1-5, or “ispositive”/“isnegative”)
• ENGAGED - Whether the conversation was engaged
• HANDOFF - Whether the conversation was handed off to an agent
• ARTICLEID - Filter by specific knowledge article ID
• ACTIONID - Filter by specific action ID
• ARSTATUS - Automated resolution status (“Resolved” or “Not Resolved”)
• TOPICS - Filter by topic ID (use list_entities(entity_type='topics') to find IDs)
• LANGUAGE - Filter by language code (e.g., ‘en’, ‘es’, ‘fr’)
• CHANNEL - Filter by channel (e.g., ‘web’, ‘mobile’, ‘email’)
• BROWSER - Filter by browser (e.g., ‘chrome’, ‘safari’, ‘firefox’)
• DEVICE - Filter by device (e.g., ‘macos’, ‘iphone’, ‘android’)
• STATUSCODE - Filter by action HTTP status code (e.g., ‘200’, ‘400’, ‘500’)
• COACHINGAPPLIED - Filter by coaching ID (use search_coaching to find IDs)
• PLAYBOOKID - Filter by playbook ID (use get_ada_configuration to find IDs)
• ISTESTUSER - Include/exclude test conversations (excluded by default)
• VARIABLE - Filter by conversation variable value (use list_entities(entity_type='variables') to find variable IDs and names)

get_conversations

Retrieve many conversations at a chosen detail level within a date range.

• IDS_ONLY — Returns conversation IDs, created date, and platform (default up to 500, max 1,000). Use for finding conversations that match specific filters.
• SUMMARY — Returns inquiry summaries, resolution status, resolution reason, and a dashboard link per conversation (default up to 250, max 500). Use for pattern analysis across many conversations.

Use get_available_filters to find valid filter options before filtering.

get_conversation

Retrieves full details for a single conversation by ID, including:

• Conversation summary, resolution status, and resolution reason
• The full AI agent event log (actions, decisions, and reasoning)

Use this for debugging or analyzing a specific conversation. For bulk analysis, use get_conversations with SUMMARY detail instead.

search_knowledge

Searches for knowledge articles to check existing content before suggesting new articles. Used in conjunction with get_ada_configuration.

search_coaching

Searches for coaching to check existing coaching before suggesting new coaching. Used in conjunction with get_ada_configuration.

list_entities

Lists entities of a given type for discovery and reference. Supports three entity types:

• channels — All communication channels configured for the AI Agent (native and custom).
• topics — Generated topics and categories. Use topic IDs with the TOPICS filter in get_ada_metric or get_conversations.
• variables — Conversation variables (scopes: global, meta, auto_capture). Use variable names with the VARIABLE filter in get_ada_metric or get_conversations.

Accepts a detail parameter: full (default) returns all available fields including type-specific metadata; minimal returns only ID and name.

propose_change

Proposes creating, updating, enabling, or disabling Ada entities directly from your AI assistant. Uses a two-phase flow:

1. Discover fields: Call with entity_type and operation (without fields) to see available fields and their descriptions.
2. Execute: Call again with the fields parameter populated to apply the change.

Supported entity types and operations:

Knowledge articles are created with enabled: false by default to prevent unintended live impact.

For test cases, the tool supports the full lifecycle:

• Create new test cases with a message, channel, and evaluation criteria
• Update existing test cases to refine context or adjust expected outcomes
• Delete test cases that are no longer needed

Each test case defines how the AI Agent should respond to a specific scenario and what evaluation criteria determine a pass or fail.

For test runs, creating a test_run triggers test execution for the specified test case IDs. After execution, use get_test_runs to retrieve results including pass/fail status, evaluation criteria outcomes, and rationale for each result.

get_test_cases

Retrieves test cases for an AI Agent. Supports listing all test cases with optional name filtering, retrieving full details for a specific test case by ID, and grouping test cases by channel.

get_test_runs

Retrieves test run results for an AI Agent. Supports:

• Latest results per test case, with optional status and test case filters
• Full details for a specific test run, including pass/fail status, evaluation criteria, and rationale
• Historical test runs with pagination

get_test_run_quota

Retrieves daily test run quota information for an AI Agent, including runs used today, remaining runs, and the daily limit (300 runs per day).

Built-in prompts

In addition to tools, Ada’s MCP server ships with pre-built prompt templates for common tasks. In MCP clients that support prompts (such as Claude Desktop), these appear as ready-to-use shortcuts in the connector menu — no typing required.

To use them in Claude Desktop:

1. Click the + icon in the chat bar
2. Select Connectors
3. Click your Ada connection
4. Choose a prompt from the list — it will be inserted into your chat and ready to run

Getting started

Requirements

• Access to an MCP-compatible client:
  • Claude Desktop or ChatGPT (paid plan recommended for higher usage limits)
  • Gemini CLI for Gemini Enterprise users
  • Google ADK for programmatic integrations
• For Claude Desktop and Gemini CLI: Node.js installed locally (LTS version recommended)
• For ADK: Python 3.10 or later
• Agent, Admin, or Owner role in your Ada dashboard

Data privacy

Some MCP tools—such as get_conversation—retrieve conversation transcripts that may contain personally identifiable information (PII). Before connecting Ada to an AI assistant, we recommend disabling model training on your chat data to ensure customer information isn’t used to train AI models.

• ChatGPT: Go to Settings → Data Controls → disable “Improve the model for everyone”
• Claude: Go to Settings → Privacy → disable “Allow training”

If you prefer not to share conversation transcripts with your AI assistant, Claude Desktop allows you to disable individual tools like get_conversation after connecting—you can still get value from the other available tools. (ChatGPT does not currently support disabling individual tools.)

Authentication methods

The MCP server supports two authentication approaches:

Your dashboard domain is the URL you use to access Ada (e.g., acme-corp.ada.support, acme-corp.eu.ada.support, or acme-corp.maple.ada.support).

Example: If your dashboard is at https://acme-corp.eu.ada.support, your MCP Server URL is: https://acme-corp.eu.ada.support/api/mcp/oauth

To generate an API key, go to Config > PLATFORM > API Keys in your Ada dashboard. See Authentication for details.

ChatGPT setup

1. Open ChatGPT in your browser
2. Click your name in the bottom left
3. Click ‘Settings’
4. Click ‘Apps’
5. Scroll down and click ‘Advanced settings’
6. Toggle ‘Developer mode’ to ‘On’
7. Click ‘Create app’ just above the toggle
8. Fill out these values:
   • Name: A name for this connection (e.g., “Ada” or your company name)
   • Description: A description that helps ChatGPT recognize when to use this connection (e.g., “Use when asked about Acme Corp’s AI agent data, CSAT, or conversation analytics”)
   • MCP Server URL: https://<your-dashboard-domain>/api/mcp/oauth (see Authentication Methods above)
   • Authentication: OAuth
   • OAuth Client ID (Optional): Leave blank
   • OAuth Client Secret (Optional): Leave blank
9. Click the checkbox next to ‘I understand and want to continue’
10. Wait 5-10 seconds to be redirected to a page where you are asked to enter your Ada handle
11. Enter your Ada handle (the subdomain from your dashboard URL), select your region from the dropdown, and click ‘Continue to Login’
12. Log in with your Ada credentials
13. Click ‘Allow access’ on the authorization page
14. Wait 15-30 seconds for the connection to complete
15. Start asking ChatGPT questions about your Ada AI Agent! See the prompt library for inspiration.

Claude Desktop setup

The MCP server supports both OAuth and API key authentication. Choose the method that works best for you.

Option 1: OAuth (recommended)

OAuth authentication uses browser-based login with your Ada credentials. No API key is required.

To connect Claude Desktop to Ada’s MCP server using OAuth:

1. Open Claude Desktop
2. Go to Settings → Developer → Edit Config
3. Add the following to your claude_desktop_config.json:

1
{
2
  "mcpServers": {
3
    "ada": {
4
      "command": "npx",
5
      "args": ["mcp-remote", "https://acme-corp.ada.support/api/mcp/oauth"]
6
    }
7
  }
8
}

4. Replace acme-corp.ada.support with your Ada dashboard domain (see Authentication Methods above)
5. Restart Claude Desktop
6. When prompted, authorize the connection with your Ada credentials

Option 2: API key

API key authentication uses a token generated from your Ada dashboard. This method is useful for automated setups or when browser-based login is not available.

To connect Claude Desktop to Ada’s MCP server using an API key:

1. Generate an API key from Config → PLATFORM → API keys in your Ada dashboard
2. Open Claude Desktop and go to Settings → Developer → Edit Config
3. Add the following to your claude_desktop_config.json:

1
{
2
  "mcpServers": {
3
    "ada": {
4
      "command": "npx",
5
      "args": [
6
        "mcp-remote",
7
        "https://acme-corp.ada.support/api/mcp",
8
        "--header",
9
        "Authorization:${AUTH_HEADER}"
10
      ],
11
      "env": {
12
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
13
      }
14
    }
15
  }
16
}

4. Replace acme-corp.ada.support with your Ada dashboard domain (see Authentication Methods above)
5. Replace YOUR_API_KEY with your API key
6. Restart Claude Desktop

Gemini CLI setup

Gemini CLI supports MCP server connections through its settings configuration. Both OAuth and API key authentication are supported.

Option 1: OAuth (recommended)

OAuth authentication uses browser-based login with your Ada credentials. No API key is required.

Gemini CLI uses the mcp-remote bridge to connect to HTTP-based MCP servers. If prompted, allow npx to install it automatically, or install it manually with:

$
npm install -g mcp-remote

To connect Gemini CLI to Ada’s MCP server using OAuth:

1. Ensure Gemini CLI is installed and configured with your Google account
2. Open your Gemini CLI settings file at ~/.gemini/settings.json.
3. Add the following configuration under the existing mcpServers section (or create one if it does not exist):

1
{
2
  "mcpServers": {
3
    "ada": {
4
      "command": "npx",
5
      "args": ["mcp-remote", "https://acme-corp.ada.support/api/mcp/oauth"]
6
    }
7
  }
8
}

4. Replace acme-corp.ada.support with your Ada instance domain (for example, your-company.ada.support). MCP routing is based on subdomain.

5. Restart Gemini CLI.

6. When you first attempt to use an Ada MCP tool, Gemini CLI will detect the OAuth challenge from the server. If authentication is required, run:

$
/mcp auth ada

This opens a browser window to complete the OAuth login flow. After authentication completes, retry your request.

Option 2: API key

API key authentication uses a token generated from your Ada dashboard. This method is useful for automated setups or when browser-based login is not available.

To connect Gemini CLI to Ada’s MCP server using an API key:

1. Generate an API key from Config > PLATFORM > API keys in your Ada dashboard.
2. Set the API key as an environment variable:

export ADA_API_KEY=your_api_key_here

3. Open your Gemini CLI settings file at ~/.gemini/settings.json
4. Add the following configuration under the existing mcpServers section (or create one if it does not exist):

1
{
2
  "mcpServers": {
3
    "ada": {
4
      "command": "npx",
5
      "args": [
6
        "mcp-remote",
7
        "https://acme-corp.ada.support/mcp",
8
        "--header",
9
        "Authorization: Bearer ${ADA_API_KEY}"
10
      ]
11
    }
12
  }
13
}

5. Replace acme-corp.ada.support with your Ada instance domain (see Authentication Methods above).
6. Restart Gemini CLI.

ADK setup

The Google Agent Development Kit (ADK) can connect to Ada’s MCP server using the MCPToolset class. This enables programmatic access to Ada’s MCP tools within ADK-based agents.

Ada’s MCP server currently supports JSON-RPC 2.0 over HTTP at the /mcp endpoint. Server-Sent Events (SSE) streaming is not available.

Requirements

• Python 3.10 or later

• Google ADK installed:

  $
  pip install google-adk

• An API key generated from Config > PLATFORM > API keys in your Ada dashboard

Configuration

To connect ADK to Ada’s MCP server:

1. Generate an API key from Config > PLATFORM > API keys in your Ada dashboard.
2. Set your Ada API key as an environment variable:

$
export ADA_API_KEY=your_api_key_here

3. Connect to Ada’s MCP server:

1
import asyncio
2
import os
3
from google.adk.toolsets import MCPToolset
4
5
async def main():
6
    ada_toolset = await MCPToolset.from_server(
7
        connection_params={
8
            "url": "https://acme-corp.ada.support/mcp",
9
            "headers": {
10
                "Authorization": f"Bearer {os.environ['ADA_API_KEY']}"
11
            }
12
        }
13
    )
14
15
    tools = ada_toolset.get_tools()
16
    print(f"Loaded {len(tools)} Ada MCP tools")
17
18
asyncio.run(main())

4. Replace acme-corp.ada.support with your Ada instance domain (see Authentication Methods above).
5. Ensure ADA_API_KEY is set in your environment before running the script.

Endpoint used by ADK

Ada’s MCP server is exposed at the /mcp endpoint and routed by subdomain.

• Production: https://<your-subdomain>.<your-ada-domain>/mcp
• Local development: http://<subdomain>.localhost:8000/mcp

Common issues

• 401 Unauthorized
  • Ensure your API key is valid
  • Verify the Authorization header is correctly formatted as Bearer <key>
• 405 Method Not Allowed
  • Ensure you are sending POST requests to /mcp
  • SSE (GET streaming) is not supported

Connecting multiple bots

If you manage multiple Ada bots, you can connect them all to Claude Desktop by adding each one to your config file with a unique name:

1
{
2
  "mcpServers": {
3
    "ada-support": {
4
      "command": "npx",
5
      "args": ["mcp-remote", "https://support-bot.ada.support/api/mcp/oauth"]
6
    },
7
    "ada-sales": {
8
      "command": "npx",
9
      "args": ["mcp-remote", "https://sales-bot.ada.support/api/mcp/oauth"]
10
    }
11
  }
12
}

Getting the best results

We recommend using detailed, structured prompts for best results. Being specific about the data you want to analyze (timeframe, filters, number of conversations) and the insights you’re seeking will help you get more actionable results.

See the Prompt Library below for examples organized by use case.

Prompt library

Use these example prompts to get started with common use cases. You can ask these questions directly in your connected AI assistant.

Get improvement recommendations

The most powerful way to use MCP is to ask for actionable recommendations to improve your AI agent’s performance. The AI assistant will analyze your conversation data, review your current configuration, and suggest specific improvements.

Quick health checks

Get an immediate read on performance, trends, or experience quality.

Create visualizations

Ask the AI assistant to create charts and diagrams to visualize your data. This is especially useful for presentations, reports, or sharing insights with stakeholders.

Example: AR and CSAT Trend Chart

Example: Conversation Flow Sankey Diagram

Diagnose performance issues

Investigate patterns by pulling summaries and metadata to understand what’s driving outcomes.

Identify optimization opportunities

Find areas with the biggest potential for improvement.

Review current configuration

Understand what your AI agent is currently configured with.

Search knowledge and coaching

Find existing content before making changes.

Manage test cases and run tests

Create, update, and delete test cases, and trigger test runs to validate agent behavior.

Analyze and export test results

Retrieve test data, identify trends, and export results through MCP.

Deep-dive analysis

Combine multiple insights for comprehensive analysis and recommendations.

Potential future capabilities

Additional capabilities are being explored based on customer feedback:

• In-dashboard AI assistant — An AI assistant within the Ada dashboard as an alternative to external tools like Claude and ChatGPT
• Additional write capabilities — Expand write support to additional entity types such as playbooks

Troubleshooting

Authentication problems

If you’re experiencing issues connecting to the MCP server, try these debugging steps:

1. Kill existing MCP connections

$
pkill -f mcp-remote

2. Clear the MCP auth cache

$
rm -rf ~/.mcp-auth

After running these commands, restart your MCP client (Claude Desktop or ChatGPT) and try connecting again.

FAQ

Q: What’s the value of using MCP?

A: It lets you ask natural-language questions like “How has CSAT trended this quarter?” and “What can I do to improve my CSAT?” This removes the need to dig through dashboards, and also helps generate insights that would be difficult to produce manually without the help of an LLM.

Q: Can I customize which tools are available?

A: Yes, in Claude Desktop. Once you connect Ada’s MCP server, you can disable specific tools you’re not interested in using. For example, if you prefer not to share conversation transcripts, you can disable the get_conversation tool and still get value from the other available tools. (ChatGPT does not currently support disabling individual tools.)

Q: What data flows through MCP?

A: Depending on which tools you use, conversation transcripts, reasoning history, summaries, AR status, and CSAT may be transmitted to your chosen MCP client (e.g., Claude, ChatGPT).