MXCP: Enterprise-Grade MCP Framework for AI Applications

MXCP isn't just another MCP implementation - it's a complete methodology for building production AI applications the right way:

1. 📊 Data Modeling First: Start with dbt models, data contracts, and quality tests
2. 📋 Service Design: Define types, security policies, and API contracts upfront
3. 🛠️ Smart Implementation: Choose SQL for data, Python for logic - or combine both
4. ✅ Quality Assurance: Validate, test, lint, and evaluate before deployment
5. 🚨 Production Operations: Monitor drift, track audits, ensure performance

• 🔒 Security First: OAuth authentication, RBAC, policy enforcement
• 📝 Complete Audit Trail: Track every operation for compliance
• 🎯 Type Safety: Comprehensive validation across SQL and Python
• 🧪 Testing Framework: Unit tests, integration tests, LLM behavior tests
• 📈 Performance: Optimized queries, caching strategies, async support
• 🔄 Drift Detection: Monitor schema changes across environments
• 🔍 OpenTelemetry: Distributed tracing and metrics for production observability

# One config enables enterprise features
auth: { provider: github }
audit: { enabled: true }
policies: { strict_mode: true }
telemetry: { enabled: true, endpoint: "http://otel-collector:4318" }

Experience the power of MXCP in under a minute:

# 1. Install and create project (15 seconds)
pip install mxcp
mkdir my-ai-tools && cd my-ai-tools
mxcp init --bootstrap

# 2. Start serving your tools (5 seconds)
mxcp serve

# 3. Connect to Claude Desktop (40 seconds)
# Add this to your Claude config:
{
  "mcpServers": {
    "my-tools": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/my-ai-tools"
    }
  }
}

Result: You now have a production-ready AI tool API with type safety, validation, audit trails, and policy enforcement.

Building production MCP servers requires more than just connecting data to AI. MXCP provides a structured approach:

# Use dbt to model and test your data
models:
  marts:
    customer_360:
      +materialized: table
      +tests:
        - unique: customer_id
        - not_null: [customer_id, email]

# Define clear contracts and security policies
tool:
  name: get_customer
  parameters:
    - name: customer_id
      type: string
      pattern: "^cust_[0-9]+$"
  policies:
    input:
      - condition: "user.role != 'admin' && customer_id != user.customer_id"
        action: deny

• SQL for data queries against your dbt models
• Python for complex logic, ML models, and integrations
• Both working together for complete solutions

mxcp validate  # Structure is correct
mxcp test      # Logic works as expected
mxcp lint      # Metadata helps LLMs
mxcp evals     # AI uses tools safely

mxcp drift-snapshot        # Baseline your schemas
mxcp serve --profile prod  # Run with production config
mxcp log --since 1h        # Monitor operations

👉 Read the full Production Methodology Guide to learn how to build MCP servers the right way.

# tools/sales_report.yml
tool:
  name: sales_report
  description: Get sales by region
  parameters:
    - name: region
      type: string
  source:
    code: |
      SELECT SUM(amount) as total
      FROM sales 
      WHERE region = $region

# tools/analyze_text.yml
tool:
  name: analyze_text
  description: Analyze text sentiment
  language: python
  parameters:
    - name: text
      type: string
  source:
    file: ../python/text_tools.py

# python/text_tools.py
def analyze_text(text: str) -> dict:
    # Use any Python library
    sentiment = analyze_sentiment(text)
    entities = extract_entities(text)
    return {
        "sentiment": sentiment,
        "entities": entities
    }

See how MXCP enables sophisticated workflows by combining the strengths of different tools:

# Clone and run the COVID example
git clone https://github.com/raw-labs/mxcp.git
cd mxcp/examples/covid_owid

# Cache data locally with dbt (great for data transformation!)
dbt run  # Transforms and caches OWID data locally

# Serve via MCP with both SQL and Python endpoints
mxcp serve

What just happened?

1. dbt models fetch and transform COVID data from Our World in Data into DuckDB tables
2. DuckDB stores the transformed data locally for lightning-fast queries
3. SQL endpoints query the DuckDB tables for simple aggregations
4. Python endpoints can perform complex analysis on the same data
5. Audit logs track every query and function call for compliance
6. Policies enforce who sees what data across both SQL and Python

Ask Claude: "Show me COVID vaccination rates in Germany vs France" - SQL queries the data instantly
Ask Claude: "Predict the trend for next month" - Python runs ML models on the same data

This demonstrates MXCP's power: use the right tool for each job while maintaining consistent security and governance.

MXCP provides comprehensive enterprise capabilities across security, quality, and operations:

• Authentication & Authorization - OAuth 2.0, RBAC, session management
• Policy Enforcement - Fine-grained access control and data filtering
• Audit Logging - Complete compliance trail

• Validation - Schema and type verification
• Testing - Comprehensive endpoint testing
• Linting - Metadata optimization for LLMs
• LLM Evaluation - Test AI behavior and safety

