Documentation Index
Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
Use this file to discover all available pages before exploring further.
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, npx -y @moda-ai/cli
npx skills add ModaLabs/moda-cli
{
"mcpServers": {
"moda": {
"command": "npx",
"args": ["-y", "@moda-ai/cli"],
"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": "npx",
"args": ["-y", "@moda-ai/cli"],
"env": {
"MODA_API_KEY": "moda_sk_your_api_key_here"
}
}
| Tool | Description |
|---|
moda_get_overview | Dashboard overview with KPIs, top clusters, and recent activity |
moda_get_clusters | Browse topic cluster hierarchy |
moda_get_cluster_conversations | List conversations in a specific cluster |
moda_search_conversations | Search and filter conversations by text, user, time range, environment |
moda_get_conversation_context | Get windowed conversation context (messages around a center point) |
moda_get_frustrations | User frustration detections with evidence and signal breakdown |
moda_get_tool_failures | Tool failure overview — which tools are failing and how often |
moda_get_tool_failure_detail | Per-tool failure detail with subtype breakdown and examples |
moda_get_overview
Get a high-level dashboard of your conversation analytics.
| Parameter | Type | Default | Description |
|---|
days_back | number | 7 | Number of days to look back (1-90) |
moda_get_clusters
Browse the topic cluster hierarchy.
| Parameter | Type | Default | Description |
|---|
parent_id | string | — | Parent node ID to drill down (omit for root) |
time_range | string | all | Time range filter: all, 1h, 3d, 7d, 24h, 30d, 90d |
moda_get_cluster_conversations
List conversations in a specific cluster.
| Parameter | Type | Default | Description |
|---|
node_id | string | required | Cluster node ID |
limit | number | 10 | Max results per page (1-100) |
offset | number | 0 | Pagination offset |
moda_search_conversations
Search and filter conversations.
| Parameter | Type | Default | Description |
|---|
search | string | — | Full-text search in summaries |
user_id | string | — | Filter by user ID |
time_range | string | all | all, 1h, 3d, 24h, 7d, 30d, 90d |
environment | string | all | all, development, staging, production |
limit | number | 20 | Max results per page (1-100) |
offset | number | 0 | Pagination offset |
moda_get_conversation_context
Get a window of messages from a conversation.
| Parameter | Type | Default | Description |
|---|
conversation_id | string | required | Conversation ID |
msg_index | number | — | Message index to center on (omit for middle) |
window | number | 2 | Messages before and after center (1-5) |
moda_get_frustrations
Get user frustration detections with evidence.
| Parameter | Type | Default | Description |
|---|
days_back | number | 7 | Number of days to look back (1-90) |
limit | number | 10 | Max results per page (1-20) |
offset | number | 0 | Pagination offset |
| Parameter | Type | Default | Description |
|---|
days_back | number | 7 | Number of days to look back (1-90) |
| Parameter | Type | Default | Description |
|---|
tool_name | string | required | Name of the tool to inspect |
subtype | string | — | Filter by error subtype |
days_back | number | 7 | Number of days to look back (1-90) |
limit | number | 5 | Max examples to return (1-20) |
offset | number | 0 | Pagination 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
- Try running
npx -y @moda-ai/cli manually to check for errors
No data returned?
- Verify your API key is valid at moda.dev/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
