io.github.setluca/luca-mcp

The coach's cross-coach benchmark opt-in state (whether this workspace contributes to and sees anonymized niche cohort percentiles). Read-only; the opt-in is changed from the app, not through this key surface. Luca operation: GET /api/analytics/benchmark-consent Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

This coach's own cross-coach benchmark percentiles (e.g. 'top 15% for response speed among fitness coaches'), never another coach's data. `comingSoon: true` with an empty metrics list is the honest, expected state until the cross-coach benchmark pipeline populates this coach's row — never a fabricated comparison. Luca operation: GET /api/analytics/benchmarks Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Post-call intelligence for a period: show rate, close rate, average rating and rating distribution, call-to-close lag, repeat-call cohort, day-of-week and call-sequence show rates, and surprise patterns, derived from post-call events and coach-recorded outcomes. Luca operation: GET /api/analytics/call-intelligence Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Most recent completed calls with a generated summary, newest first: the coach-facing summary, attendance outcome, rating, and lead name. Luca operation: GET /api/analytics/call-intelligence/calls Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Per-content rollup (leads touched, qualified, booked, revenue) of attributed touches for a period. Content is attributed automatically from an Instagram comment or Story reply that carries a real media id, or tagged manually; an honest empty list means no content is attributed yet, not zero performance. Luca operation: GET /api/analytics/content-attribution Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Per-post rollup (reach, engagement rate, likes/comments/saves/shares, attributed leads/bookings/revenue) for each Instagram post, reel, story, or carousel over a period. Insight fields stay null until the coach's account grants Instagram insights access — read that as not connected yet, not zero engagement. Luca operation: GET /api/analytics/content-performance Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Aggregate CRM-sync health for the coach's post-call summaries: counts of synced, pending, local-only, failed, and permanently-failed pushes. All zeros is the honest, expected state for a coach with no synced summaries yet — never a fabricated status. Luca operation: GET /api/analytics/crm-sync-health Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Answer a specific business question by composing all seven analytics reads in one call: pipeline funnel, revenue and ROI, response-speed impact, a point-in-time revenue forecast, call intelligence (show/close rates), ghosted-lead recovery, and coach trust/auto-send status. Use it when the coach asks a specific question that needs several of these numbers side by side, rather than the fixed weekly report. Example: call with {question: "why did close rate drop this month?", period: "this_month"}.

Point-in-time pipeline revenue forecast with on-track, optimistic, and conservative scenarios based on pipeline stage probabilities and historical conversion rates. Luca operation: GET /api/analytics/forecast Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Pipeline funnel stage counts with period and channel filters. Returns counts and conversion rates for each funnel stage plus period-over-period deltas. Luca operation: GET /api/analytics/funnel Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Summarize leads who stopped replying during a period, including their count, follow-up recovery rate, estimated lost revenue, and common reasons conversations stalled. This is an aggregate report, not a list of individual leads. Luca operation: GET /api/analytics/ghosted-leads Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

The coach's proactive-insights feed (metric drops/spikes, opportunities, risks, milestones) surfaced by the daily insight-detection cron, newest first. Optionally filter to one status via the status query param (e.g. unread). An empty items list is the honest, expected state for a coach nothing has been flagged for yet — never a fabricated alert. Luca operation: GET /api/insights Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Predictive booking-likelihood score (0-100) for one lead from the coach's trained bucket-rate model, with a confidence tier and the top contributing features. Honest about insufficient data: an under-trained model returns a null score and low confidence instead of a fabricated number. Luca operation: GET /api/analytics/lead-score/{leadId} Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Read-only rollup of the agent-improvement signals mined from post-call feedback for a period: total/applied/pending signal counts, a per-type breakdown (qualification, objection handling, lead quality, general), and recent example notes. An empty rollup is the honest, expected state until the coach submits call feedback — never fabricated learning. Luca operation: GET /api/analytics/learning-insights Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Category breakdown of automatic 'why you lost' analyses for a period: count and estimated lost revenue per category (price objection, ghosted after a call-to-action, competitor, slow reply, bad fit, other), derived from a per-lead loss analysis generated when a lead goes silent or lost. Luca operation: GET /api/analytics/loss-reasons Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Return the current week's business report (called Magic Monday in Luca): pipeline funnel, revenue and ROI, response-speed impact, a point-in-time revenue forecast, and call intelligence (show/close rates). Composes five analytics reads into a single call. Example: call with {} for the weekly report.

