POLITEMall MCP Server
The exposed schema provides a small, read-only POLITEMall toolset for courses and your own academic data.
List your enrolled POLITEMall courses.
Get a course’s module/topic table of contents.
Get your grade items and scores for a course.
Get a course’s announcements/news.
Get a course’s calendar events.
Get a course’s assignment/dropbox folders and due dates.
Check the currently authenticated POLITEMall user’s identity.
Course-specific tools take a numeric courseId (orgUnitId) from list_courses; this schema exposes no write, instructor, quiz-authoring, discussion, survey, or catalog tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@POLITEMall MCP Server what are my current grades?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
politemall-mcp
MCP server for the Singapore polytechnic/ITE learning systems on POLITEMall: the two D2L Brightspace tenants POLITEMall and NYP. Talks directly to each tenant's own REST API as the signed-in person — no institutional API key or app registration involved.
Live server: https://<your-server-host> — one shared server; each person signs in once with
their own Microsoft account. The exact same server (same tools, same code) can also
run on your own machine with npx -y @qiaoguanming/politemall-mcp@latest, signing in in
your own browser and keeping your sign-in data on your own disk.
The two tenants
One sign-in covers both:
POLITEMall (
lms.polite.edu.sg) — shared D2L Brightspace instance across polytechnics.NYP (
nyplms.polite.edu.sg) — NYP's own dedicated D2L Brightspace instance.
Related MCP server: moodle-utn-mcp
Tools
D2L (POLITEMall and NYP) — courseId is an opaque string like politemall:6606
or nyp:12345 returned by list_courses; it encodes which of the two schools the
course belongs to, so just pass it through as-is to the other tools.
Tool | What it does |
| Your enrolled courses, merged across POLITEMall and/or NYP |
| Content items with due dates across every course and connected school in one call — completed and pending |
| D2L-computed overdue items across every course and connected school — a filtered view distinct from |
| Counts of unread/pending activity (discussions, feedback, quizzes) across every course and connected school — a "what's new" feed |
| Your calendar events across every course and connected school in one call, within a date window (default: 7 days ago to 60 days ahead) |
| The course's module/topic tree — one call — with |
| A single content topic — a drill-down from |
| The course description/overview content (the "Class Overview"/syllabus) |
| Grade items and your scores |
| Your calculated/adjusted final grade for a course |
| Latest announcements, newest first, plain text, drafts excluded — for one course or (no |
| Course calendar events |
| Assignments and quizzes, soonest due first — instructions, rubric, whether you've submitted, your files and feedback, quiz attempts, plus scored items that have no assignment behind them. One course, or all active courses |
| Read the files an instructor attached to an assignment (PDF, DOCX, XLSX, PPTX, text): list which assignments have attachments, then read one and get its text |
| Your own submission (files, dates, score, feedback) for an assignment folder |
| Quiz list, then your attempt scores/status for one |
| Questions defined for a quiz |
| Drill down forums → topics → actual post content and authors |
| Who is in a course: headcount per role, plus the staff by default (students only with |
| Rubric criteria/levels — by |
| Survey list, then your attempt history for one |
| Questions defined for a survey |
| Group categories and groups, with member counts |
| Your identity on each connected school |
POLITEMall/NYP (D2L), instructor/TA only — same courseIds as above, but
these call grading-permission-gated endpoints. A student's session gets a clear
permission error, not their own data, if they call one of these by mistake.
Tool | What it does |
| Every grade item and score for every student — the gradebook view |
| Every student's calculated/adjusted final grade — the gradebook's final-grade column |
| Every student's attempts for a quiz (or one student's, by classlist Identifier) |
| Every student's attempts for a survey (or one student's, by classlist Identifier) |
| Every student's submission for an assignment folder — files, dates, score, grading status |
POLITEMall/NYP (D2L), quiz authoring (instructor/TA only, writes to the school) — the only tools that change anything in D2L. Every other tool is read-only. Your MCP client should ask before running them. The agent turns your question list (Excel, CSV, a document) into structured data; these tools never read files.
Tool | What it does |
| Create an empty quiz — hidden from students unless |
| Change those settings on an existing quiz; settings you leave out keep their value |
| Add questions to a quiz (up to 100 per call), or update existing ones by |
All three take dryRun: true to preview the request without changing anything. There is no tool to delete
a quiz or a question. Example question list for save_quiz_questions:
[
{ "type": "multiple_choice", "text": "Capital of France?", "answers": [
{ "text": "Paris", "correct": true }, { "text": "Rome", "correct": false } ] },
{ "type": "true_false", "text": "Water boils at 100 °C at sea level.", "answer": true, "points": 2 },
{ "type": "matching", "text": "Match the symbol", "pairs": [
{ "prompt": "H2O", "match": "Water" }, { "prompt": "NaCl", "match": "Salt" } ] }
]POLITEMall/NYP (D2L), long-tail escape hatch — the tools above are a curated slice of the
~190 read (GET) routes Valence exposes under Learning Environment; the rest are reachable
without a dedicated tool for each one. Start with the curated tools above — they're
response-shaped and better-documented. Reach for these only when nothing above covers what you
need.
Tool | What it does |
| Search/browse the full route catalog by category or keyword, to find an operation's key and required parameters |
| Invoke any cataloged operation by key — returns D2L's raw JSON response, unshaped. Course-scoped operations take |
POLITEMall public catalog — a third, separate system again: the marketing
site at politemall.polite.edu.sg, not Brightspace. No login required.
Tool | What it does |
| Search/browse all ~300 modules in the public marketing catalog across every poly/ITE — not your enrollments |
Valence (the actual Brightspace/D2L API) has no endpoint for browsing courses
you're not enrolled in, for any non-admin role — confirmed by testing directly,
not just reading docs: even GET /d2l/api/lp/(version)/courses/(orgUnitId) for a
course we are enrolled in returns 403 Forbidden, since it needs a
course-management permission regular students/staff don't have. The public
catalog above is the closest available substitute for "what modules exist" —
but note its catalogCode values (e.g. D-NP-06030001) are a completely
different ID space from Brightspace courseIds and can't be passed to
get_grades/get_course_content/etc.
Evidence links
Tool results let you check what you were told. Where a result has a page on the school's site, it carries the link next to the data:
sourceUrlon an item (an announcement, quiz, assignment, content topic, discussion topic, calendar event, ...) opens that item.pageUrlon a result opens the page that shows the whole result (the classlist, "my grades", a course's quiz list). An item with no verified page has no link at all, not a guessed one.provenance(or, for results that are plain lists, a second text block) says which system the data came from (NYP Brightspace, POLITEMall Brightspace) and when it was read....Sgtfields (dueDateSgt,dateSgt, ...) give the same instant as the original UTC value in Singapore time (+08:00), which is what the sites display. The original value is never changed.Links inside announcement, discussion or description text were written by other people; results flag them (
untrustedLinksInText) and they are never used as evidence.
The server also sends citation rules to the connecting agent (cite the sourceUrl, never build or
edit a link, say when there is none). A link opens only for someone signed in to that school in
their browser, and it can show only what that person is already allowed to see. Every
pattern is opened in a real session before it is emitted, and test-oracle/verify-links.js
re-checks them.
Two environment switches (see deploy/README.md): SOURCE_LINKS=off removes all
of the above and returns the previous result shapes; SOURCE_RESOURCE_LINKS=on additionally
returns MCP resource_link blocks for clients that display them.
Connecting
You connect with only the server URL. The first time, your MCP client opens a sign-in page in your browser; you type your own Microsoft account and approve MFA there, and you're connected. Nothing to install, no cookies or tokens to copy.
How the sign-in works. The page shows a live view of a browser running on the server, at the real Microsoft sign-in page. What you type goes only to Microsoft's page: it isn't stored or logged. When you reach POLITEMall (and NYP, which signs in automatically from the same Microsoft session), the server keeps your D2L session, exchanges it for an access token, and renews that token itself. If the session ever lapses it first tries to renew it silently from your saved Microsoft sign-in; only if Microsoft asks for something again will a tool reply with a fresh one-time sign-in link.
What the server keeps about you (all encrypted at rest): your D2L session for each tenant, your current access token, and your Microsoft sign-in state, which is deleted after 30 days without use. By connecting you trust this server with that state, so only connect to a server you trust. To delete everything and revoke every token your MCP clients hold:
curl -X POST https://<your-server-host>/signout -H "Authorization: Bearer <your MCP access token>"Sign-ins are limited to a few at a time; if the server is busy, try again in a minute.
Connecting your MCP client
Claude Code
claude mcp add --transport http politemall https://<your-server-host>/mcpAdd --scope user to make it available in every project, not just the current one. Then run
/mcp in Claude Code, choose politemall and Authenticate; your browser opens the sign-in page.
Claude Desktop
Settings → Connectors → Add custom connector, name it, and enter
https://<your-server-host>/mcp. Claude Desktop opens the sign-in page in your browser.
Microsoft Copilot Studio
Your agent → Tools → Add a tool → New tool → Model Context Protocol, server URL
https://<your-server-host>/mcp, authentication OAuth 2.0 with dynamic discovery (the
server publishes its OAuth metadata and supports dynamic client registration and PKCE).
Security notes
There is no signup and no shared secret: an MCP access token is only issued after a completed Microsoft sign-in, and it identifies a person, nothing more.
Sign-in links are unguessable, single-use and short-lived; each runs in its own isolated browser that is closed as soon as the sign-in ends, fails, times out or you leave the page.
D2L sessions, access tokens and Microsoft sign-in state are encrypted at rest (AES-256-GCM) and used only server-side to call D2L on your behalf. Typed credentials, cookies and tokens are never logged;
/mcpand/signinrequests are rate-limited and audit-logged with a short one-way hash of your id, a timestamp and IP.OAuth endpoints enforce PKCE and exact redirect-URI matching; authorization codes work once.
Architecture
server/
control-plane/ the MCP server (Streamable HTTP) — the only server in this repo
src/
index.ts hosted entry point; app.ts builds the HTTP app
local/ npx entry point: stdio server, local-browser sign-in, key storage, CLI
server.ts builds the MCP server for one caller
api/ D2L client: version discovery, routes, pagination, errors
auth/ OAuth server, streamed sign-in, session vault, token mint/renewal, encryption, rate limiting
tools/ one file per tool (+ shared helpers and schemas)
utils/ config, audit log, HTML→Markdown, PDF/Office text extraction, deep links
types/ shared types, incl. ToolContext
tests/ mirrors src/ (api/, auth/, tools/, utils/); run with `npm test`
docker-compose.yml, Caddyfile
deploy/ AWS provisioning notes/scripts for the hosted serverTools never know where a caller's sessions live: they receive a ToolContext
(types/tool-context.ts), so the hosted server and a local run expose the identical
tool set. See deploy/README.md for how the server is provisioned
and operated on AWS.
Running it locally
The same tools, D2L client and session handling run on your own computer, started by your MCP
client with npx. Only two things differ from the hosted server: you sign in in a browser window
on your own computer, and your sign-in data stays on your own disk.
Add this to your MCP client's servers (or run npx -y @qiaoguanming/politemall-mcp@latest setup and answer yes
for the clients it finds):
{ "mcpServers": { "politemall": { "command": "npx", "args": ["-y", "@qiaoguanming/politemall-mcp@latest"] } } }Needs Node.js 22 or newer and Google Chrome or Microsoft Edge (or set CHROMIUM_PATH to a Chrome,
Edge or Chromium executable). Nothing is downloaded. The first time you ask for something, a
browser window opens on the school's Microsoft sign-in; type your own credentials and approve MFA
there. The window closes by itself and you ask again. On macOS run npx from your home folder, not
Documents, Desktop or Downloads.
Command | What it does |
| Runs the MCP server over stdio (what your client launches) |
| Checks Node and the browser, offers to add the server to your MCP clients, offers to sign in. Never asks for a password |
| Opens the sign-in window now (also retries a stuck sign-in) |
| Deletes the sign-in data stored on this computer (does not sign you out of Microsoft or the school elsewhere) |
| Checks Node, browser, key storage, data directory, connectivity and who is signed in; prints no secrets |
Where your data lives. Encrypted sessions are in sessions.json under %APPDATA%\politemall-mcp
(Windows), ~/Library/Application Support/politemall-mcp (macOS) or ~/.local/share/politemall-mcp
(Linux); set POLITEMALL_DATA_DIR to move it. The encryption key is kept in the operating
system's credential store (Keychain, Credential Manager, Secret Service) and, only when none is
available, in an owner-only master.key beside it. doctor tells you which. Your Microsoft
password is never stored or seen by this program.
npx -y @qiaoguanming/politemall-mcp@latest always runs the newest release (npx may reuse a cached copy for a
short while). To pin one, use @qiaoguanming/politemall-mcp@X.Y.Z; releases are listed on the
releases page.
Developing it: from server/control-plane, npm ci && npm run build, then
node dist/local/cli.js is the same command. Tests: npm test (compiles src/ and tests/, then
runs everything with Node's test runner).
Contributing and releases
Changes go through pull requests with a Conventional Commit title (feat: ..., fix: ...); CI must pass. Versions, tags and CHANGELOG.md are produced by release-please: merge the Release PR to cut a release. A release does not deploy; see deploy/README.md for deploying. Full rules for people and agents: .claude/rules/cicd.md.
License
MIT. Third-party notices are in THIRD_PARTY_NOTICES.md.
Available Tools
7 toolsget_announcementsGet announcementsA
Get news/announcements posted in a course.
Inputs: courseId (required).
get_assignmentsGet assignmentsB
Get dropbox/assignment folders and due dates for a course.
Inputs: courseId (required).
get_calendar_eventsGet calendar eventsB
Get calendar events for a course.
Inputs: courseId (required).
get_course_contentGet course contentA
Get the module/topic table of contents for a course.
Inputs: courseId (required).
get_gradesGet gradesB
Get your grade items and scores for a course.
Inputs: courseId (required).
list_coursesList coursesA
List the courses you are enrolled in on POLITEMall.
Inputs: no named parameters.
whoamiWhoamiA
Get the currently authenticated POLITEMall user's identity.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct resource type: courses, content, grades, announcements, calendar events, assignments, and user identity. There is no overlap or ambiguity between them.
All tools follow a consistent verb_noun snake_case pattern (list_courses, get_course_content, get_grades), with 'whoami' being a standard exception. The naming is predictable and readable.
Seven tools is well within the ideal 3-15 range and appropriately covers the core student-facing features of an LMS without unnecessary bulk.
The surface covers the main read-only information needs: enrollment, content, grades, announcements, calendar, and assignments. Missing discussion forums or quizzes are minor gaps for a read-only student portal.
Maintenance
Related MCP Connectors
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
PLATO (Pusan National University LMS) MCP server via Moodle Web Service API + ubboard scraping
Unofficial Wentworth (WIT) course catalog and student schedule. Needs a WIT sign-in.
Read Lessonspace sessions, recordings, transcripts, spaces and users; launch spaces, edit sessions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables reading and writing Canvas LMS course content using browser session cookies, without needing an API key.MIT
- FlicenseNot gradedqualityBmaintenanceEnables browser-based login to approved UTN Moodle sites and read-only access to the user's profile, course list, and course activities via local Chromium automation.2-
- AlicenseAqualityBmaintenanceGives Claude, Codex, Cursor and any other MCP client read access to your courses, content, files, grades, deadlines, announcements and discussions, using your own browser session.3143 npm5MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to access and manage academic course information, assignments, submissions, grades, calendars, materials, recordings, and announcements through authenticated LMS sessions.MIT