MCP Server

The Sidemantic MCP (Model Context Protocol) server enables AI assistants like Claude to query your semantic layer directly.

What is MCP?

Model Context Protocol is a standard for connecting AI assistants to external tools and data sources. The Sidemantic MCP server exposes your semantic layer as a set of tools that AI assistants can use.

Quick Start

1. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "sidemantic": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./path/to/models"]
    }
  }
}

With database:

{
  "mcpServers": {
    "sidemantic": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./path/to/models", "--db", "data/warehouse.db"]
    }
  }
}
Tip

Using uvx automatically manages the sidemantic installation - no need to install anything manually!

2. Test Locally (Optional)

# Try the demo
uvx sidemantic mcp-serve --demo

# Serve your models
uvx sidemantic mcp-serve ./models

# With a DuckDB database
uvx sidemantic mcp-serve ./models --db data/warehouse.db

3. Restart and Query

Restart Claude Desktop and try:

“List all available models in my semantic layer”

“Show me the dimensions and metrics for the orders model”

“Query total revenue by month from the orders model”

Available Tools

The MCP server provides three tools:

list_models

Lists all models in your semantic layer with basic information.

Returns: - Model name - Source table - List of dimension names - List of metric names - Relationship count

Example: > “What models are available?”

get_models

Get detailed information about specific models.

Parameters: - model_names: List of model names to retrieve

Returns: - Full dimension details (type, SQL, description) - Full metric details (aggregation, SQL, filters, description) - Relationship details (type, join conditions) - Source metadata (format, file)

Example: > “Show me all the dimensions and metrics for the orders and customers models”

run_query

Execute queries against the semantic layer.

Parameters: - dimensions: List of dimension references (e.g., ["orders.customer_name", "orders.created_at__month"]) - metrics: List of metric references (e.g., ["orders.total_revenue", "orders.order_count"]) - where: Optional WHERE clause filter - order_by: List of fields to order by - limit: Optional row limit

Returns: - Generated SQL - Result rows - Row count

Examples:

“Query total revenue grouped by customer region”

“Show me monthly revenue for 2024, ordered by month descending”

“Get the top 10 customers by revenue where order status is completed”

Query Syntax

Field References

Always use model.field_name format:

orders.customer_name
orders.total_revenue
customers.region

Time Granularity

Time dimensions support granularity suffixes:

orders.created_at__year
orders.created_at__month
orders.created_at__week
orders.created_at__day

Available granularities: __year, __quarter, __month, __week, __day, __hour

Automatic Joins

Reference fields from multiple models to trigger automatic joins:

dimensions: ["customers.region", "products.category"]
metrics: ["orders.total_revenue"]

This automatically joins orders → customers and orders → products based on relationships defined in your models.

Filters

Use model.field_name in WHERE conditions:

where: "orders.status = 'completed' AND orders.amount > 100"
where: "orders.created_at >= '2024-01-01'"
where: "customers.region IN ('US', 'CA')"

Configuration

Using Environment Variables

You can use environment variables in your Claude Desktop config:

{
  "mcpServers": {
    "sidemantic": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "${HOME}/projects/my-semantic-layer"],
      "env": {
        "DB_PATH": "${HOME}/data/warehouse.db"
      }
    }
  }
}

Multiple Environments

Configure different servers for dev/prod:

{
  "mcpServers": {
    "sidemantic-dev": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./models", "--db", "dev.db"]
    },
    "sidemantic-prod": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./models", "--db", "prod.db"]
    }
  }
}

Example Queries

Here are some example questions you can ask Claude:

Discovery: - “What models are available in my semantic layer?” - “Show me all dimensions and metrics for the orders model” - “What are the relationships between models?”

Simple Aggregations: - “Query total revenue by order status” - “Show me customer count by region” - “What’s the total revenue?”

Time Series: - “Query monthly revenue for 2024” - “Show me daily active users by week” - “Get quarterly revenue trends”

Cross-Model Queries: - “Query total revenue by customer region and product category” - “Show me order count by customer tier and payment method”

Filtered Queries: - “Query revenue for completed orders only” - “Show me customers from the US with total revenue over $10,000” - “Get orders placed in the last 30 days grouped by status”

Top N Queries: - “Show me the top 10 customers by revenue” - “What are the top 5 products by order count?” - “Get the 20 highest revenue days”

Troubleshooting

Server Not Appearing in Claude

  1. Check Claude Desktop config location:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Verify JSON syntax is valid

  3. Restart Claude Desktop completely

  4. Check Claude Desktop logs for errors

Command Not Found

Ensure uvx is installed:

which uvx
# Should show path to uvx executable

If uvx is not available, install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or use pipx instead:

{
  "mcpServers": {
    "sidemantic": {
      "command": "pipx",
      "args": ["run", "sidemantic", "mcp-serve", "./models"]
    }
  }
}

Models Not Found

Verify the path to your models directory is correct and absolute:

{
  "mcpServers": {
    "sidemantic": {
      "command": "sidemantic",
      "args": ["mcp-serve", "/absolute/path/to/models"]
    }
  }
}

Next Steps