MCP Server

The MCP Server exposes Epistom's semantic intelligence to AI agents via the Model Context Protocol. It provides 8 tools that agents can use to understand data, generate queries, and provide feedback.

How It Works

The server runs in two modes:

stdio — For direct integration with Claude Desktop, Cursor, and other MCP-compatible clients
SSE — HTTP-based Server-Sent Events for web and remote connectivity (default port 3000)

# stdio mode
python -m epistom.mcp_server.server
 
# SSE mode (default)
python -m epistom.mcp_server.server --sse --port 3000

The server initializes the SemanticEngine on startup and routes tool calls through it. Downstream MCP servers (Salesforce, Slack, etc.) can be connected via the Aegis connection manager and their tools are merged into the tool list with namespace prefixes.

The 8 MCP Tools

ask_question

Ask a business question in natural language. Routes through the full semantic pipeline.

Parameters:

question (string, required) — Natural language business question
thread_id (string, optional) — Thread ID for multi-turn context

Returns: Validated SQL, query results, confidence score, explanation, and query ID for feedback.

get_definition

Look up the formal definition of a business concept.

Parameters:

concept (string, required) — Concept name (e.g., "MRR", "customer churn")

Returns: Definition, domain, related concepts, and SHACL constraints.

validate_sql

Validate a SQL statement against the semantic model before execution.

Parameters:

sql (string, required) — SQL statement to validate
dialect (string, optional) — SQL dialect: postgresql (default), snowflake, bigquery, mysql

Returns: PASS/FAIL with structured explanation of validation errors.

list_concepts

List available business concepts in the workspace ontology.

Parameters:

domain (string, optional) — Filter by domain (e.g., "Revenue", "Customer")
search (string, optional) — Search keyword

Returns: List of concepts with names, domains, and descriptions.

get_schema

Return relevant table and column schema for a given question or topic.

Parameters:

question (string, required) — Question or topic to find relevant schema for
max_tables (integer, optional) — Maximum tables to return (default 10)

Returns: Table names, column names, types, and relationship annotations.

get_metrics

Retrieve formal metric definitions with SQL formulas and aggregation rules.

Parameters:

metric_names (string array, required) — List of metric names (e.g., ["MRR", "Churn Rate", "LTV"])

Returns: Verified computation patterns, SQL formulas, and aggregation constraints for each KPI.

suggest_queries

Return verified query suggestions (curated, production-validated SQL patterns).

Parameters:

domain (string, optional) — Domain to get suggestions for
topic (string, optional) — Specific topic or keyword

Returns: List of verified queries with descriptions, SQL, and applicable contexts.

report_feedback

Report whether a query result was correct or incorrect. Feeds the self-improving accuracy loop.

Parameters:

query_id (string, required) — ID from a previous ask_question response
rating (string, required) — One of: "correct", "wrong", "partial"
comment (string, optional) — Explanation of what was wrong

Returns: Confirmation of feedback submission.

Architecture

The MCP server consists of:

server.py — Main server with stdio and SSE transport, tool list assembly, and call routing
tools/ — 8 tool modules, each with a TOOL_DEFINITION dict and an async handle() function
workspace_resolver.py — Resolves workspace context from MCP session metadata

Tool calls are dispatched through a handler map (TOOL_HANDLERS) that routes by tool name. Error responses are sanitized via sanitize_error_internal() to prevent leaking internal details to agents.

Configuration

The MCP server inherits all Epistom configuration. Additional MCP-specific settings:

# SSE transport settings
MCP_SSE_HOST=0.0.0.0
MCP_SSE_PORT=3000

On this page