Choosing an Integration Surface
TimeBack exposes three integration surfaces. They are not alternatives for the same job: REST is the contract you build a product on, MCP is how an AI assistant explores, and webhooks are how TimeBack tells you something happened. Most integrations use more than one.
Which Surface for Which Job
| If you want to | Use | Why |
|---|---|---|
| Read one student's insights in your product | REST (GET /insights/1.0/users/{userId}) |
Stable contract, pagination, filtering, your own credentials |
| Discover which insight types exist | REST (GET /insights/1.0/types) |
The catalog is not reachable from any MCP server today |
| Read or set per-org insight enforcement policy | Platform MCP (manage_org_insight_policy) |
Levers, rollout, and audit for org overlay on the catalog |
| Explore data ad hoc, or let an AI assistant answer questions | Analytics MCP | SQL over curated views; 500-row and 110-second limits |
| Let an AI assistant look up a student's sessions conversationally | Platform MCP | Scoped to session insights for the signed-in user |
| Register an app, manage credentials or webhooks | Developer-platform MCP, or the REST applications API | Purpose-built tools; two of its tools are not yet available |
| Be told when a session ends or an insight is raised | Webhooks | Push, no polling |
The Three MCP Servers
| Server | URL | Auth | For |
|---|---|---|---|
| Platform MCP | https://platform.timeback.com/mcp |
OAuth 2.0 with dynamic client registration, Google sign-in | Assistants working across platform data |
| Analytics MCP | https://platform.timeback.com/mcps/analytics |
OAuth, org-scoped | Analytical questions over curated views |
| Developer-platform MCP | https://platform.timeback.com/mcps/developer-platform |
Same OAuth as the platform MCP | Developers integrating an app |
When REST Is Still the Right Answer
MCP exists alongside REST, not instead of it:
- MCP tool surfaces change as we improve them and are not a versioned contract.
- The platform MCP's data reads via
query_dataare GET-only and scoped to the signed-in user for session insights (/insights/1.0/sessionsand/insights/1.0/sessions/{sessionId}). Org insight-policy list, audit, levers, and rollout go throughmanage_org_insight_policyinstead. The type catalog and other/insights/paths remain unavailable through either MCP tool. - The analytics MCP caps results at 500 rows and 110 seconds, and answers from curated analytics views rather than the live Insights API.
- Anything you ship to your own users belongs on REST.
See also Level 4: Insights API, Analytics, and Webhooks.
