@thinkhive/mcp-explainer

@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

• Visit https://demo.thinkhive.ai
• Sign in to your account
• Go to Settings > API Keys
• Click Create API Key
• 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
• API Documentation
• MCP Specification
• GitHub Issues

License

MIT