Per-conversation drilldown for one objection bucket: one row per matching conversation with the lead's display name, the verbatim objection quote, whether the draft was sent without an edit, and the lead's most recent call outcome. Bounded by a limit with a hasMore truncation flag; an empty list is the honest, expected state for a bucket with no conversations in the window. Luca operation: GET /api/analytics/objections/{type} Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Objection-bucket rollup over the review queue's qualifier signals for a period (price, timing, trust, fit, authority, smokescreen): per-bucket occurrence count, distinct leads, handled rate, wins, and up to three of the most frequent verbatim lead quotes. Filter by channel. An empty bucket list is the honest, expected state until objections are raised — never fabricated. Luca operation: GET /api/analytics/objections Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

The coach's active prescriptive recommendations for a week (what to change and why), generated weekly from detected insights and deduped by title. An empty list is the honest, expected state when nothing is recommended for the window — never a fabricated action. Luca operation: GET /api/analytics/recommendations Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Revenue attribution and plan ROI for a period. Returns total revenue, ROI, and a per-channel revenue breakdown. Luca operation: GET /api/analytics/revenue Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Roll up performance across the coach's campaigns (per-campaign analytics for up to 5 recent campaigns) and recent broadcasts. When one half fails to load, the other still comes back and failedSections names the one that is missing. Example: call with {} for the default rollup, or { campaignLimit: 3 }.

Fast-vs-slow first-reply booking-rate impact for a period. Returns fast- and slow-reply conversion rates, a lost-opportunity estimate, and the peak performance reply window. Luca operation: GET /api/analytics/speed-impact Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Weekly rollup by normalized content topic (post count, average engagement rate, attributed leads/bookings/revenue per theme). Defaults to the most recently computed week when weekStart is omitted; an empty items list is the honest, expected state until content topics are extracted, not zero performance. Luca operation: GET /api/analytics/topic-performance Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

The coach's weekly metrics as a trend series (leads, qualified, booked, revenue, and rates week over week) for charting direction of travel. An empty series is the honest, expected state until enough weeks of history accrue — never fabricated points. Luca operation: GET /api/analytics/trends Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Draft approval, edit, and rejection rates plus the auto-send gate flag for a period. Luca operation: GET /api/analytics/trust-score Required scopes: analytics:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Approve a pending review-queue draft and dispatch it through the lead's channel. THIS SENDS A REAL MESSAGE TO A REAL PERSON — only call it after a human has reviewed and intends to send. Pass confirm: true to proceed. Optional finalBody replaces the draft text before sending. Example: { reviewQueueId, confirm: true }.

Book a call on the coach's calendar provider and have the provider invite the lead's email; the lead also gets Luca's booking confirmation. Works for call types on Calendly, Cal.com, or Google Calendar. Reads the open slots of the call type first and books the one that starts at slotAt. When that slot is taken it books nothing and returns the open slots instead, so pick one of them and call again. The answer is usually pending while the provider confirms; check it with luca_bookings_provider_requests_get. The booking puts an event on the coach's calendar and invites the lead, so pass confirm: true only after the coach approves this exact slot. If a retry answers slot_not_available, the first attempt may have taken the slot, so check luca_bookings_list before booking again. To record a call that is already on a calendar, use luca_bookings_create instead. Example: call with { leadId, bookingTypeId, slotAt: "2026-07-14T15:00:00Z", inviteeEmail: "sam@example.com", confirm: true } after the lead agreed to a time.

List open slots the coach can actually be booked into. Check this before booking. Luca operation: GET /api/bookings/availability Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Read the pre-call brief: who the lead is, what they want, and the objections to expect. Luca operation: GET /api/bookings/{id}/brief Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

