@thinkhive/mcp-explainer

MCP (Model Context Protocol) server for the ThinkHive Explainer API. Provides AI agents with access to trace analysis, explainability, and debugging capabilities.

Features

• 15 powerful tools for trace analysis, pattern detection, and debugging
• STDIO transport for Claude Code CLI integration
• HTTP/SSE transport for web clients and external integrations
• Comprehensive trace support: multi-turn conversations, tool calls, RAG context
• Redis-based rate limiting for production deployments
• Company isolation for multi-tenant security
• Comprehensive audit logging for compliance
• Tier-based feature gates (free, starter, professional, enterprise)

Installation

npm install @thinkhive/mcp-explainer

Quick Start

Claude Code CLI

Add to your Claude Code configuration (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "thinkhive-explainer": {
      "command": "npx",
      "args": ["@thinkhive/mcp-explainer"],
      "env": {
        "THINKHIVE_API_KEY": "thk_your_api_key_here",
        "THINKHIVE_API_URL": "https://demo.thinkhive.ai"
      }
    }
  }
}

Programmatic Usage

import { startStdioServer } from '@thinkhive/mcp-explainer';

// Start STDIO server
await startStdioServer();

HTTP/SSE Transport

import express from 'express';
import { setupHttpTransport } from '@thinkhive/mcp-explainer';

const app = express();
app.use(express.json());

setupHttpTransport({
  app,
  basePath: '/mcp',
});

app.listen(3001, () => {
  console.log('MCP server running on http://localhost:3001');
});

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | THINKHIVE_API_KEY | Yes | - | Your ThinkHive API key (get one at Settings page) | | THINKHIVE_API_URL | No | https://demo.thinkhive.ai | ThinkHive API URL | | REDIS_URL | No | - | Redis URL for distributed rate limiting |

Getting Your API Key

1. Visit https://demo.thinkhive.ai
2. Sign in to your account
3. Go to Settings > API Keys
4. Click Create API Key
5. Copy the key (shown only once) and add it to your configuration

Available Tools

Trace Analysis

| Tool | Description | Tier | |------|-------------|------| | trace_explain | Analyze a trace and generate detailed explanation | Free | | trace_search | Search traces using natural language | Starter+ | | trace_get_explanation | Get stored explanation by trace ID | Free | | trace_patterns | Get failure patterns for an agent | Starter+ | | trace_stats | Get statistics for traces | Free | | trace_batch_analyze | Analyze multiple traces at once | Starter+ | | trace_counterfactual | Get "what would work" analysis | Professional+ |

Cluster Analysis

| Tool | Description | Tier | |------|-------------|------| | cluster_list | List failure clusters for an agent | Starter+ | | cluster_details | Get cluster details with examples | Starter+ |

Webhooks

| Tool | Description | Tier | |------|-------------|------| | webhook_list | List configured webhooks | Professional+ | | webhook_create | Create a new webhook | Professional+ | | webhook_update | Update a webhook | Professional+ | | webhook_delete | Delete a webhook | Professional+ |

Keywords

| Tool | Description | Tier | |------|-------------|------| | keyword_search | Search traces by keywords | Free | | keyword_top | Get top keywords for an agent | Free |

Tool Examples

Simple Trace Analysis

Minimal trace with just the essentials:

{
  "trace": {
    "id": "trace-123",
    "userMessage": "I want to return my order",
    "agentResponse": "I'll process that refund for you right away!",
    "outcome": "policy_violation"
  }
}

Full Trace with Agent Metadata

Include agent information for better context:

{
  "trace": {
    "id": "trace-456",
    "agent": {
      "id": "support-agent-v2",
      "name": "Customer Support Bot",
      "description": "Handles customer inquiries and support tickets",
      "type": "customer-support",
      "version": "2.1.0",
      "framework": "langchain"
    },
    "userMessage": "Can you help me track my package?",
    "agentResponse": "I'd be happy to help! Let me look up your order...",
    "outcome": "success",
    "duration": 1250
  }
}

Multi-Turn Conversation

Analyze a specific turn within a longer conversation:

{
  "trace": {
    "id": "trace-789",
    "agentId": "sales-assistant",
    "sessionId": "session-abc123",
    "turnNumber": 3,
    "totalTurns": 5,
    "conversationHistory": [
      { "role": "user", "content": "I'm looking for a laptop" },
      { "role": "assistant", "content": "What's your budget and primary use case?" },
      { "role": "user", "content": "Around $1500, mostly for software development" }
    ],
    "userMessage": "Do you have any with 32GB RAM?",
    "agentResponse": "Yes! I recommend the ThinkPad X1 Carbon with 32GB RAM...",
    "outcome": "success"
  }
}

