MCP Tools

Epistom exposes 8 MCP (Model Context Protocol) tools that AI agents use to understand data, generate queries, and provide feedback. These tools are available via both stdio and SSE transports.

Tool Reference

ask_question

Ask a business question and get a validated SQL answer.

{
  "name": "ask_question",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": {"type": "string", "description": "Natural language business question"},
      "thread_id": {"type": "string", "description": "Thread ID for multi-turn context (optional)"}
    },
    "required": ["question"]
  }
}

Response: { "answer": "...", "sql": "SELECT ...", "confidence": 0.92, "query_id": "q-123", "sources": [...] }

get_definition

Look up the formal definition of a business concept.

{
  "name": "get_definition",
  "inputSchema": {
    "type": "object",
    "properties": {
      "concept": {"type": "string", "description": "Concept name (e.g., 'MRR', 'customer churn')"}
    },
    "required": ["concept"]
  }
}

Response: { "definition": "...", "domain": "Revenue", "related_concepts": [...], "constraints": [...] }

validate_sql

Validate SQL against the semantic model before execution.

{
  "name": "validate_sql",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sql": {"type": "string", "description": "SQL statement to validate"},
      "dialect": {"type": "string", "description": "postgresql, snowflake, bigquery, mysql", "default": "postgresql"}
    },
    "required": ["sql"]
  }
}

Response: { "valid": true, "errors": [], "warnings": ["Consider adding a date filter"] }

list_concepts

List business concepts in the workspace.

{
  "name": "list_concepts",
  "inputSchema": {
    "type": "object",
    "properties": {
      "domain": {"type": "string", "description": "Filter by domain"},
      "search": {"type": "string", "description": "Search keyword"}
    }
  }
}

Response: { "concepts": [{"name": "MRR", "domain": "Revenue", "description": "..."}, ...] }

get_schema

Get relevant table/column schema for a question.

{
  "name": "get_schema",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": {"type": "string", "description": "Question or topic"},
      "max_tables": {"type": "integer", "description": "Maximum tables (default 10)"}
    },
    "required": ["question"]
  }
}

Response: { "tables": [{"name": "invoices", "columns": [{"name": "amount", "type": "numeric"}, ...]}] }

get_metrics

Retrieve formal metric definitions with SQL formulas.

{
  "name": "get_metrics",
  "inputSchema": {
    "type": "object",
    "properties": {
      "metric_names": {"type": "array", "items": {"type": "string"}, "description": "Metric names"}
    },
    "required": ["metric_names"]
  }
}

Response: { "metrics": [{"name": "MRR", "formula": "SUM(amount) WHERE status='active'", ...}] }

suggest_queries

Get verified query suggestions for a domain.

{
  "name": "suggest_queries",
  "inputSchema": {
    "type": "object",
    "properties": {
      "domain": {"type": "string", "description": "Domain (e.g., 'Revenue')"},
      "topic": {"type": "string", "description": "Specific topic"}
    }
  }
}

Response: { "suggestions": [{"question": "Monthly revenue trend", "sql": "SELECT ...", ...}] }

report_feedback

Report whether a query result was correct.

{
  "name": "report_feedback",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query_id": {"type": "string", "description": "ID from ask_question response"},
      "rating": {"type": "string", "enum": ["correct", "wrong", "partial"]},
      "comment": {"type": "string", "description": "Explanation of what was wrong"}
    },
    "required": ["query_id", "rating"]
  }
}

Response: { "submitted": true, "feedback_id": "f-456" }

Transport Modes

stdio

For Claude Desktop, Cursor, and MCP-compatible clients:

python -m epistom.mcp_server.server

SSE (Server-Sent Events)

For web and remote connectivity:

python -m epistom.mcp_server.server --sse --port 3000

The SSE endpoint is also available via the REST API at /api/v1/mcp/sse.

On this page