MCP Tools Reference - Intro to ClosedLoop AI

🔧 Available Tools

The ClosedLoop MCP Server provides comprehensive tools for accessing and searching customer insight data:

list_insights - Retrieve insights with filtering and pagination
get_insight_detail - Get detailed information about specific insights
search_insights - Advanced full-text search with relevance ranking

📋 list_insights

Retrieve customer insights with optional filtering and pagination.

Description

Get a paginated list of customer insight items for the authenticated team. Supports date range filtering and pagination to help you find the insights you need.

Input Schema

{
  "type": "object",
  "properties": {
    "date_from": {
      "type": "string",
      "format": "date",
      "description": "Start date for insights (YYYY-MM-DD)"
    },
    "date_to": {
      "type": "string", 
      "format": "date",
      "description": "End date for insights (YYYY-MM-DD)"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Page number for pagination"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Number of insight items per page"
    }
  },
  "required": []
}

Parameters

date_from

string

Start date for insight filtering. Format: YYYY-MM-DD (e.g., “2024-01-01”)

date_to

string

End date for insight filtering. Format: YYYY-MM-DD (e.g., “2024-01-31”)

page

integer

default:"1"

Page number for pagination. Minimum: 1

limit

integer

default:"20"

Number of insight items per page. Range: 1-100

Example Usage

Get Recent Insights

{
  "name": "list_insights",
  "arguments": {
    "limit": 10
  }
}

Get Insights from Date Range

{
  "name": "list_insights",
  "arguments": {
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
    "page": 1,
    "limit": 20
  }
}

Get All Insights (Paginated)

{
  "name": "list_insights",
  "arguments": {
    "page": 2,
    "limit": 50
  }
}

Response Format

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"data\": {\"insights\": [...], \"pagination\": {...}}}"
    }
  ]
}

Response Data Structure

{
  "success": true,
  "data": {
    "insights": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "content": "The new dashboard is confusing and hard to navigate",
        "sentiment": "negative",
        "topic": "bug_report",
        "priority": "high",
        "source": "gong",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "metadata": {
          "customer_id": "customer_123",
          "call_duration": 1200,
          "speaker": "customer",
          "call_id": "call_456"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Insight Object Fields

Field	Type	Description
`id`	string	Unique identifier (UUID)
`content`	string	The actual insight text
`sentiment`	string	AI-determined sentiment (positive/negative/neutral)
`topic`	string	Categorized topic (feature_request/bug_report/complaint/praise)
`priority`	string	Priority level (low/medium/high/critical)
`source`	string	Data source (gong/zendesk/intercom/slack)
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp
`metadata`	object	Additional context data

Metadata Fields

Field	Type	Description
`customer_id`	string	Customer identifier
`call_duration`	number	Call duration in seconds (Gong)
`speaker`	string	Who spoke (customer/agent)
`call_id`	string	Call identifier (Gong)

🔍 get_insight_detail

Get detailed information about a specific insight item.

Description

Retrieve comprehensive details about a specific insight item, including full analysis and metadata. This tool provides deeper insights than the list view.

Input Schema

{
  "type": "object",
  "properties": {
    "insight_id": {
      "type": "string",
      "description": "UUID of the insight item"
    }
  },
  "required": ["insight_id"]
}

Parameters

insight_id

string

required

UUID of the insight item to retrieve details for

Example Usage

Get Specific Insight Details

{
  "name": "get_insight_detail",
  "arguments": {
    "insight_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response Format

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"data\": {...}}"
    }
  ]
}

Response Data Structure

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "content": "The new dashboard is confusing and hard to navigate. We had to train our team for 2 hours just to understand the new layout.",
    "sentiment": "negative",
    "topic": "bug_report",
    "priority": "high",
    "source": "gong",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "customer_id": "customer_123",
      "call_duration": 1200,
      "speaker": "customer",
      "call_id": "call_456",
      "participants": ["customer", "sales_rep", "product_manager"]
    },
    "analysis": {
      "key_points": [
        "Dashboard navigation is confusing",
        "Requires extensive training",
        "Layout changes are disruptive"
      ],
      "action_items": [
        "Improve dashboard navigation",
        "Add user onboarding flow",
        "Consider gradual rollout"
      ],
      "sentiment_score": 0.2,
      "confidence": 0.95,
      "business_impact": "high",
      "urgency": "medium"
    }
  }
}

