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 bot data conversationally:
  • Retrieve Ada metrics (CSAT, AR rate, conversation volume, etc.)
  • Access conversation transcripts and summaries for performance review
  • Pull structured metadata like classification reasons and inquiry summaries
  • Search knowledge articles before suggesting new ones
• Test and validate AI agent behavior:
  • Simulate conversations to test how your agent responds before making changes live
  • Discover available communication channels configured for your bot

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; can be filtered using get_available_filters and desired date ranges)
• 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_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)

get_conversations_by_filters

Retrieve conversation IDs that match specific filters (CSAT, engagement, handoff status, etc.) within a date range.

get_conversation

Retrieves the transcript for a given conversation ID.

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_topics

Lists all generated topics and categories with their IDs. Use this to find topic IDs for filtering conversations by topic with get_ada_metric or get_conversations_by_filters.

list_channels

Lists all available communication channels configured for the client (e.g., Chat, Email, Voice). Useful for discovering channel IDs needed by other tools like simulate_conversation.

simulate_conversation

Simulates a single-turn conversation with the Ada agent without affecting real conversations or analytics. Send a test message and receive the agent’s response to validate configuration changes before applying them. Currently supports Chat and Email channels. Use list_channels to find available channel IDs.

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 bot! 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.

Test agent responses

Simulate conversations to validate changes before going live.

Deep-dive analysis

Combine multiple insights for comprehensive analysis and recommendations.

Potential future capabilities

We’re exploring additional capabilities 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
• Write capabilities — Allow AI assistants (with your permission) to make changes on your behalf, such as creating playbooks they’ve helped you draft

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).