Skip to main content

​
Overview

The Moda MCP server exposes your conversation analytics as tools that AI assistants can use directly. It supports 8 tools covering overview dashboards, conversation search, frustration detection, and tool failure analysis.

​
Prerequisites

​
Setup for Claude Code

Add the Moda MCP server to your Claude Code configuration: 
claude mcp add moda-data-api -- node /path/to/moda-data-api-mcp/dist/index.js
Or add it manually to your MCP config file: 
{
  "mcpServers": {
    "moda-data-api": {
      "command": "node",
      "args": ["/path/to/apps/moda-data-api-mcp/dist/index.js"],
      "env": {
        "MODA_API_KEY": "moda_sk_your_api_key_here"
      }
    }
  }
}

​
Setup for Other MCP Clients

Any MCP-compatible client can connect using the stdio transport: 
{
  "command": "node",
  "args": ["/path/to/apps/moda-data-api-mcp/dist/index.js"],
  "env": {
    "MODA_API_KEY": "moda_sk_your_api_key_here"
  }
}

​
Available Tools

ToolDescription
moda_get_overviewDashboard overview with KPIs, top clusters, and recent activity
moda_get_clustersBrowse topic cluster hierarchy
moda_get_cluster_conversationsList conversations in a specific cluster
moda_search_conversationsSearch and filter conversations by text, user, time range, environment
moda_get_conversation_contextGet windowed conversation context (messages around a center point)
moda_get_frustrationsUser frustration detections with evidence and signal breakdown
moda_get_tool_failuresTool failure overview — which tools are failing and how often
moda_get_tool_failure_detailPer-tool failure detail with subtype breakdown and examples

​
Tool Reference

​
moda_get_overview

Get a high-level dashboard of your conversation analytics.
ParameterTypeDefaultDescription
days_backnumber7Number of days to look back (1-90)

​
moda_get_clusters

Browse the topic cluster hierarchy.
ParameterTypeDefaultDescription
parent_idstring—Parent node ID to drill down (omit for root)
time_rangestringallTime range filter: all, 1h, 3d, 7d, 24h, 30d, 90d

​
moda_get_cluster_conversations

List conversations in a specific cluster.
ParameterTypeDefaultDescription
node_idstringrequiredCluster node ID
limitnumber10Max results per page (1-100)
offsetnumber0Pagination offset

​
moda_search_conversations

Search and filter conversations.
ParameterTypeDefaultDescription
searchstring—Full-text search in summaries
user_idstring—Filter by user ID
time_rangestringallall, 1h, 3d, 24h, 7d, 30d, 90d
environmentstringallall, development, staging, production
limitnumber20Max results per page (1-100)
offsetnumber0Pagination offset

​
moda_get_conversation_context

Get a window of messages from a conversation.
ParameterTypeDefaultDescription
conversation_idstringrequiredConversation ID
msg_indexnumber—Message index to center on (omit for middle)
windownumber2Messages before and after center (1-5)

​
moda_get_frustrations

Get user frustration detections with evidence.
ParameterTypeDefaultDescription
days_backnumber7Number of days to look back (1-90)
limitnumber10Max results per page (1-20)
offsetnumber0Pagination offset

​
moda_get_tool_failures

Get tool failure overview.
ParameterTypeDefaultDescription
days_backnumber7Number of days to look back (1-90)

​
moda_get_tool_failure_detail

Get detailed failure info for a specific tool.
ParameterTypeDefaultDescription
tool_namestringrequiredName of the tool to inspect
subtypestring—Filter by error subtype
days_backnumber7Number of days to look back (1-90)
limitnumber5Max examples to return (1-20)
offsetnumber0Pagination offset

​
Troubleshooting

Server won’t start?
  • Ensure MODA_API_KEY is set and starts with moda_sk_
  • Verify Node.js 18+ is installed: node --version
  • Check the path to dist/index.js is correct
No data returned?
  • Verify your API key is valid at modaflows.com/settings
  • Check that you have conversations ingested — see Quickstart
  • Try increasing days_back for a wider time range
Connection errors?
  • The MCP server connects to the Moda backend API by default
  • Override with MODA_BASE_URL environment variable if needed
  • Ensure your network can reach the backend service
For more example workflows, see Use Cases.