TimeBack Analytics MCP Server

The MCP server for TimeBack Analytics. Exposes tools to query student learning data, analyze session patterns, and generate reports.

Version: 1.0.0

Connect to TimeBack Analytics MCP Server

Remote (HTTP)

Add the following to your ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "timeback-analytics-mcp-server": {
      "type": "http",
      "url": "https://analytics.platform.timeback.com/mcp",
      "headers": {
        "X-Api-Key": "<API_KEY>"
      }
    }
  }
}

Remote (HTTP)

Add the following to your VS Code settings.json:

{
  "mcp.servers": {
    "timeback-analytics-mcp-server": {
      "type": "http",
      "url": "https://analytics.platform.timeback.com/mcp",
      "headers": {
        "X-Api-Key": "<API_KEY>"
      }
    }
  }
}

Remote (HTTP)

Run the following command:

claude mcp add --transport http timeback-analytics-mcp-server https://analytics.platform.timeback.com/mcp --header "X-Api-Key: <API_KEY>"

Tools

The server exposes the following MCP tools:

Tool	Description
`timeback_get_schema_overview`	Get an overview of the TimeBack analytics database schema. IMPORTANT: This should ALWAYS be your first call when working with the analytics database. TIMING: 1-2 seconds typical. Returns: - Current database version (for SQL syntax compatibility) - List of all available relations (tables/views) with their descriptions Use this to understand what data is available before diving into specific relations. Flow: Call this first → then timeback_get_relation_metadata → then timeback_execute_query
`timeback_get_relation_metadata`	Get detailed column metadata for specific database relations (tables/views). IMPORTANT: Call timeback_get_schema_overview first to see what relations are available. TIMING: 1-3 seconds depending on number of relations (0.5s per relation). This returns detailed information about columns including: - Column names - Data types - Comments/descriptions Use this after getting the schema overview to understand the structure of specific tables/views you want to query. NOTE: Do NOT include schema prefixes - just use table names (e.g., "students", not "analytics.students").
`timeback_execute_query`	Execute a SELECT query against the TimeBack analytics database. IMPORTANT: Always follow this workflow: 1. Call timeback_get_schema_overview to understand available data 2. Call timeback_get_relation_metadata to understand column details 3. Then call this tool to execute your query TIMING: 2-10 seconds typical. Complex queries with many JOINs/aggregations: 10-25 seconds. Maximize SQL usage: - Use the FULL power of the SQL dialect (CTEs, window functions, subqueries, aggregations, joins, etc.) - Avoid pulling large datasets into memory to do aggregation outside the database. - Complex analytical queries are encouraged - The database version from step 1 tells you what SQL syntax is available Limits: - Only SELECT queries are allowed (INSERT, UPDATE, DELETE, DROP, etc. are forbidden) - Maximum 500 rows returned per query (enforced) - Maximum 25 seconds execution time (enforced at database level) - Queries are automatically validated using PostgreSQL EXPLAIN before execution to prevent timeouts - If result set exceeds limit, 'hasMore' flag will be true NOTE: Do NOT include schema prefixes in queries - the schema is set automatically. Just reference tables directly (e.g., "SELECT * FROM students", not "SELECT * FROM analytics.students"). Best practices: - Add WHERE clauses to filter large datasets - Use aggregations (GROUP BY, COUNT, SUM, etc.) for summary views
`timeback_estimate_query`	Estimate query execution time using PostgreSQL's query planner (EXPLAIN) WITHOUT executing the query. TIMING: 1-2 seconds (planner analysis only, no data scanned). This tool uses the database's actual cost-based optimizer to provide accurate estimates based on: - Table statistics (actual row counts) - Index availability and selectivity - Join strategies and costs - Aggregation complexity - Data distribution statistics Use this to: - Plan complex queries before executing them - Decide if a query needs optimization - Set user expectations for long-running operations - Compare different query approaches Returns: - Estimated duration in seconds (based on database planner cost) - Estimated rows returned - Complexity level (low/medium/high) - Query plan operations (Seq Scan, Index Scan, Hash Join, etc.) - Specific optimization suggestions IMPORTANT: This uses real database statistics, making it much more accurate than heuristic estimates. Example workflow: 1. timeback_estimate_query → Get real database estimate 2. If estimate > 15s, refine query based on suggestions 3. timeback_estimate_query → Verify improvement 4. timeback_execute_query → Execute optimized query Best practices: - Always estimate complex queries before executing - Use suggestions to add indexes or filters - Queries estimated >20s may timeout (25s limit)
`timeback_get_sample_data`	Get sample rows from a specific table or view to understand its data format and content. TIMING: 1-3 seconds typical. This is useful for: - Seeing what actual data looks like before writing queries - Understanding data formats, value ranges, and patterns - Quick exploration of unfamiliar tables The sample is taken from the first N rows (not random sampling). Flow: timeback_get_schema_overview → timeback_get_relation_metadata → timeback_get_sample_data → timeback_execute_query
`timeback_get_table_stats`	Get statistical information about a table or view including row counts and column-level statistics. TIMING: 10-20 seconds (performs full table scan). Returns: - Total row count - For each column: null count and distinct value count This is useful for: - Understanding data completeness (null counts) - Assessing cardinality (distinct counts) - Planning queries and filters Note: This can be slow on large tables as it scans all rows. Flow: timeback_get_schema_overview → timeback_get_table_stats (optional) → timeback_execute_query
`timeback_get_view_definition`	Get the SQL definition (CREATE VIEW statement) for a specific view. TIMING: 1-2 seconds typical. This is useful for: - Understanding how a view is constructed - Seeing what transformations are applied to the underlying data - Learning the data pipeline and relationships Note: Only works for views, not tables. Flow: timeback_get_schema_overview → timeback_get_view_definition (optional)