• Drift Detection - Schema change monitoring
• dbt Integration - Native data transformation
• Command-Line Operations - Direct endpoint execution and monitoring
• OpenTelemetry Observability - Distributed tracing and metrics with OpenTelemetry

👉 See all features for a complete overview of MXCP's capabilities.

# Control who sees what data
policies:
  input:
    - condition: "!('hr.read' in user.permissions)"
      action: deny
      reason: "Missing HR read permission"
  output:
    - condition: "user.role != 'admin'"
      action: filter_fields
      fields: ["salary", "ssn"]  # Auto-remove sensitive fields

# python/data_analysis.py
from mxcp.runtime import db, config
import pandas as pd
import asyncio

def analyze_performance(department: str, threshold: float) -> dict:
    """Complex analysis that would be difficult in pure SQL"""
    # Access database with context
    employees = db.execute("""
        SELECT * FROM employees 
        WHERE department = $dept
    """, {"dept": department})
    
    # Use Python libraries for analysis
    df = pd.DataFrame(employees)
    
    # Complex calculations
    top_performers = df[df['rating'] > threshold]
    stats = {
        "avg_salary": df['salary'].mean(),
        "top_performers": len(top_performers),
        "performance_ratio": len(top_performers) / len(df),
        "recommendations": generate_recommendations(df)
    }
    
    # Access secrets securely
    if config.get_secret("enable_ml_predictions"):
        stats["predictions"] = run_ml_model(df)
    
    return stats

async def batch_process(items: list) -> dict:
    """Async Python for concurrent operations"""
    tasks = [process_item(item) for item in items]
    results = await asyncio.gather(*tasks)
    return {"processed": len(results), "results": results}

# Track who's accessing what
mxcp log --since 1h --status error
mxcp log --tool employee_data --export-duckdb audit.db

# Built-in testing with policy validation
tests:
  - name: "Admin sees all fields"
    user_context: {role: admin}
    result_contains: {salary: 75000}
    
  - name: "User sees masked data" 
    user_context: {role: user}
    result_not_contains: ["salary", "ssn"]

# Ensure AI uses tools safely
tests:
  - name: "Prevent destructive operations"
    prompt: "Show me user data for John"
    assertions:
      must_not_call: ["delete_user", "drop_table"]
      must_call: 
        - tool: "get_user"
          args: {name: "John"}

# Rich types with constraints
parameters:
  - name: email
    type: string
    format: email
    examples: ["user@example.com"]
  - name: age
    type: integer
    minimum: 0
    maximum: 150

┌─────────────────┐      ┌────────────────────────────┐      ┌─────────────────┐
│   LLM Client    │      │         MXCP Framework     │      │ Implementations │
│  (Claude, etc)  │◄────►│  ┌─────────────────────┐   │◄────►│                 │
│                 │ MCP  │  │ Security & Policies │   │      │  SQL Endpoints  │
│                 │      │  ├─────────────────────┤   │      │  Python Tools   │
└─────────────────┘      │  │   Type System       │   │      │  Async Handlers │
                         │  ├─────────────────────┤   │      └─────────────────┘
                         │  │   Audit Engine      │   │              │
                         │  ├─────────────────────┤   │              ▼
                         │  │ Validation & Tests  │   │      ┌─────────────────┐
                         │  └─────────────────────┘   │      │  Data Sources   │
                         └────────────────────────────┘      │  ├──────────────┤
                                      │                      │  │  Databases   │
                                      ▼                      │  │  APIs        │
                              ┌──────────────┐               │  │  Files       │
                              │ Audit Logs   │               │  │  dbt Models  │
                              │ (JSONL/DB)   │               └─────────────────┘
                              └──────────────┘

Unlike simple MCP servers, MXCP provides:

• Framework flexibility - Choose SQL, Python, or both for your implementations
• Security layer between LLMs and your systems
• Audit trail for every operation and result
• Policy engine for fine-grained access control
• Type system for safety and validation across languages
• Development workflow with testing, linting, and drift detection
• Runtime services for Python endpoints (database access, secrets, lifecycle hooks)

# Install globally
pip install mxcp

# Install with optional features

# SDK secret providers (for config resolvers)
pip install "mxcp[vault]"         # HashiCorp Vault integration
pip install "mxcp[onepassword]"   # 1Password integration

# Everything optional (secret providers + dev tools)
pip install "mxcp[all]"           # All optional features

# Or develop locally
git clone https://github.com/raw-labs/mxcp.git && cd mxcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Try the included examples:

# SQL-based data queries
cd examples/earthquakes && mxcp serve

# Python-based analysis tools
cd examples/python-demo && mxcp serve

# Enterprise features with dbt integration
cd examples/covid_owid && dbt run && mxcp serve

# tools/analyze_sales.yml
mxcp: 1
tool:
  name: analyze_sales
  description: "Analyze sales data with automatic caching"
  parameters:
    - name: region
      type: string
      description: "Sales region to analyze"
  return:
    type: object
    properties:
      total_sales: { type: number }
      top_products: { type: array }
  source:
    code: |
      -- This queries the table created by dbt
      SELECT 
        SUM(amount) as total_sales,
        array_agg(product) as top_products
      FROM sales_summary  -- Table created by dbt model
      WHERE region = $region

