@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

• 12 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
• 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
THINKHIVE_API_URL	No	https://demo.thinkhive.ai	ThinkHive API URL
REDIS_URL	No	-	Redis URL for distributed rate limiting

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_delete	Delete a webhook	Professional+

Tool Examples

Analyze a Trace

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

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

Debug a Recurring Issue

Use the debug_pattern prompt to investigate: "Agent is providing incorrect pricing information"

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	Features
Free	10/min	Basic explainability
Starter	60/min	+ Semantic search, batch analysis, pattern detection
Professional	300/min	+ Business metrics, webhooks, counterfactual analysis
Enterprise	1000/min	All features + dedicated support

Security

• API Key Authentication: HMAC-SHA256 hashed keys
• 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://api.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);

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT

Documentation

• Interactive Documentation - Beautiful UI guide with examples
• API Reference - Complete API documentation

Links

• ThinkHive Documentation
• MCP Specification
• API Reference