Analysis Fields

Field	Type	Description
`key_points`	array	Extracted key points from the insight
`action_items`	array	Suggested action items based on the insight
`sentiment_score`	number	Numeric sentiment score (0-1, where 0 is negative)
`confidence`	number	AI confidence level (0-1)
`business_impact`	string	Business impact assessment (low/medium/high)
`urgency`	string	Urgency level (low/medium/high)

🔍 search_insights

Advanced full-text search across customer insights with relevance ranking and comprehensive filtering.

Description

Perform powerful full-text search across customer insights using PostgreSQL’s tsvector technology. This tool provides much more sophisticated search capabilities than basic filtering, with relevance ranking, phrase search, fuzzy matching, and field-specific search options.

Key Features

Full-text search across 8+ insight fields
Relevance ranking - most relevant results appear first
Phrase search - find exact phrases like “mobile app”
Fuzzy matching - handles typos automatically
Field-specific search - search specific fields or all fields
Advanced filtering - category, severity, date range, source
Language agnostic - works with any language

Input Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query text (works in any language)"
    },
    "fields": {
      "type": "array",
      "items": { 
        "type": "string",
        "enum": ["signal_title", "content", "pain_point", "workaround", "use_case", "feature_area", "competitor_gap", "willingness_to_pay"]
      },
      "description": "Specific fields to search in (optional - searches all if not specified)"
    },
    "date_from": {
      "type": "string",
      "format": "date",
      "description": "Start date for insights (YYYY-MM-DD)"
    },
    "date_to": {
      "type": "string",
      "format": "date",
      "description": "End date for insights (YYYY-MM-DD)"
    },
    "severity": {
      "type": "string",
      "enum": ["critical", "high", "medium", "low"],
      "description": "Filter by severity level"
    },
    "category": {
      "type": "string",
      "enum": [
        "Bug", "Performance Issue", "Security Issue", "Feature Request", 
        "Improvement", "UX/UI Issue", "Documentation", "Integration Issue", 
        "Missing Functionality"
      ],
      "description": "Filter by category"
    },
    "source": {
      "type": "string",
      "description": "Filter by integration source"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "default": 1,
      "description": "Page number for pagination"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Number of insight items per page"
    }
  },
  "required": ["query"]
}

Parameters

query

string

required

Search query text. Supports phrase search with quotes, fuzzy matching, and works in any language.

fields

array

Specific fields to search in. Options: signal_title, content, pain_point, workaround, use_case, feature_area, competitor_gap, willingness_to_pay. If not specified, searches all fields.

Example Usage

Basic Search

{
  "name": "search_insights",
  "arguments": {
    "query": "mobile app performance"
  }
}

Advanced Search with Filters

{
  "name": "search_insights",
  "arguments": {
    "query": "slow loading times",
    "category": "Performance Issue",
    "severity": "high",
    "date_from": "2024-01-01",
    "limit": 10
  }
}

Field-Specific Search

{
  "name": "search_insights",
  "arguments": {
    "query": "pricing concerns",
    "fields": ["pain_point", "willingness_to_pay"]
  }
}

Phrase Search

{
  "name": "search_insights",
  "arguments": {
    "query": "\"mobile app startup\"",
    "category": "Performance Issue"
  }
}

Response Format

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"data\": {\"insights\": [...], \"pagination\": {...}, \"search_info\": {...}}}"
    }
  ]
}

Response Data Structure

