Assistant & MCP — initiative plan

Audience: Leadership, product, engineering
Status: Phase 0 started — read-only capabilities API (no chat UI, no LLM)
Engineering detail: design-log/2026-06-26-assistant-mcp-learning-plan.md and design-log/2026-08-15-assistant-explain-capabilities.md in the monorepo

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

Executive summary

Two related initiatives share one capabilities layer:

Initiative	What it is	Status today
Nella (in-app assistant)	Chat that answers questions about Ascendly policies and your BSC, scorecard, and learning progress	Chat panel shipped (scoped tools). MCP not started
MCP server	Lets external AI tools (e.g. Cursor) query Ascendly safely via structured tools	Not 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

Update Status in this table as work ships. When a phase is live, describe it in Guide and What's in Ascendly — do not add dated changelog entries on this site.

Phase	Focus	Est.	Status	Key outcome
0	Assistant capabilities	2–3 wk	In progress	Scoped, audited read APIs. Shipped: catalog, tenure, ranking, month BSC summary, bonus gates
1	Doc RAG + MCP v1	~2 wk	Not started	Cursor can search guides + run read-only data tools
2	(Learning — separate plan)	—	—	See Learning plan
3	In-app bot v1	3–4 wk	In progress	Web/desktop chat: free-form prompts; tools for tenure, ranking, guide search
4	Deep retrieval	ongoing	Not started	Index published modules; optional write tools

Phase 0 — Capabilities foundation

Start here. Everything else plugs into this.

Build:

Internal assistant domain in the API
GET /v1/assistant/capabilities — what the signed-in user may invoke
explain_tenure — runs tenure_from_hire_date (does not re-guess the formula)
rank_employees — top N by Total BSC in the asker’s dashboard pool
Audit log (tbl_assistant_queries) for every assistant query
Still planned: scorecard search, org context, learning enrollments, KPI breakdowns

Rules:

Never expose raw database queries to the AI
Every call runs as the authenticated user (same org scope as dashboards)
Same Mongo/BigQuery split as dashboards (ranking uses the month-snapshot path)
Out-of-scope people: 404, not 403 (do not confirm they exist)
No write routes, no source-code dump, no chat/LLM in this phase
Safety protocol: design-log/2026-08-15-assistant-explain-capabilities.md

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):

Tool	Example 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:

Role	Can ask about
Employee	Own BSC, own scorecard entries, docs, own learning
Manager	Team scope (same as dashboard), docs
Admin	Broader 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

Source	How the assistant uses it	Risk
Product guides	Vector search (RAG)	Low
BSC configuration	Structured tool	Low
Employee / scorecard data	Scoped tool calls only	Medium — audit critical
Lesson content	RAG when published	Low

Do not embed all employee records in a vector database.

Suggested timeline (~90 days, Assistant track only)

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

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

Recommended priority vs Learning

If the priority is…	Start with
Training, compliance, onboarding inside Ascendly	Learning plan L0
Admin/dev Q&A about BSC rules	Assistant 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

Topic	Options	Decide by
MCP auth	Personal access token vs OAuth device flow	Phase 1
LLM provider	OpenAI / Anthropic / Google — server-side only	Phase 3
Vector storage	MongoDB embeddings vs Atlas Vector Search	Phase 1
Chat retention	90-day TTL after last activity; pinned chats skip TTL	Shipped

When a phase ships

Update Status in this doc and design-log/2026-06-26-assistant-mcp-learning-plan.md.
Add user-facing guides under Guide when behavior is stable.
Update What's in Ascendly and remove completed items from the Roadmap if listed.
Extend API reference with /v1/assistant routes.

Ascendly Learning plan — Disprz-inspired LMS (separate track)
Roadmap — dashboard learning overview
What's in Ascendly — current product map
Scorecard guide — doc RAG corpus

Assistant & MCP — initiative plan ​

Executive summary ​

Why one foundation? ​

Phases at a glance ​

Phase 0 — Capabilities foundation ​

Phase 1 — Doc RAG + MCP server ​

Phase 2 — Learning (separate plan) ​

Phase 3 — In-app AI bot ​

Phase 4 — Polish and depth ​

Knowledge strategy ​

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

Recommended priority vs Learning ​

What we are not doing first ​

Decisions still open ​

When a phase ships ​

Related ​