Trace with Model & Token Information

Track LLM usage and costs:

{
  "trace": {
    "id": "trace-cost-analysis",
    "agentId": "gpt4-agent",
    "userMessage": "Write me a detailed marketing strategy",
    "agentResponse": "Here's a comprehensive 12-month marketing strategy...",
    "model": {
      "provider": "openai",
      "model": "gpt-4-turbo",
      "temperature": 0.7,
      "maxTokens": 4096
    },
    "tokenUsage": {
      "prompt": 150,
      "completion": 2500,
      "total": 2650,
      "estimatedCost": 0.08
    },
    "duration": 8500,
    "outcome": "success"
  }
}

Trace with Tool Calls

When your agent uses tools/functions:

{
  "trace": {
    "id": "trace-tools",
    "agentId": "assistant-with-tools",
    "userMessage": "What's the weather in New York and book me a restaurant for tonight",
    "agentResponse": "It's 72°F and sunny in New York. I've booked a table at Gramercy Tavern for 7 PM.",
    "toolCalls": [
      {
        "name": "get_weather",
        "input": { "city": "New York" },
        "output": { "temp": 72, "condition": "sunny" },
        "durationMs": 150,
        "status": "success"
      },
      {
        "name": "book_restaurant",
        "input": { "city": "New York", "time": "19:00", "party_size": 2 },
        "output": { "confirmation": "GRT-12345", "restaurant": "Gramercy Tavern" },
        "durationMs": 890,
        "status": "success"
      }
    ],
    "outcome": "success"
  }
}

Trace with RAG/Retrieval Context

For RAG-enabled agents:

{
  "trace": {
    "id": "trace-rag",
    "agentId": "knowledge-base-agent",
    "userMessage": "What's our refund policy for digital products?",
    "agentResponse": "Our digital product refund policy allows returns within 14 days...",
    "retrievalContext": {
      "query": "refund policy digital products",
      "vectorStore": "pinecone",
      "embeddingModel": "text-embedding-3-small",
      "searchType": "hybrid",
      "chunks": [
        {
          "content": "Digital products may be returned within 14 days of purchase...",
          "source": "policies/refund-policy.md",
          "score": 0.92
        },
        {
          "content": "Exceptions to digital refunds include: downloadable content...",
          "source": "policies/refund-exceptions.md",
          "score": 0.85
        }
      ]
    },
    "outcome": "success"
  }
}

Trace with Business Metrics

Track business impact:

{
  "trace": {
    "id": "trace-metrics",
    "agentId": "sales-agent",
    "userMessage": "I'd like to upgrade my subscription",
    "agentResponse": "I've upgraded you to the Pro plan! You'll see the changes...",
    "outcome": "success"
  },
  "businessMetrics": {
    "revenueImpact": 299,
    "customerSatisfaction": 95,
    "conversionRate": 1,
    "timeToResolution": 45
  }
}

Or with detailed metric format:

{
  "businessMetrics": {
    "revenueImpact": {
      "value": 299,
      "unit": "usd",
      "label": "Monthly Revenue Impact",
      "category": "revenue"
    },
    "satisfactionScore": {
      "value": 4.8,
      "unit": "rating",
      "label": "Customer Satisfaction",
      "category": "satisfaction"
    }
  }
}

Batch Analyze Multiple Traces

{
  "traces": [
    {
      "id": "batch-1",
      "userMessage": "Reset my password",
      "agentResponse": "I've sent a password reset link to your email.",
      "outcome": "success"
    },
    {
      "id": "batch-2",
      "userMessage": "Delete my account immediately",
      "agentResponse": "I've deleted your account.",
      "outcome": "policy_violation"
    }
  ],
  "agent": {
    "id": "support-bot",
    "name": "Support Assistant",
    "type": "customer-support"
  },
  "options": {
    "continueOnError": true,
    "parallelism": 3
  }
}

Search for Similar Issues

Use trace_search to find traces where the agent failed to verify customer identity

Get Failure Patterns

Use trace_patterns with agentId "customer-support" and timeRange "7d" to see recent failure patterns

Available Prompts

