The structured methodology for building production-ready MCP servers with enterprise security, data quality, and comprehensive testing
๐ What Makes MXCP Different?MXCP isn't just another MCP implementation - it's a complete methodology for building production AI applications the right way:
The Production-Ready Approach# 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:
1. Start with Data Quality# 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
mxcp validate # Structure is correct mxcp test # Logic works as expected mxcp lint # Metadata helps LLMs mxcp evals # AI uses tools safely5. Deploy with Confidence
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.
Choose Your Implementation StyleSQL for Data Queries
# 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
Python for Complex Logic
# 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
} ๐ก Real-World Example: Combining SQL & Python
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?
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:
๐ See all features for a complete overview of MXCP's capabilities.
Policy Enforcement in YAML# 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 for Complex Operations
# 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 ๐๏ธ Architecture: Built for Production
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ 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:
# 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๐ก Key Implementation Features 1. Choose the Right Tool for the Job Use SQL When: Use Python When:
# 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 3. Python Example: Complex Logic
# 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)} Tools, Resources, Prompts
Define your AI interface using MCP (Model Context Protocol) specs:
MXCP supports two implementation approaches:
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๐ Operations & Monitoring
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:
For specific setup instructions, see:
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:
MXCP is released under the Business Source License 1.1 (BSL). It is free to use for development, testing, and most production scenarios. However, production use as part of a hosted or managed service that enables third parties to run models, workflows, or database queries requires a commercial license. This includes:
The license automatically converts to the MIT license four years after the release of each version. You can view the source code and contribute to its development.
For commercial licensing inquiries, please contact mxcp@raw-labs.com.
Built for production AI applications: Enterprise-grade MCP framework that combines the simplicity of YAML configuration with the power of SQL and Python, wrapped in comprehensive security and governance.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4