Lumenore Analytics MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to Lumenore's analytics and natural language query capabilities. Built with FastMCP and Python 3.13 for scalable data analytics integration.

Quick Start

1. Install & Run

2. Connect Your AI Assistant

• URL: http://localhost:8080/mcp

• Transport: Streamable HTTP

3. Start Analyzing

📖 Full Documentation | 🐛 Report Issues | 🔒 Privacy Policy

Table of Contents

• Overview

• Installation

• Configuration

• Available Tools

• Usage Examples

• Authentication

• Security & Privacy

• Troubleshooting

• Contributing

• Support

• License

Overview

This MCP server provides AI assistants with access to Lumenore's powerful analytics capabilities:

• Natural Language Queries: Convert questions to data insights

• Advanced Analytics: Trends, predictions, correlations, outliers, changes, Pareto analysis

• Real-time Processing: Stream responses for large datasets

• Zero Data Storage: In-memory processing with no persistent logging. When the MCP Server forwards requests to Lumenore's backend, Lumenore's privacy policies apply

Installation

Prerequisites

• Python 3.13+

• Lumenore API token

• Access to Lumenore server instance

Setup

Configuration

Create a .env file with your credentials:

Token Format: Valid JWT without "Bearer " prefix (server adds this automatically)

Running the Server

Start the MCP server:

The server runs on http://0.0.0.0:8080 with SSE transport for real-time streaming.

Connecting Your AI Assistant

Claude for Desktop

1. Settings → MCP Servers

2. Add Server with:

   Name: Lumenore Analytics URL: http://localhost:8080/mcp Transport: Streamable HTTP

Programmatic Access (Python)

Connection Details:

• Protocol: MCP 2024-11-05+

• Transport: Streamable HTTP (SSE)

• Port: 8080 (default)

• Auth: No MCP-level auth required

Test Connection:

Authentication

Getting Your API Token

1. Visit https://preview.lumenore.com/ and sign in

2. Go to Account Settings → API Access

3. Generate a new token with required permissions

