Disclaimer: this project and documentation were created with active usage of AI with basic code and content review and are in the "beta" state as a part of POC project. There can be errors in documentation.

Insight Digger MCP

Enterprise-grade Model Context Protocol (MCP) system for data analysis with Claude Desktop integration.

Architecture Overview

This project provides a sophisticated 3-layer MCP architecture designed for enterprise environments:

1. MCP Bridge ↔ MCP Client Flask API (Custom HTTP REST endpoints)

2. MCP Client Flask API ↔ MCP Server subprocess (Standard MCP protocol)

3. MCP Server ↔ Backend Data API (HTTP calls to enterprise backend)

Key Enterprise Features

• 🔐 Dynamic JWT Authentication: 14-day JWT tokens with session management

• 🧠 Intelligent Caching: Parameter caching and auto-injection for efficient workflows

• 📋 Workflow Guidance: LLM-optimized tool orchestration with conversation management

• 👥 Multi-User Support: Centralized service with session isolation

• 🏢 Enterprise Integration: Compatible with existing authentication and monitoring systems

Setup Options

Option 1: Claude Desktop Integration (Recommended)

For end users who want to use Claude Desktop with Insight Digger:

1. Install the NPX Bridge

2. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Note: The MCP_CLIENT_URL environment variable is optional. By default, the system will use Sandsiv's hosted MCP service. Only provide this variable if you're deploying your own version of the data-narrator-mcp service.

3. Usage in Claude Desktop

1. Authenticate first: Use the setup_authentication tool with your API URL and JWT token

2. Start analysis: Begin with list_sources to see available data

3. Follow the workflow: The system guides you through multi-step analysis processes

Option 2: Direct API Integration (For developers)

For custom integrations or testing:

1. Start the MCP Services

2. Use the REST API

Development Setup

Prerequisites

• Python 3.8+

• Node.js 18+ (for NPX bridge)

• Access to Insight Digger backend API

Local Development

Testing the NPX Bridge Locally

Authentication Flow

JWT Token Management

• Lifetime: 14 days

• Refresh: Through the main platform web UI (outside MCP scope)

• Validation: Bridge handles expired tokens by requesting re-authentication

Session Management

• Single Session: One active session per bridge instance

• Session ID: UUID generated for each bridge startup

• Isolation: Multiple Claude Desktop instances use separate sessions

Tools & Workflow

Available Analysis Tools

The system provides LLM-optimized tools for:

• 📊 Data Source Discovery: list_sources, get_source_structure

• ⚙️ Analysis Configuration: prepare_analysis_configuration

• 🚀 Execution: execute_analysis_from_config

• 📈 Results: Interactive dashboards and summaries

Intelligent Caching

• Parameter Injection: Previously fetched data automatically included in subsequent calls

• Workflow Memory: System remembers source selections, configurations, and analysis state

• Efficiency: LLM doesn't need to repeat large data structures between steps

Error Handling

• Authentication Errors: Clear guidance for JWT/URL validation failures

• Tool Errors: Contextual error messages from backend systems

• Session Errors: Automatic cleanup and re-authentication prompts

Configuration

Environment Variables

• MCP_CLIENT_URL: URL of the MCP Client Flask API service

• INSIGHT_DIGGER_API_URL: Backend API URL (configured in MCP server layer)

Service Configuration

The MCP Server (mcp_server.py) connects to your backend API using configuration provided during the /init call.

Documentation

• docs/mcp_bridge_implementation_guide.md - Detailed bridge architecture

• docs/integration_guide.md - Integration patterns

• docs/mcp_client_development_plan.md - Client development guide

• docs/mcp_server_development_plan.md - Server development guide

Production Deployment

Service Deployment

NPX Package Publishing

Monitoring

• Service logs: journalctl -u data-narrator-mcp -f

• Bridge logs: Console output in Claude Desktop

• Session tracking: All sessions logged with UUIDs

Security & Production Readiness

✅ Status: Ready for external publication
🔐 Security: Comprehensive credential validation implemented
📊 Performance: Optimized with session reuse and direct validation

Security Features

• Immediate credential validation during /init endpoint

• Session reuse optimization - no redundant validation calls

• Proper HTTP status codes (401 for auth failures, 500 for server errors)

• Input validation for API URLs and JWT tokens

• Resource efficiency - MCP servers created only for valid credentials

• 5-second timeout for validation requests

Security Considerations

• JWT Tokens: Never logged or stored permanently

• Session Isolation: Proper cleanup prevents cross-session data leakage

• HTTPS Required: All production communications must use HTTPS

• Enterprise Auth: Integrates with existing authentication systems

• Immediate Auth Feedback: Invalid credentials rejected in <5 seconds

• Resource Protection: No MCP instances created for invalid credentials

See SECURITY.md for detailed security documentation.

Support

For issues or questions:

1. Check the documentation in the docs/ folder

2. Review the service logs for error details

3. Verify JWT token validity and API connectivity

4. Ensure MCP Client service is running and accessible

License

MIT License - See LICENSE file for details.