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://platform.timeback.com/mcps/analytics"
    }
  }
}

Remote (HTTP)

Add the following to your VS Code settings.json:

{
  "mcp.servers": {
    "timeback-analytics-mcp-server": {
      "type": "http",
      "url": "https://platform.timeback.com/mcps/analytics"
    }
  }
}

Remote (HTTP)

Run the following command:

claude mcp add --transport http timeback-analytics-mcp-server https://platform.timeback.com/mcps/analytics

In ChatGPT, go to Settings → Connectors and add the MCP server URL:

https://platform.timeback.com/mcps/analytics

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) - Every available relation (table/view) with its description AND its full column list (each column's name, data type, and description) Because this already includes every column name, type, and description, you have everything needed to write a correct query directly — you do NOT need a follow-up metadata call. Always use the exact column names returned here; do not guess or invent column names. Flow: Call this first → then timeback_execute_query (use timeback_get_relation_metadata only if you need to re-confirm a single relation).
`timeback_get_relation_metadata`	Get detailed column metadata for specific database relations (tables/views). NOTE: This is usually unnecessary — timeback_get_schema_overview already returns every column's name, type, and description for all relations. Use this only to re-confirm a single relation's columns in isolation. 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 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 — it already returns every relation's columns (name, type, description), so use those exact column names here 2. Then call this tool to execute your query (use timeback_get_relation_metadata only to re-confirm a single relation if needed) 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 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)

Analytical Entities