Insightful
Insightful is org structure first, then projects and tasks, then tracking settings — create a project before tasks, resolve organization context from tags or teams before writes, and treat shared settings as reusable tracking profiles.
The MCP surface targets Insightful v1 REST at app.insightful.io/api/v1 (kebab-case paths, Bearer token, next pagination).
Hierarchy
- Organization — implied by the API token; organizationId appears on tags, settings, and writable rows.
- Team — groups employees and projects; carries productivity ignore flags.
- Employee — directory members with email and timestamps.
- Project — time-allocation container with statuses, priorities, payroll, member lists.
- Task — work item under exactly one projectId; requires status, priority, and employees array on create (empty array allowed).
- Shared settings — reusable tracking profiles (idle, screenshots, breaks).
- Scheduled shift settings — org clock rules (list-only API).
- App category / app tag — read-only application taxonomy and colored labels.
- Directory — HR/directory connector metadata.
Operational order
- Resolve org context from teams or app tags when a write needs organizationId.
- Create or select a project before creating tasks (projectId is mandatory).
- Use shared settings profiles when adjusting tracking behavior — copy an existing settings object shape before authoring a new profile.
- Prefer get_* with id for single rows; omit id to list and follow next cursors.
- Do not send a limit query param — Insightful rejects it on several collections.
Write semantics
- Project create — POST JSON with name, organizationId, employees[], teams[] (arrays may be empty).
- Task create — POST JSON with name, projectId, organizationId, status, priority, employees[].
- Updates — PUT /{collection}/{id} with partial JSON bodies.
- Deletes — DELETE /{collection}/{id}; destructive and idempotent.
Telemetry collections (fragments, shifts, screenshots) and v2 export paths are not on this v1 base URL — do not assume they exist here.
