Install and configure ktx, an executable context layer for data and analytics agents that enables accurate warehouse queries through MCP with semantic layer and skills
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Install and configure ktx, an executable context layer for data and analytics agents that enables accurate warehouse queries through MCP with semantic layer and skills
triggers
["set up ktx for data agent queries","configure ktx semantic layer for warehouse","install ktx context layer with MCP","help me query my data warehouse with ktx","set up ktx for Claude Code data analysis","configure ktx ingestion from dbt and warehouse","troubleshoot ktx mcp server connection","build ktx context from database metadata"]
ktx is a self-improving context layer that teaches AI agents how to query your data warehouse accurately. It ingests metadata from databases, dbt, Looker, Metabase, and wikis to build a semantic layer with approved metric definitions, joinable columns, and business knowledge. Agents access this through MCP (Model Context Protocol) tools and CLI commands.
What ktx Does
Learns from company knowledge — ingests wiki content, removes duplicates, flags contradictions
Maps the data stack — samples tables, detects joinable columns, captures metadata and usage patterns
Builds a semantic layer — combines raw tables and high-level metrics with automatic join resolution
Serves agents at execution — exposes CLI and MCP tools with semantic search across wiki and semantic-layer entities
Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and SQLite. Integrates with dbt, MetricFlow, LookML, Looker, Metabase, and Notion.
Installation
Global CLI Installation
npm install -g @kaelio/ktx
Project-Specific Installation
cd /path/to/your/project
npm install @kaelio/ktx
Verify Installation
ktx --version
ktx --help
Quick Setup
# Create or resume a ktx project in current directory
ktx setup
# Check project readiness
ktx status
The ktx setup command will:
Create or resume a local ktx project
Configure LLM and embedding providers
Set up database connections
Configure context sources (dbt, Looker, etc.)
Build initial context
Install agent integration (MCP)
Project Structure
my-project/
├── ktx.yaml # Project configuration
├── semantic-layer/<connection-id>/ # YAML semantic sources
├── wiki/global/ # Shared business context
├── wiki/user/<user-id>/ # User-scoped notes
├── raw-sources/<connection-id>/ # Ingest artifacts and reports
└── .ktx/ # Local state and secrets (git-ignored)
Important: Commit ktx.yaml, semantic-layer/, and wiki/. Keep .ktx/ local.
Configuration
ktx.yaml Structure
version:1name:my-analytics-projectllm:provider:anthropicmodel:claude-sonnet-4-6embeddings:provider:openaimodel:text-embedding-3-smalldatabases:warehouse:type:postgreshost:localhostport:5432database:analytics# Credentials stored in .ktx/secrets.yamlcontext-sources:dbt_main:type:dbtpath:./dbt-projecttarget:prodlooker_main:type:lookerbase_url:https://company.looker.com# API credentials in .ktx/secrets.yamlagent-integration:type:mcpclients:-codex:project-claude-code
LLM Configuration
ktx supports multiple LLM providers:
# During setup, choose provider
ktx setup
# Supported providers:# - anthropic (requires ANTHROPIC_API_KEY)# - vertex-ai (requires Google Cloud credentials)# - ai-gateway (custom endpoint)# - claude-agent-sdk (local Claude Code session)
# Ingest all configured sources
ktx ingest
# Ingest specific connection
ktx ingest --connection warehouse
# Ingest specific context source
ktx ingest --source dbt_main
# Force re-ingestion (skip cache)
ktx ingest --force
Searching Context
# Search semantic layer (metrics, dimensions, entities)
ktx sl "revenue"
ktx sl "monthly active users"# Search wiki pages
ktx wiki "refund policy"
ktx wiki "data retention"# Combined search (semantic layer + wiki)
ktx search "customer churn"
MCP Server
# Start MCP server for agent clients
ktx mcp start
# Start with specific project directory
ktx mcp start --project-dir /path/to/project
# Check MCP server status
ktx mcp status
# Stop MCP server
ktx mcp stop
Semantic Layer Management
# List semantic sources
ktx sl list
# Validate semantic layer definitions
ktx sl validate
# Show semantic source details
ktx sl show users
ktx sl show revenue_metrics
Project Management
# Initialize new project (alternative to setup)
ktx init
# Update project configuration
ktx config set llm.provider anthropic
ktx config set llm.model claude-sonnet-4-6
# Show current configuration
ktx config show
# Clean cached context
ktx clean --cache
# Clean everything (reset project)
ktx clean --all
Real Usage Examples
Example 1: Set Up ktx for PostgreSQL Warehouse
# Install globally
npm install -g @kaelio/ktx
# Navigate to projectcd ~/my-analytics-project
# Set LLM API keyexport ANTHROPIC_API_KEY=sk-ant-...
# Run setup (interactive)
ktx setup
# Choose: anthropic, claude-sonnet-4-6# Choose: openai, text-embedding-3-small# Add database: postgres# Host: localhost# Port: 5432# Database: analytics# User: readonly_user# Password: [enter securely]# Verify setup
ktx status
# Navigate to projectcd ~/my-analytics-project
# Run setup with MCP integration
ktx setup
# During setup, select: "Install MCP integration? yes"# Select agent: "Claude Code (codex)"# Start MCP server
ktx mcp start --project-dir ~/my-analytics-project
# Keep terminal open, open Claude Code in another window# Claude Code will auto-discover the MCP server
Example 5: Create Semantic Layer Definition
Create semantic-layer/warehouse/customers.yaml:
kind:SemanticSourcename:customerstype:entitydescription:Customerdimensionwithlifetimemetricscolumns:-name:customer_idtype:dimensiondata_type:integerprimary_key:true-name:emailtype:dimensiondata_type:string-name:created_attype:dimensiondata_type:timestamp-name:lifetime_valuetype:metricdata_type:numericsql:SUM(order_total)aggregation:sum-name:total_orderstype:metricdata_type:integersql:COUNT(DISTINCTorder_id)aggregation:countsql:|
SELECT
c.id as customer_id,
c.email,
c.created_at,
COALESCE(SUM(o.total), 0) as lifetime_value,
COUNT(o.id) as total_orders
FROM customers c
LEFT JOIN orders o ON c.id = o.customer_id
GROUP BY c.id, c.email, c.created_at
joins:-to:orderstype:one_to_manyon:customers.customer_id=orders.customer_id
Validate and ingest:
ktx sl validate
ktx ingest --force
ktx sl show customers
Example 6: Add Wiki Context
Create wiki/global/data-definitions.md:
# Data Definitions## Revenue Recognition
Revenue is recognized at the point of sale, not when payment is received.
**Key Metrics:**-`gross_revenue`: Total sales before discounts
-`net_revenue`: Sales minus refunds and discounts
-`arr`: Annual Recurring Revenue (subscription only)
## Customer Classification-**Active**: Made a purchase in last 90 days
-**Churned**: No purchase in 90+ days
-**New**: First purchase within last 30 days
## Refund Policy
Refunds are processed within 7 days and deducted from revenue in the same period.
npm install -g @kaelio/ktx
# or
npx @kaelio/ktx setup
Issue: MCP server not connecting
Solution: Check server is running and project directory is correct:
ktx mcp status
# If not running:
ktx mcp start --project-dir /absolute/path/to/project
# Verify in Claude Code settings:# MCP servers should show ktx with status "Connected"
Issue: Database connection fails
Solution: Verify credentials and network access:
# Test connection manually
psql -h localhost -p 5432 -U readonly_user -d analytics
# Check ktx configuration
ktx config show
# Re-run setup to update credentials
ktx setup
Issue: Ingestion fails with "LLM error"
Solution: Verify API key and quota:
# Check API key is setecho$ANTHROPIC_API_KEY# Verify in ktx config
ktx config show
# Try with different model
ktx config set llm.model claude-sonnet-3-5-20240620
ktx ingest
Issue: Semantic layer validation errors
Solution: Check YAML syntax and required fields:
# Run validation with verbose output
ktx sl validate --verbose
# Common issues:# - Missing 'kind' field# - Invalid column types (must be: dimension, metric, or attribute)# - Invalid join syntax# - Missing SQL or columns definition
Solution: Use incremental ingestion and tune sampling:
# Skip force refresh (use cache)
ktx ingest
# Reduce table sampling (in ktx.yaml)
databases:
warehouse:
sampling:
max_rows: 1000 # default is 10000
Issue: Agent can't find ktx MCP tools
Solution: Ensure MCP server is running and configured:
# Start MCP server in background
ktx mcp start --project-dir $(pwd) &
# In Claude Code, verify MCP connection:# Settings > MCP Servers > ktx should show "Connected"# If using Cursor/other, check their MCP configuration
# Explicit project directory
ktx status --project-dir /path/to/project
# Using environment variableexport KTX_PROJECT_DIR=/path/to/project
ktx status
# Auto-discover from current directorycd /path/to/project
ktx status