List the calendars Luca reads for conflicts, and which one it writes new events to. Luca operation: GET /api/bookings/calendars Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Stop using a calendar for conflict checks or as the booking destination. The calendar itself is left alone in Google; only Luca's selection changes. Luca operation: DELETE /api/bookings/calendars Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Add or update a calendar selection, either for conflict checks or as the destination new bookings are written to. The destination has to be writable: a read-only calendar returns 400, and a Google connection needing attention returns 409. Luca operation: PUT /api/bookings/calendars Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Cancel a booking. A Google Calendar or Cal.com booking is cancelled on that calendar too, and the calendar can email the lead about it. Luca operation: DELETE /api/bookings/{id} Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: full_content Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Destructive: has a real-world side effect. You must pass confirm: true; the call is rejected without it. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Create a provider-neutral booking record. Body requires leadId and slotAt. Luca operation: POST /api/bookings Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: full_content Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Destructive: has a real-world side effect. You must pass confirm: true; the call is rejected without it. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Read one booking: its slot, status, provider, and lead. Luca operation: GET /api/bookings/{id} Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Mint revocable reschedule and cancel links for one booking, so a lead can move the call without an account. Luca operation: POST /api/bookings/{id}/guest-links Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Kill every outstanding guest link on a booking at once. Luca operation: DELETE /api/bookings/{id}/guest-links Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

List bookings where Luca's record and the provider's disagree and a human has to decide. Luca operation: GET /api/bookings/lifecycle-attention Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Settle one booking whose record disagrees with the provider's: retry the sync, dismiss the duplicate, or keep Luca's version. Luca operation: POST /api/bookings/{id}/lifecycle-resolution Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: full_content Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Destructive: has a real-world side effect. You must pass confirm: true; the call is rejected without it. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

List bookings. Query supports limit, cursor, status, and upcoming. Luca operation: GET /api/bookings Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

List open slots for one of Luca's own call types, with calendar conflicts already removed. Luca operation: GET /api/bookings/managed-availability Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

List attended calls with no outcome recorded yet. The work list for closing revenue attribution. Luca operation: GET /api/bookings/needs-outcome Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: full_content Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Read where the sale stands on a booking, plus the version you send back to correct it. Luca operation: GET /api/bookings/{id}/outcome Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Read every outcome ever recorded on a booking, in order. Corrections append rather than overwrite. Luca operation: GET /api/bookings/{id}/outcome/history Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Add a lost-sale or cancellation reason in the workspace's own wording. A code already in use returns 409. Luca operation: POST /api/bookings/outcome-reasons Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

List the reasons a sale can be lost or a call cancelled. Use one of these codes when recording an outcome. Luca operation: GET /api/bookings/outcome-reasons Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Rename, reorder, or archive an outcome reason. Archiving hides it from the picker and leaves recorded outcomes alone. Luca operation: PATCH /api/bookings/outcome-reasons/{id} Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Record what the call was worth: won, lost with a reason, or still open. Won and lost outcomes can update a connected CRM deal stage, so pass confirm: true for those outcomes. To correct an earlier outcome send the expectedVersion you read; a stale version returns 409 with the current one. Luca operation: POST /api/bookings/{id}/outcome Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Destructive when status is won or lost (can update a connected CRM deal): has a real-world side effect. You must pass confirm: true; the call is rejected without it. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Book one exact slot from luca_bookings_managed_availability on the coach's Calendly, Cal.com, or Google Calendar, which sends the invite to the lead's email; the lead also gets Luca's booking confirmation. Pass the slot's id, startsAt, endsAt, and timezone as returned by a read of exactly that slot's window, since a slot id is tied to the window it was read in. The answer is usually pending while the provider confirms; read it again with luca_bookings_provider_requests_get. A slot taken in the meantime returns 409 slot_unavailable. Luca operation: POST /api/bookings/provider-requests Required scopes: bookings:write Required OAuth scope: luca:queue_ops; data sensitivity: redacted Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one. Destructive: has a real-world side effect. You must pass confirm: true; the call is rejected without it. Use workspaceId or workspaceSlug to override the default workspace configured by environment.

Read where a calendar booking request stands. pending_provider turns into confirmed, handoff_required, or failed once the provider answers, and a confirmed request carries the booking id and meeting link. Luca operation: GET /api/bookings/provider-requests/{id} Required scopes: bookings:read Required OAuth scope: luca:read; data sensitivity: redacted Does not require idempotency. Use workspaceId or workspaceSlug to override the default workspace configured by environment.