Overview

Mxcp is an open-source Model Context Protocol (MCP) server framework designed for building enterprise-grade data and model backends using YAML, SQL, and Python. It provides a lightweight, extensible platform to declare data endpoints, transformation pipelines, authorization policies, and observability hooks in a reproducible, version-controlled way. The goal is to make it easy to expose data and model context to downstream services (including LLMs) while retaining control over access, auditing, and transformation logic.

The server is useful when teams need predictable, auditable data access for analytics, ETL, and model-serving scenarios. Developers can define endpoints declaratively with YAML, implement complex logic in Python, and leverage SQL for data retrieval. Built-in primitives for authentication, monitoring, and policy enforcement simplify compliance requirements and reduce the custom integration surface for enterprise deployments.

Features

Declarative endpoint definitions using YAML for predictable configuration-as-code
SQL-first data access with support for parameterized queries and connection pooling
Python hooks for data transformation, enrichment, and custom business logic
Auth and authorization primitives (JWT/OAuth-compatible patterns)
Policy enforcement (row/column-level masking, allow/deny rules)
Observability: metrics, logs, and request tracing integration
Pluggable storage and connector model (databases, files, object stores)
CLI and REST API for managing and invoking endpoints
Lightweight and extensible architecture suitable for containerized deployment

Installation / Configuration

Clone the repository and run with Docker Compose for a quick start:

git clone https://github.com/raw-labs/mxcp.git
cd mxcp
docker-compose up --build

Or install and run from Python (for development):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export MXCP_CONFIG=./config/mxcp.yml
python -m mxcp.server

Minimal configuration file (config/mxcp.yml):

server:
  host: 0.0.0.0
  port: 8080
logging:
  level: INFO
auth:
  jwt_secret: "changeme"
  issuer: "my-org"
datasources:
  - name: analytics_db
    type: postgres
    dsn: "postgresql://user:pass@db:5432/analytics"

Environment variables commonly used:

MXCP_CONFIG — path to YAML config
MXCP_LOG_LEVEL — override log level
MXCP_JWT_SECRET — secret for signing tokens

Available Tools

CLI: mxcp-cli for listing endpoints, testing queries, and applying configs
REST API: endpoints to invoke defined resources, manage policies, and inspect metrics
Web UI (optional): lightweight console for browsing endpoint definitions and logs
Connectors: Postgres, MySQL, SQLite, S3, and generic JDBC/ODBC adapters
Monitoring: Prometheus metrics endpoint (/metrics) and tracing headers

Component reference

Component	Purpose	Location
YAML config	Declare endpoints, policies, and datasources	/config
SQL templates	Data retrieval and parameterized queries	/sql
Python hooks	Custom transformations and UDFs	/handlers
Auth module	Token validation and policy evaluation	/auth

Use Cases

Declarative ETL pipeline

Define an extraction endpoint in YAML that runs a SQL query, then register a Python transformer to normalize fields and write to a data warehouse.

Example YAML snippet:

endpoints:
  - name: users_daily_extract
    type: etl
    source: analytics_db
    query: sql/users_daily.sql
    transformer: handlers.normalize_users:transform
    destination: dw.users

SQL-backed model context for LLMs

Expose curated rows via a REST endpoint that accepts natural-language filters turned into SQL parameters. Apply row-level masking policy before returning results.

Policy-enforced analytics API

Use the auth module to validate JWT tokens, map roles to policies, and enforce column masking (e.g., hide PII for non-privileged roles). Policies are declared in YAML and executed in the request pipeline.

Policy example:

policies:
  - name: mask_pii
    rules:
      - target: users.email
        action: mask
        roles_exempt: ["data_admin"]

Ad-hoc SQL exploration with safe execution

Developers can define parameterized SQL templates and allow read-only execution via the CLI or REST API. Queries run through connection pooling and timeout controls to protect production systems.

Getting Help and Contributing

Repository: https://github.com/raw-labs/mxcp
Look for examples in the examples/ directory for common patterns (ETL, masking, SQL templates).
Open issues and pull requests for feature requests, bug reports, and integrations.

This server is intended as a foundation: extend connectors, add policy types, or integrate with your observability stack to match enterprise requirements.

Mxcp MCP Server: Enterprise YAML SQL Python