wealthi-coach-mcp-server

Read-only MCP server giving Wealthi's AI Coach scoped access to student progress data, without the AI ever touching Firestore or Supabase directly.

Why this exists

Before this server, two clients wrote and read student data directly via SDK calls: the dashboard against Supabase, the mobile app against Firestore. Any AI feature built on top of that would need direct database credentials — which violates Wealthi's own AI philosophy ("AI should never receive unrestricted database access," "AI should not expose internal system data"). This server is the single, narrow, auditable path by which AI systems read student data. It does not replace the app's existing read/write paths for UI rendering; it exists specifically for AI consumption.

Domain ownership

Domain	System of record	Read by
XP, streak, points, level	Firestore (users/{uid})	get_student_progress, get_coach_context
Quiz attempts	Firestore (users/{uid}/quizAttempts)	get_assessment_results, get_curriculum_progress
Achievements	Firestore (users/{uid}/achievements)	(reserved — not yet exposed; see Future Work)
Identity, grade band, parent link	Supabase profiles (project qsawrfybwwpgajefndnk)	get_student_profile, get_coach_context
Coach seen-content tracker	Supabase profiles.routing_signals	get_learning_signals, get_coach_context

This split is intentional and permanent, not a migration waypoint. See project history for the full reasoning — short version: Firestore owns event-heavy gamification data because that's already its strength and mobile's home turf; Supabase owns identity/relational data because it needs joins and row-level security that Firestore doesn't offer.

Known infrastructure note: as of 2026-06, qsawrfybwwpgajefndnk is the confirmed-correct Supabase project — verified directly against wealthihome/.env's VITE_SUPABASE_URL, which is what the live app actually uses. Wealthi has had multiple Supabase projects connected to the same Lovable workspace with no "active" indicator in Lovable's panel itself, so don't trust Lovable's panel alone to determine which project is correct — always cross-check against the app's actual env var.

Read-only scope (by design, not just by convention)

This server never writes to Firestore or Supabase. All six tools carry readOnlyHint: true / destructiveHint: false annotations, and the service layer (src/services/) contains no write methods at all — there's no update, set, or delete call anywhere in this codebase. Writes continue to go through existing paths:

• Mobile's direct Firestore SDK writes (XP, streak, quiz submission)
• Dashboard's existing Supabase writes (profile updates, routing_signals)
• The dormancy-decay Edge Function (Supabase) for pattern-state decay

If a future use case needs the AI to act (e.g., "mark this content as seen" instead of just reading seen-content), that should be a deliberately designed, narrowly-scoped write tool added later with its own review — not an extension of this server's existing read tools, and not a broadening of its current credentials to writable ones.

Authentication & Credential Scoping

This server uses two separate, dedicated credentials, neither reused from any other Wealthi service. This matters because of a prior credential exposure incident — the fix isn't just rotating one key, it's making sure no future leak from this server compromises anything beyond what this server itself can read.

Firebase Admin (Firestore access)

1. In the Firebase console for the project backing the mobile app, go to Project Settings → Service Accounts.
2. Create a new service account specifically for this server — do not reuse the mobile app's or NestJS API's existing service account.
3. Grant it the Cloud Datastore Viewer IAM role (Google Cloud Console → IAM, not the Firebase console) — this is a read-only role scoped to Firestore/Datastore. Firestore has no separate "read-only Admin SDK mode"; the restriction must be enforced at the IAM role level. Do not grant roles/datastore.user or roles/owner — both include write access.
4. Generate a private key (JSON) for this service account and populate FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY in .env from its contents.
5. Store the JSON file itself in a secrets manager (not in this repo, not in plain .env in any deployed environment) — inject the three env vars at deploy time instead.

Supabase (identity + routing_signals access)

1. In the Supabase dashboard for project qsawrfybwwpgajefndnk, go to Authentication → Policies and confirm profiles has row-level security enabled (it should already, given existing app usage).
2. Create a dedicated Postgres role or use Supabase's API key management to issue a key scoped to read-only SELECT on profiles only — not the service_role key used by the existing Edge Functions. If Supabase's built-in key types don't offer this granularity directly, create a custom Postgres role with GRANT SELECT ON profiles TO wealthi_coach_readonly; and authenticate via that role's credentials, rather than defaulting to service_role.
3. Populate SUPABASE_URL and SUPABASE_COACH_READONLY_KEY in .env.

