11 KiB
11 KiB
MXCP Expert Claude Skill
A comprehensive Claude skill for working with MXCP (Enterprise MCP Framework) - enabling you to build production-ready MCP servers with SQL and Python endpoints, complete with security, audit trails, and policy enforcement.
What's Included
This skill provides complete guidance for:
- Creating MXCP projects - Initialize and structure production-ready MCP servers
- Endpoint development - Build tools, resources, and prompts using SQL or Python
- Enterprise features - Implement authentication, policies, and audit logging
- dbt integration - Combine data transformation with MCP endpoints
- Quality assurance - Validate, test, lint, and evaluate your endpoints
- Production deployment - Monitor drift, track operations, and ensure security
Installation
- Download the
mxcp-expert.zipfile - In Claude Desktop, go to Settings → Developer → Custom Skills
- Click "Add Skill" and upload the
mxcp-expert.zipfile - The skill will be automatically available when working on MXCP projects
Skill Structure
mxcp-expert/
├── SKILL.md # Main skill file with quick reference
├── assets/ # Project templates and resources
│ ├── project-templates/ # Pre-built MXCP projects
│ │ ├── google-calendar/ # OAuth integration examples
│ │ ├── jira/ jira-oauth/ # Jira integrations
│ │ ├── salesforce/ salesforce-oauth/ # Salesforce integrations
│ │ ├── confluence/ # Confluence integration
│ │ ├── python-demo/ # Python endpoint patterns
│ │ ├── covid_owid/ # dbt data caching example
│ │ ├── keycloak/ # SSO integration
│ │ └── ... # More templates
│ └── schemas/ # JSON Schema definitions for YAML validation
│ ├── mxcp-site-schema-1.json # mxcp-site.yml validation
│ ├── mxcp-config-schema-1.json # config.yml validation
│ ├── tool-schema-1.json # Tool definition validation
│ ├── resource-schema-1.json # Resource definition validation
│ ├── prompt-schema-1.json # Prompt definition validation
│ ├── eval-schema-1.json # Evaluation suite validation
│ └── common-types-schema-1.json # Common type definitions
├── scripts/ # Utility scripts
│ └── validate_yaml.py # YAML validation script
└── references/ # Detailed documentation (23 files)
├── tool-templates.md # Ready-to-use YAML templates for tools/resources/prompts
├── project-selection-guide.md # Decision tree and template selection
├── dbt-core-guide.md # Essential dbt knowledge (seeds, models, Python models)
├── duckdb-essentials.md # DuckDB features and SQL extensions
├── endpoint-patterns.md # Complete endpoint examples
├── python-api.md # Python runtime API reference
├── policies.md # Policy enforcement guide
├── comprehensive-testing-guide.md # Complete testing strategies
├── debugging-guide.md # Systematic debugging workflows
├── error-handling-guide.md # Python error handling patterns
├── dbt-patterns.md # Advanced dbt integration patterns
├── database-connections.md # PostgreSQL, MySQL, SQLite, SQL Server
├── excel-integration.md # Excel file handling with pandas and dbt
├── claude-desktop.md # Claude Desktop setup guide
├── cli-reference.md # Complete CLI documentation
├── type-system.md # Type validation reference
└── ... # 8 more specialized guides
When This Skill is Used
Claude will automatically use this skill for ANY mention or reference to MXCP, including when you:
- Mention "MXCP", "mxcp", "MXCP server", "MXCP project" in any context
- Ask questions about MXCP or its features
- Create, initialize, build, or set up MXCP projects
- Edit or modify MXCP files (mxcp-site.yml, config.yml, tools/resources/prompts)
- Define or work with MCP tools, resources, or prompts using MXCP
- Implement SQL queries or Python endpoints for MXCP
- Configure MXCP features (authentication, policies, audit logging, dbt integration)
- Run MXCP commands (mxcp validate, mxcp test, mxcp serve, mxcp init, mxcp lint)
- Test, validate, lint, or debug MXCP endpoints
- Fix MXCP validation errors or troubleshoot issues
- Deploy MXCP servers to production
Quick Start Examples
Example 1: CSV File to MCP Server
User: "I need to connect my chat to a CSV file with customer data"
Claude: [Uses mxcp-expert skill]
I'll help you create an MXCP server that queries your CSV file.
1. Initialize project:
mkdir customer-mcp && cd customer-mcp
mxcp init --bootstrap
2. Add your CSV as a dbt seed:
cp customers.csv seeds/
3. Create schema definition (seeds/schema.yml):
[Creates proper schema.yml with column types and tests]
4. Load data:
dbt seed
dbt test
5. Create query tool:
[Creates tools/get_customers.yml with parameterized SQL]
6. Test and validate:
mxcp validate && mxcp test
mxcp serve
[Provides complete security-first implementation with validation]
Example 2: API Integration
User: "Connect to Google Calendar API"
Claude: [Uses mxcp-expert skill]
I'll use the google-calendar project template for OAuth integration.
1. Copy template:
cp -r assets/project-templates/google-calendar calendar-mcp
cd calendar-mcp
2. Configure OAuth in project config.yml:
[Creates config.yml with OAuth settings in project directory]
3. Test authentication:
mxcp serve
[Explains OAuth flow]
[Provides complete working OAuth integration]
Example 3: Database Connection
User: "Connect to my PostgreSQL production database"
Claude: [Uses mxcp-expert skill]
I'll help you connect to your PostgreSQL database using DuckDB ATTACH.
1. Create project and config:
mkdir postgres-mcp && cd postgres-mcp
mxcp init --bootstrap
Create config.yml with database credentials (uses environment variables)
2. Create SQL tool with ATTACH:
[Creates tools/query_customers.yml with PostgreSQL ATTACH statement]
3. Set credentials and test:
export DB_HOST="localhost" DB_USER="readonly_user" DB_PASSWORD="xxx"
mxcp validate && mxcp run tool query_customers
4. Alternative: Cache data with dbt for fast queries
[Shows dbt source + model pattern to materialize data]
[Provides both direct query and cached approaches with security best practices]
Key Features Covered
Endpoint Development
- SQL tools for data queries
- Python tools for complex logic
- Resources for data access
- Prompts with Jinja templates
- Combined SQL + Python patterns
Enterprise Features
- OAuth authentication (GitHub, Google, Microsoft, etc.)
- Policy-based access control with CEL expressions
- Comprehensive audit logging (JSONL format)
- Field-level data filtering and masking
- User context testing
Quality Assurance
- Structure validation with
mxcp validate - Functional testing with
mxcp test - Metadata quality checks with
mxcp lint - LLM behavior testing with
mxcp evals
dbt Integration
- Data transformation pipelines
- External data caching
- Incremental model patterns
- Data quality tests
Production Operations
- Drift detection and monitoring
- Audit log querying and export
- Multi-environment profiles
- Secrets management (Vault, 1Password)
- OpenTelemetry observability
Core Principles
This skill prioritizes:
- Security First - Authentication, authorization, parameterized queries, input validation
- Robustness - Error handling, type safety, data quality checks
- Validity - Schema compliance, structure validation
- Testability - Comprehensive test coverage
- Testing - Always validate/test/lint before deployment
Mandatory Workflow
To ensure MXCP servers always work correctly, the agent follows:
- Build incrementally - One tool/component at a time
- Validate continuously -
mxcp validateafter each change - Test before proceeding -
mxcp testmust pass before next step - Verify manually - Run actual tool with real data
- Definition of Done - ALL validation checks must pass
The agent will NEVER declare a project complete unless all validation, tests, and manual verification succeed.
Documentation Coverage
The skill includes comprehensive documentation based on official MXCP docs:
CRITICAL - Start Here:
- build-and-validate-workflow.md - MANDATORY workflow ensuring correctness
- minimal-working-examples.md - Guaranteed-to-work examples (copy, test, customize)
Essential Guides (for most projects):
- project-selection-guide.md - Decision trees, heuristics, when to use which approach
- dbt-core-guide.md - dbt seeds, models, schema.yml (critical for CSV/data projects)
- duckdb-essentials.md - DuckDB SQL features, CSV import, analytics
- excel-integration.md - Excel file handling and pandas integration
- synthetic-data-patterns.md - Generate test data with GENERATE_SERIES
Detailed References:
- endpoint-patterns.md - Complete tool/resource/prompt examples
- python-api.md - Python runtime API and library wrapping patterns
- testing-guide.md - Comprehensive testing strategies
- policies.md - Policy enforcement and security
- type-system.md - Type validation rules
- cli-reference.md - Complete CLI documentation
- claude-desktop.md - Claude Desktop integration
- dbt-patterns.md - Advanced dbt integration patterns
About MXCP
MXCP is an enterprise-grade MCP (Model Context Protocol) framework that provides a structured methodology for building production AI applications:
- Data Quality First - Start with dbt models and data contracts
- Service Design - Define types, security policies, and API contracts
- Smart Implementation - Choose SQL for data, Python for logic
- Quality Assurance - Validate, test, lint, and evaluate
- Production Operations - Monitor drift, track audits, ensure performance
License
This skill compiles information from the MXCP project documentation. MXCP is released under the Business Source License 1.1 (BSL).
For more information about MXCP:
- Website: https://mxcp.dev
- GitHub: https://github.com/raw-labs/mxcp
- Contact: mxcp@raw-labs.com
Skill Version
Version: 1.0.0 Created: October 2025 Based on: MXCP documentation as of October 2025