{
  "success": true,
  "data": {
    "insights": [
      {
        "id": "uuid",
        "title": "Mobile app startup >30s — investigate and fix",
        "content": "Multiple users report the mobile app is taking more than 30 seconds to start...",
        "pain_point": ">30s startup time causing frustration and likely abandonment",
        "workaround": null,
        "use_case": "Enable users to adjust settings and customize features...",
        "feature_area": "Mobile app",
        "competitor_gap": null,
        "willingness_to_pay": null,
        "severity": "High",
        "status": "new",
        "category": "Performance Issue",
        "timestamp": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:30:00Z",
        "customer_name": "John Doe",
        "reporter_name": "John Doe",
        "source_name": "Gong",
        "source_logo_url": "https://...",
        "relevance_score": 0.5748475
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    },
    "search_info": {
      "query": "mobile app performance",
      "fields_searched": "all",
      "total_matches": 45
    }
  }
}

Searchable Fields

Field	Description	Example Search
`signal_title`	Insight title	”Mobile app startup”
`content`	Raw feedback content	”app crashes frequently”
`pain_point`	Customer pain points	”slow loading times”
`workaround`	Customer workarounds	”using competitor app”
`use_case`	Use case descriptions	”real-time collaboration”
`feature_area`	Feature categorization	”mobile app”
`competitor_gap`	Competitive analysis	”better than Salesforce”
`willingness_to_pay`	Payment willingness	”pay extra for features”

Search Features

Full-Text Search Capabilities:

Phrase Search: Find exact phrases like “mobile app”
Fuzzy Matching: Handles typos automatically (e.g., “moblie” matches “mobile”)
Relevance Ranking: Results ordered by relevance score
Language Agnostic: Works with any language using PostgreSQL’s ‘simple’ configuration
Field Selection: Search specific fields or all fields

💡 Best Practices

Efficient Data Retrieval

Use date ranges to limit results when possible
Start with smaller page sizes for testing
Use get_insight_detail only when you need the full analysis

Search Optimization

Use specific search terms for better relevance
Combine search with filters (category, severity) for faster results
Use field-specific search when you know where to look
Try phrase searches with quotes for exact matches
Use date ranges to limit search scope

Performance Optimization

Cache results when appropriate
Use pagination for large datasets
Consider date ranges for historical data
Use search_insights for complex queries instead of list_insights + filtering

MCP Server Overview - Learn about the MCP server architecture
Integration Guide - Setup and configuration instructions

Need Help with Integration?

Learn how to set up and configure the MCP server with your AI client

MCP Server

​🔧 Available Tools

​📋 list_insights

​Description

​Input Schema

​Parameters

​Example Usage

​Get Recent Insights

​Get Insights from Date Range

​Get All Insights (Paginated)

​Response Format

​Response Data Structure

​Insight Object Fields

​Metadata Fields

​🔍 get_insight_detail

​Description

​Input Schema

​Parameters

​Example Usage

​Get Specific Insight Details

​Response Format

​Response Data Structure

​Analysis Fields

​🔍 search_insights

​Description

​Key Features

​Input Schema

​Parameters

​Example Usage

​Basic Search

​Advanced Search with Filters

​Field-Specific Search

​Phrase Search

​Response Format

​Response Data Structure

​Searchable Fields

​Search Features

​💡 Best Practices

​Efficient Data Retrieval

​Search Optimization

​Performance Optimization

​🔗 Related Resources

Need Help with Integration?

🔧 Available Tools

📋 list_insights

Description

Input Schema

Parameters

Example Usage

Get Recent Insights

Get Insights from Date Range

Get All Insights (Paginated)

Response Format

Response Data Structure

Insight Object Fields

Metadata Fields

🔍 get_insight_detail

Description

Input Schema

Parameters

Example Usage

Get Specific Insight Details

Response Format

Response Data Structure

Analysis Fields

🔍 search_insights

Description

Key Features

Input Schema

Parameters

Example Usage

Basic Search

Advanced Search with Filters

Field-Specific Search

Phrase Search

Response Format

Response Data Structure

Searchable Fields

Search Features

💡 Best Practices

Efficient Data Retrieval

Search Optimization

Performance Optimization

🔗 Related Resources