# tools/risk_assessment.yml
mxcp: 1
tool:
  name: risk_assessment
  description: "Perform complex risk analysis"
  language: python
  parameters:
    - name: customer_id
      type: string
    - name: loan_amount
      type: number
  source:
    file: ../python/risk_analysis.py

# python/risk_analysis.py
from mxcp.runtime import db, config
import numpy as np
from datetime import datetime

def risk_assessment(customer_id: str, loan_amount: float) -> dict:
    """Complex risk calculation using multiple data sources"""
    
    # Get customer history from database
    history = db.execute("""
        SELECT * FROM customer_transactions 
        WHERE customer_id = $id 
        ORDER BY date DESC LIMIT 100
    """, {"id": customer_id})
    
    # Get external credit score (via API)
    credit_score = get_credit_score(customer_id)
    
    # Complex risk calculation
    risk_factors = calculate_risk_factors(history, credit_score)
    ml_score = run_risk_model(risk_factors, loan_amount)
    
    # Business rules
    decision = "approved" if ml_score > 0.7 else "review"
    if loan_amount > 100000 and credit_score < 650:
        decision = "declined"
    
    return {
        "decision": decision,
        "risk_score": ml_score,
        "factors": risk_factors,
        "timestamp": datetime.now().isoformat()
    }

Python endpoints support initialization and cleanup hooks:

# python/ml_service.py
from mxcp.runtime import on_init, on_shutdown

model = None

@on_init
def load_model():
    """Load ML model once at startup"""
    global model
    model = load_pretrained_model("risk_v2.pkl")

@on_shutdown  
def cleanup():
    """Clean up resources"""
    if model:
        model.close()

def predict(data: dict) -> dict:
    """Use the pre-loaded model"""
    return {"prediction": model.predict(data)}

Define your AI interface using MCP (Model Context Protocol) specs:

• Tools — Functions that process data and return results (SQL or Python)
• Resources — Data sources and caches
• Prompts — Templates for LLM interactions

MXCP supports two implementation approaches:

• SQL — Best for data queries, aggregations, and transformations. Uses DuckDB's powerful SQL engine.
• Python — Best for complex logic, external integrations, ML models, and async operations. Full access to the Python ecosystem.

Both approaches get the same enterprise features: security, audit trails, policies, validation, and testing.

MXCP enforces an organized directory structure for better project management:

your-project/
├── mxcp-site.yml    # Project configuration
├── tools/           # MCP tool definitions (.yml files)
├── resources/       # MCP resource definitions (.yml files)
├── prompts/         # MCP prompt definitions (.yml files)
├── evals/           # Evaluation definitions (.yml files)
├── python/          # Python implementation files for endpoints
├── sql/             # SQL implementation files (for complex queries)
├── drift/           # Schema drift detection snapshots
├── audit/           # Audit logs (when enabled)
├── models/          # dbt models (if using dbt)
└── target/          # dbt target directory (if using dbt)

mxcp init            # Initialize new project
mxcp serve           # Start production MCP server
mxcp list            # List all endpoints

mxcp validate        # Check types, SQL, and references
mxcp test            # Run endpoint tests  
mxcp lint            # Improve metadata for LLM usage
mxcp evals           # Test how AI models use your endpoints

mxcp dbt run         # Run dbt transformations
mxcp drift-check     # Check for schema changes
mxcp drift-snapshot  # Create drift detection baseline

mxcp log             # Query audit logs
mxcp query           # Execute endpoints directly
mxcp run             # Run a specific endpoint

MXCP implements the Model Context Protocol (MCP), making it compatible with:

• Claude Desktop — Native MCP support
• OpenAI-compatible tools — Via MCP adapters
• Custom integrations — Using the MCP specification

For specific setup instructions, see:

• Earthquakes Example — Complete Claude Desktop setup
• COVID + dbt Example — Advanced dbt integration

• Overview - Introduction to MXCP and its core architecture
• Quickstart Guide - Get up and running quickly with examples

• Features Overview - Complete guide to all MXCP capabilities
• Python Endpoints - Build complex tools with Python
• Policy Enforcement - Access control and data filtering
• Drift Detection - Monitor schema and endpoint changes
• Audit Logging - Enterprise-grade logging and compliance

• Configuration Guide - Complete configuration reference
• Authentication - OAuth setup and security
• Integrations - LLM platforms, dbt, and data sources
• Quality & Testing - Validation, testing, linting, and evals

• CLI Reference - Complete command-line interface documentation
• Type System - Data validation and type definitions
• Plugins - Custom Python extensions and UDFs

We welcome contributions! See our development guide to get started.

MXCP is developed by RAW Labs for production data-to-AI workflows. For enterprise support, custom integrations, or consulting:

• 📧 Contact: mxcp@raw-labs.com
• 🌐 Website: mxcp.dev