4. Copy and store securely (won't be shown again)

Configuration

Set your token in .env file:

Token Requirements:

• Valid JWT format (no "Bearer " prefix)

• Permissions: read:datasets, read:analytics, read:nlq, read:predictions

Security Best Practices

• ✅ Store in environment variables or secure vaults

• ✅ Rotate tokens every 90 days

• ✅ Use separate tokens for dev/prod

• ❌ Don't commit tokens to version control

• ❌ Don't share tokens or log them

Troubleshooting

"Authorization token missing or invalid":

• Verify LUMENORE_API_KEY is set

• Check token format and expiration

• Ensure Lumenore AI credits are available

Available Tools

The server provides 8 powerful tools for data analysis:

Dataset Management

get_dataset_metadata - Lists available datasets and schema IDs

Natural Language Queries

nlq_to_data - Converts questions to structured data

Advanced Analytics

get_trend_data - Identifies temporal patterns and trends get_prediction_data - Generates forecasts and predictions get_outlier_data - Detects anomalies and unusual patterns get_correlation_data - Analyzes variable relationships get_change_data - Detects pattern shifts and transitions get_pareto_data - Performs 80/20 impact analysis

Error Handling

All tools return standardized responses:

• Success: {"data": {...}, "status": "success"}

• Validation Error: {"error": "...", "status": "validation_error"}

• Service Error: {"error": "...", "status": "error"}

Performance

• Response Time: 1-7 seconds

• Timeout: 60 seconds

• Concurrency: Multiple simultaneous requests supported

Best Practices

1. Start with get_dataset_metadata to find schema IDs

2. Be specific in natural language queries

3. Always check the status field in responses

4. Cache frequent queries for better performance

Usage Examples

Here are three realistic examples showing how AI assistants can interact with the Lumenore Analytics MCP Server:

Example 1: Sales Performance Analysis

Scenario: A business analyst wants to understand sales performance for the last quarter.

AI Assistant Interaction:

Expected Insights:

• Regional sales breakdown with totals

• Monthly trend visualization showing growth/decline

• Product contribution analysis highlighting key revenue drivers

Example 2: Customer Behavior Analysis

Scenario: A marketing team wants to understand customer purchasing patterns and detect anomalies.

AI Assistant Interaction:

Expected Insights:

• Customer segmentation by demographics and spending

• Identification of potential fraud or VIP customers

• Key drivers of customer value for targeted marketing

Example 3: Inventory Optimization

Scenario: An operations manager needs to optimize inventory levels based on demand patterns and forecasts.

AI Assistant Interaction:

Expected Insights:

• Historical demand patterns by category

• Future demand forecasts with confidence intervals

• Early warning of demand pattern shifts

• Data-driven inventory optimization recommendations

Benefits:

• Automated data refresh without manual intervention

• Real-time insights for operational decision-making

• Reduced load on backend systems through efficient caching

Best Practices from Examples

1. Start with Metadata: Always use get_dataset_metadata to understand available datasets

2. Combine Tools: Use multiple tools together for comprehensive analysis

3. Specific Queries: Be clear and specific in natural language queries

4. Error Handling: Always check response status before processing results

5. Performance: Cache frequently accessed data to improve response times

Claude Prompts

Here are example prompts you can use with Claude when connected to this MCP server:

For Sales Analysis:

"Use the Lumenore Analytics tools to analyze our Q4 sales performance. I need to see regional breakdowns, identify top-performing products, and understand sales trends."

For Customer Insights:

Analyze customer demographics, find any unusual purchasing patterns, and identify what factors drive customer value. Use the available analytics tools to provide comprehensive insights."

For Inventory Management:

"generate forecasts for next quarter, and identify any recent changes in demand behavior using the predictive and trend analysis tools."

Configuration

The server uses Pydantic for configuration management. Configure via environment variables or .env file:

Creating .env file:

Token Format: The API key should be a valid JWT token without the "Bearer " prefix (the server adds this automatically).

Error Handling

All tools implement comprehensive error handling with specific error types:

Development

Running in Development Mode

Testing the Server

You can test the MCP server using any MCP-compatible client or by making HTTP requests to the SSE endpoint:

Security & Privacy

Security Overview

The Lumenore Analytics MCP Server implements multiple layers of security to protect your data and API credentials:

Data Protection

• In-Memory Processing: All data is processed in-memory and immediately discarded after response generation

• No Data Storage: The MCP server does not store or log any user queries, schema IDs, or response data

• Secure Communication: All backend API requests use HTTPS encryption

• Token Security: API tokens are never logged, stored, or exposed in responses

Authentication Security

• OAuth 2.0 Bearer Tokens: Industry-standard authentication using JWT tokens

• Token Validation: Every request validates token authenticity and permissions

• No MCP-Level Auth: MCP connection doesn't require authentication (backend auth is handled server-side)

• Security Monitoring: Failed authentication attempts are logged for security analysis

API Token Best Practices

• Environment Variables: Store tokens in environment variables or .env files (never in code)

• Regular Rotation: Rotate tokens every 90 days or as needed

• Scope Limitation: Use tokens with minimal required permissions

• Separate Environments: Use different tokens for development, staging, and production

Privacy Policy

For detailed information about how Lumenore handles your data, please see our Privacy Policy.

Key Privacy Principles

• Minimal Data Processing: Only processes queries and schema IDs provided by users

• No Conversation History: Does not store or log conversation history

• User Control: Users control what data is queried and analyzed

• Compliance: Designed to comply with data protection regulations (GDPR, CCPA)

Data Flow Privacy

Privacy Considerations

• The MCP server acts as a secure proxy between AI assistants and Lumenore's backend

• All privacy and data handling policies of Lumenore's backend API apply to your data

• The server itself does not retain any user data beyond the immediate request processing

• Users are responsible for ensuring their queries comply with applicable data protection laws

Compliance

Regulatory Compliance

• GDPR: Compliant with General Data Protection Regulation

• CCPA: Compliant with California Consumer Privacy Act

• SOC 2: Backend services follow SOC 2 security standards

• ISO 27001: Information security management best practices

Data Residency

• Data processing occurs in Lumenore's cloud infrastructure

• Data residency requirements should be discussed with Lumenore sales team

• Enterprise deployments may support private cloud or on-premise options

Security Configuration

Environment Security

Production Security

• Use dedicated API tokens for production environments

• Implement token rotation automation

• Monitor API usage and set up alerts for unusual activity

• Consider implementing IP allowlisting for API access

• Use VPN or private networks for server communication

Vulnerability Management

Reporting Security Issues

We take security seriously. If you find a vulnerability:

1. Email: askme@lumenore.com

2. Include vulnerability details and reproduction steps

3. We will acknowledge within 24 hours

4. Work with us to resolve the issue before public disclosure

Security Updates

• Security patches are prioritized and deployed quickly

• Subscribe to security notifications via our support channels

• Regular security assessments are performed on the infrastructure

Data Encryption

In Transit

• All API communications use TLS 1.2+ encryption

• HTTPS is enforced for all backend connections

• Certificate pinning can be implemented for enhanced security

At Rest

• Backend data storage uses encryption at rest

• Database encryption protects stored analytics data

• Key management follows industry best practices

Access Control

Principle of Least Privilege

• API tokens should have minimal required permissions

• Separate tokens for different applications and environments

• Regular review of token permissions and usage

Network Security

• Firewall rules restrict access to necessary ports only

• Consider implementing VPN access for server management

• Use network segmentation for production deployments

Troubleshooting

Quick Diagnostic Steps

1. Check server is running: curl -I http://localhost:8080

2. Verify token is loaded: Check server startup logs for "No authorization token" warning

3. Test backend connectivity: curl -I https://preview.lumenore.com

4. Check MCP protocol: Ensure client is using Streamable HTTP transport

Example client configuration:

Logging and Debugging

Enable debug logging:

Check logs for:

• Server startup confirmation

• Authorization token loading

• Request timing information

• Error stack traces

Manual testing with Python:

Getting Help

If you've tried the above steps and still have issues:

1. Check server logs for detailed error messages

2. Verify token validity and permissions

3. Test backend API directly to isolate MCP vs backend issues

4. Review MCP client configuration for transport and URL settings

5. Contact support with logs and error messages (see Support section)

Contributing

We welcome contributions to the Lumenore Analytics MCP Server! Please follow these guidelines:

Code of Conduct

Please note that this project is released with a Contributor Covenant. By participating, you are expected to uphold this code.

How to Contribute

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Setup

Reporting Bugs

Use the issue tracker to report bugs. Include:

• Steps to reproduce

• Expected vs actual behavior

• Environment details (Python version, OS)

Feature Requests

We welcome feature requests through GitHub Issues. Please:

• Search existing issues first

• Provide clear use cases

• Explain the desired functionality

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Contact Information

For technical support and inquiries:

• Email: askme@lumenore.com

• Website: https://lumenore.com/

• Documentation: Lumenore Analytics Docs

Support Channels

Technical Issues:

• Server configuration and setup problems

• Authentication and authorization errors

• API integration questions

• Performance and timeout issues

Feature Requests:

• New analytics capabilities

• Tool enhancements

• Integration improvements

Bug Reports: Please include:

1. Server version and Python version

2. Error messages and logs

3. Steps to reproduce the issue

4. Expected vs actual behavior

Additional Resources

• MCP Protocol: Model Context Protocol Specification

• FastMCP Documentation: FastMCP GitHub

• API Reference: Available through Lumenore support team

Version: 1.0.0
Last Updated: November 2025
Python: 3.13+
MCP Protocol: Compatible with MCP 2024-11-05 specification