Assistant & MCP — initiative plan ​

Audience: Leadership, product, engineering
Status: Planned — not started
Last updated: June 26, 2026
Engineering detail: design-log/2026-06-26-assistant-mcp-learning-plan.md in the monorepo

Learning (Disprz-inspired LMS) is a separate plan: Ascendly Learning plan

Executive summary ​

Two related initiatives share one capabilities layer:

InitiativeWhat it isStatus today
AI assistant (in-app bot)Chat that answers questions about Ascendly policies and your BSC, scorecard, and learning progressNot started
MCP serverLets external AI tools (e.g. Cursor) query Ascendly safely via structured toolsNot started

Ascendly Learning (modules, uploads, quizzes, assignments) → separate plan. Can ship before this initiative.

Recommended order (this track): Capabilities layer → doc search + MCP → in-app bot → index published learning content (after Learning L0+).

Why one foundation? ​

BSC and scorecard already enforce who can see what (access levels 1–5, org scope). An AI bot or MCP server must use the same rules — not raw database access.

                    ┌──────────────────┐
                    │  Capabilities    │
                    │  (scoped queries)│
                    └────────┬─────────┘
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
   MCP server         In-app chat          Future bots
   (Cursor)           (web + desktop)

Phases at a glance ​

Revisit this table to track progress. Update Status as work ships (also update the progress report when a phase completes).

PhaseFocusEst.StatusKey outcome
0Assistant capabilities2–3 wkNot startedScoped, audited read APIs for BSC, scorecard, org, learning status
1Doc RAG + MCP v1~2 wkNot startedCursor can search guides + run read-only data tools
2(Learning — separate plan)——See Learning plan
3In-app bot v13–4 wkNot startedWeb chat: docs + own/team BSC (by role)
4Deep retrievalongoingNot startedIndex published modules; optional write tools

Phase 0 — Capabilities foundation ​

Start here. Everything else plugs into this.

Build:

  • Internal assistant domain in the API
  • Read-only operations: my BSC, team BSC (managers), bonus qualification breakdown, scorecard entry search, org context, learning enrollments
  • Audit log for every assistant query
  • GET /v1/assistant/capabilities — what the signed-in user is allowed to ask

Rules:

  • Never expose raw database queries to the AI
  • Every call runs as the authenticated user
  • Same Mongo/BigQuery split as dashboards (self = live Mongo; team aggregates = BQ when enabled)

Phase 1 — Doc RAG + MCP server ​

Doc RAG: Index the existing Guide content so the assistant can answer “How is bonus qualification calculated?” without touching employee data.

MCP server: A small process in the monorepo (mcp/) that exposes tools to Cursor and similar clients by calling the Ascendly API.

v1 tools (read-only):

ToolExample use
Search product docs“Explain ATW scoring”
BSC summary“What’s my team’s BSC for June?”
Employee / org context“Who is this employee’s manager?”
Scorecard entry list“Show SBS entries for employee X this month”
BSC metrics config“What KPIs are in Compliance for cycle 2026?”
Learning enrollments“What courses is this user enrolled in?”

Phase 2 — Learning (separate plan) ​

Ascendly Learning is a standalone Disprz-inspired LMS — modules from documents, quizzes, assignments, points.

→ Ascendly Learning plan (phases L0–L5)

If training is the priority, start Learning L0 instead of Assistant Phase 0.

Phase 3 — In-app AI bot ​

UI: Floating chat in web (desktop reuses shared components).

Backend: POST /v1/assistant/chat with server-side LLM; tools call Phase 0 capabilities + Phase 1 doc search.

By role:

RoleCan ask about
EmployeeOwn BSC, own scorecard entries, docs, own learning
ManagerTeam scope (same as dashboard), docs
AdminBroader lookups — all audited

Example questions (v1):

  • How is bonus qualification calculated?
  • What’s my BSC this month?
  • Why did my Compliance KPI drop?
  • What learning modules am I enrolled in?

Phase 4 — Polish and depth ​

  • Bot answers questions about lesson content (after Learning L0+)
  • Manager learning dashboard rollup (Learning L4)
  • Optional MCP write tools (assign course, etc.) — strict audit
  • Proactive nudges via existing notifications (“evaluations missing this month”)

Knowledge strategy ​

SourceHow the assistant uses itRisk
Product guidesVector search (RAG)Low
BSC configurationStructured toolLow
Employee / scorecard dataScoped tool calls onlyMedium — audit critical
Lesson contentRAG when publishedLow

Do not embed all employee records in a vector database.

Suggested timeline (~90 days, Assistant track only) ​

WeeksFocusMilestone
1–2Phase 0Capabilities + audit + scope tests
2–3Phase 1Doc RAG + MCP in Cursor
4–6Phase 3In-app chat
7+Phase 4Index published learning content

Learning timeline (~20 weeks): see Learning plan.

If the priority is…Start with
Training, compliance, onboarding inside AscendlyLearning plan L0
Admin/dev Q&A about BSC rulesAssistant Phase 0–1 (this doc)

Both tracks can run in parallel with two owners. Learning does not require Assistant Phase 0.

What we are not doing first ​

  • In-app bot before the capabilities layer exists
  • MCP with direct database access (bypasses permissions)
  • Vector-indexing all HR/scorecard data
  • Full learning CMS — see Learning plan instead
  • Write-capable bot on day one

Decisions still open ​

TopicOptionsDecide by
MCP authPersonal access token vs OAuth device flowPhase 1
LLM providerOpenAI / Anthropic / Google — server-side onlyPhase 3
Vector storageMongoDB embeddings vs Atlas Vector SearchPhase 1
Chat retentionTTL on conversation threads (e.g. 90 days)Phase 3

When a phase ships ​

  1. Update Status in this doc and design-log/2026-06-26-assistant-mcp-learning-plan.md.
  2. Add shipped items to the Progress report.
  3. Add user-facing guides under Guide when behavior is stable.
  4. Extend API reference with /v1/assistant routes.