| Prompt | Description | |--------|-------------| | analyze_failure | Analyze a failed trace to identify root cause | | compare_traces | Compare two traces to understand differences | | debug_pattern | Debug a recurring failure pattern | | improve_agent | Suggest improvements for an agent | | investigate_issue | Investigate a reported issue |

Available Resources

| URI | Description | |-----|-------------| | trace://schema | JSON schema for trace objects | | trace://outcomes | List of trace outcome types | | trace://severities | List of severity levels |

API Key Tiers

| Tier | Rate Limit | Monthly Quota | Features | |------|------------|---------------|----------| | Free | 10/min | 100 | Basic explainability | | Starter | 60/min | 5,000 | + Semantic search, batch analysis, pattern detection | | Professional | 300/min | 50,000 | + Business metrics, webhooks, counterfactual analysis | | Enterprise | 1,000/min | Unlimited | All features + dedicated support |

Trace Schema Reference

The full trace schema supports these fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Required. Unique trace identifier | | userMessage | string | Required. The user's message | | agentResponse | string | The agent's response | | agentId | string | Agent identifier | | agent | object | Full agent metadata (id, name, description, type, version, framework, tags) | | companyId | string | Company identifier (multi-tenant) | | userIntent | string | What the user was trying to accomplish | | outcome | enum | success, hallucination, policy_violation, tone_issue, retrieval_miss, error, partial_success, timeout, unknown | | severity | enum | low, medium, high, critical | | duration | number | Total duration in milliseconds | | timestamp | datetime | When the trace occurred | | sessionId | string | Conversation/session identifier | | turnNumber | number | Which turn in conversation (1-indexed) | | totalTurns | number | Total turns in conversation | | conversationHistory | array | Previous messages in conversation | | model | object | LLM info (provider, model, version, temperature, maxTokens) | | tokenUsage | object | Token counts (prompt, completion, total, estimatedCost) | | toolCalls | array | Tool/function calls made during trace | | retrievalContext | object | RAG context (query, chunks, vectorStore, searchType) | | spans | array | Detailed span breakdown for observability | | error | object | Error details (code, message, stack, type) | | tags | array | Tags for categorization | | metadata | object | Any custom metadata | | source | object | SDK/environment info |

Security

• API Key Authentication: HMAC-SHA256 hashed keys with thk_ prefix
• Company Isolation: All queries scoped to authenticated company
• Rate Limiting: Redis-based sliding window per API key
• Audit Logging: All tool calls logged for compliance

Advanced Configuration

import { McpExplainerServer } from '@thinkhive/mcp-explainer';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpExplainerServer({
  name: 'my-explainer',
  version: '1.0.0',
  auth: {
    required: true,
    apiUrl: 'https://demo.thinkhive.ai',
    staticApiKey: process.env.THINKHIVE_API_KEY,
  },
  rateLimit: {
    enabled: true,
    redisUrl: process.env.REDIS_URL,
    windowMs: 60000,
    keyPrefix: 'mcp:rate:',
    limits: {
      free: 10,
      starter: 60,
      professional: 300,
      enterprise: 1000,
    },
  },
  audit: {
    enabled: true,
    level: 'info',
    logInput: true,
    logOutput: false,
    maxStringLength: 500,
  },
  features: {
    tools: true,
    resources: true,
    prompts: true,
  },
});

const transport = new StdioServerTransport();
await server.connect(transport);

API Endpoints

When running the HTTP transport, these endpoints are available:

| Endpoint | Method | Description | |----------|--------|-------------| | /mcp/tools | GET | List available tools | | /mcp/tools/{name} | POST | Execute a tool | | /mcp/resources | GET | List available resources | | /mcp/resources/{uri} | GET | Read a resource | | /mcp/prompts | GET | List available prompts | | /mcp/prompts/{name} | POST | Execute a prompt | | /mcp/sse | GET | Server-sent events stream |

Troubleshooting

"API key required" error

Make sure THINKHIVE_API_KEY environment variable is set in your Claude Code config.

"Invalid API key format" error

API keys must start with thk_ and be at least 40 characters.

Rate limit exceeded

Wait for the rate limit window to reset (1 minute) or upgrade your tier.

Connection timeout

Check that THINKHIVE_API_URL is reachable from your network.

Links

• ThinkHive Platform
• Explainer API Documentation
• MCP Specification
• GitHub Issues

License

MIT