Rotation discipline

Given the prior exposure incident: rotate both credentials on a fixed schedule (recommend quarterly), and immediately if this repo's CI/CD config, deployment logs, or any environment dump is ever suspected compromised. Because credentials are scoped narrowly and not shared with any other service, rotating them only requires redeploying this server — no coordination needed with the mobile app, dashboard, or NestJS API.

Repo location

This server lives in its own repo (wealthi-coach-mcp-server), separate from wealthi-ai/wealthihome (dashboard) and the mobile app's repo. It is not the "Wealthi Intelligence" Supabase project (a separate, unrelated leads-generation database) — that naming collision was identified and deliberately avoided when naming this repo. If "Wealthi Intelligence" or "Wealthi System" comes up in conversation, confirm which of (a) this repo, (b) the leads-gen Supabase project, or (c) the qsawrfybwwpgajefndnk Supabase project is actually meant — they are three different things that have been confused before.

Project structure

wealthi-coach-mcp-server/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── index.ts                      # entry point, transport selection
│   ├── types.ts                      # Coach-facing domain shapes
│   ├── constants.ts                  # collection/table names, limits
│   ├── tools/                        # MCP tool contracts (thin)
│   │   ├── getStudentProfile.ts
│   │   ├── getStudentProgress.ts
│   │   ├── getAssessmentResults.ts
│   │   ├── getCurriculumProgress.ts
│   │   ├── getLearningSignals.ts
│   │   └── getCoachContext.ts
│   ├── services/                     # DB clients + query/composition logic
│   │   ├── firebaseClient.ts
│   │   ├── supabaseClient.ts
│   │   ├── firestoreProgressService.ts
│   │   ├── supabaseProfileService.ts
│   │   ├── curriculumService.ts
│   │   └── learningSignalsService.ts
│   └── schemas/
│       └── studentInput.ts           # shared Zod input schemas
└── dist/                             # build output (gitignored)

Setup

npm install
cp .env.example .env   # fill in real credentials, see above
npm run build
npm start               # stdio mode by default

For HTTP mode (remote deployment):

TRANSPORT=http PORT=3000 npm start

Test with the MCP Inspector:

npm run inspect

How the AI Coach client calls this server

The AI Coach currently runs as a feature inside the dashboard (AICoachCard, coachContent.ts). To call this server from that context, add it as an MCP server in the Claude API request the Coach feature already makes:

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    max_tokens: 1000,
    messages: [
      {
        role: "user",
        content: "Open a Coach session for this student and recommend what to show next."
      }
    ],
    mcp_servers: [
      {
        type: "url",
        url: "https://<your-deployed-host>/mcp",
        name: "wealthi-coach-mcp-server"
      }
    ]
  })
});

In practice, the Coach prompt should instruct the model to call get_coach_context first, with the current student's ID, before generating any response — that's the single round-trip that gives it profile, progress, learning signals, and curriculum state together. The finer-grained tools (get_student_profile, get_student_progress, etc.) exist for cases where only one piece is needed, or for debugging which specific data source is returning unexpected values.

The student ID passed to these tools should come from the authenticated session on the dashboard/mobile side, never from anything the AI itself infers or that a user can supply via chat — that's what keeps this a properly scoped, per-student tool rather than an open query surface.

Future work (not built yet)

• getAssessmentResults-style achievement tool (Firestore achievements collection is in the domain table but not yet exposed as a tool — add when Coach actually needs to reference specific achievements).
• Teacher/School platform tools, once those surfaces exist — they belong in this same tools/+services/ structure, not a separate server.
• If dormancy-decay and other currently-dormant Edge Functions get reactivated (see open infra note: they're pointed at a different Supabase project, jatohkwzfdoxzevnxrfl, than the live app uses, and have 0 invocations to date), get_learning_signals's momentum derivation may want to read their output directly instead of recomputing a simpler heuristic here.