populi-mcp
A compact MCP server for Populi API v2 that lets an AI client discover routes, read data, download files, find people, check connection status, and optionally make changes.
Search the bundled offline Populi route catalog by keyword, method, or route id.
Describe any route, including path placeholders, parameters, expand options, filters, required Populi roles, and docs link.
GETany Populi API route with filters, expands, pagination,all_pages, record limits, timeouts, and response truncation.Download route responses to the configured files folder, including PDF/XLS/CSV exports, transcripts, Data Slicer results, backups, and images, without overwriting existing files.
Find people by exact email and/or partial first/last name, returning ids, names, status, and primary contact data.
Check the configured Populi instance, sandbox/live key type, write status, and optionally verify the key with a live request.
When
POPULI_ALLOW_WRITES=true, create, update, or delete viaPOST/PUT/DELETEroutes and upload files with multipart requests; writes are disabled by default.Run locally over stdio or as a hosted Streamable HTTP server with per-user OAuth-style sign-in for Claude/ChatGPT connectors.
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., "@populi-mcp Find the person with email jane.doe@example.com and show their billing"
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.
populi-mcp
MCP server for the Populi API v2. It lets Claude, Codex, Cursor and any other Model Context Protocol client look up people, admissions, academics and billing data in your Populi instance, and, if you opt in, make changes.
Package: @kisasa/populi-mcp on npm. Command: populi-mcp. Transports: stdio (local, the default) or Streamable HTTP with sign-in (--http, for Claude and ChatGPT connectors). Protocol: MCP 2026-07-28, plus the 2025-era initialize handshake for older clients, on both transports.
How it works
Populi's API has 697 routes across 180 models. Exposing each as its own tool would flood a model's context, so this server gives the model a small toolset plus the API reference itself:
Tool | What it does |
| Keyword search over the bundled route catalog ( |
| Full reference for one route: path ids, required and optional fields with types, |
|
|
|
|
| Look up people by exact email and/or name. |
| Shows the instance, key type (sandbox or live), whether writes are on, the files folder and the timeout. |
|
|
Together they cover the whole API: all 492 documented GET routes, all 205 write routes, file uploads and file downloads. Routes that aren't in the bundled catalog work too, since the tools take any path.
A typical exchange: the model searches for the route, reads its parameters, then calls populi_get with a server-side filter.
The catalog is generated from the public API docs and ships inside the package, so searching and describing work offline and cost no API requests.
Related MCP server: sio-mcp
Configuration
Variable | Required | Description |
| yes | Your instance, e.g. |
| yes | An API key token. In Populi: Account & Settings > API > Keys (Account Administrator). Sent as a bearer token to |
| no | Set to |
| no | The one folder downloads are saved to and uploads are read from. Default: |
| no | How long one Populi request may take, 1000 to 600000. Default: |
The key's Populi roles decide what it can see. A route the key cannot reach returns a 403 naming the problem; populi_describe_api lists the roles each route needs.
Sandbox first
Populi issues separate sk_sandbox_... keys that only work against sandbox instances (live keys only work on live). Point this server at a sandbox while you evaluate it.
Read-only by default
With no POPULI_ALLOW_WRITES, the write tool is not registered at all, so the model cannot even attempt a change. When you enable it, populi_write is marked destructive, so clients that prompt for approval will ask before each call. DELETE in Populi is permanent.
Install
Requires Node.js 20 or newer. Every client below runs npx -y @kisasa/populi-mcp, so there is nothing to install by hand.
Claude Code
claude mcp add populi \
-e POPULI_BASE_URL=https://yourschool.populiweb.com \
-e POPULI_API_KEY=sk_sandbox_... \
-- npx -y @kisasa/populi-mcpClaude Desktop
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"populi": {
"command": "npx",
"args": ["-y", "@kisasa/populi-mcp"],
"env": {
"POPULI_BASE_URL": "https://yourschool.populiweb.com",
"POPULI_API_KEY": "sk_sandbox_..."
}
}
}
}On Windows, if Claude Desktop cannot find npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@kisasa/populi-mcp"].
Codex
codex mcp add populi \
--env POPULI_BASE_URL=https://yourschool.populiweb.com \
--env POPULI_API_KEY=sk_sandbox_... \
-- npx -y @kisasa/populi-mcpor in ~/.codex/config.toml:
[mcp_servers.populi]
command = "npx"
args = ["-y", "@kisasa/populi-mcp"]
[mcp_servers.populi.env]
POPULI_BASE_URL = "https://yourschool.populiweb.com"
POPULI_API_KEY = "sk_sandbox_..."Cursor
In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Cursor expands ${env:NAME}, which keeps the key out of the file:
{
"mcpServers": {
"populi": {
"command": "npx",
"args": ["-y", "@kisasa/populi-mcp"],
"env": {
"POPULI_BASE_URL": "https://yourschool.populiweb.com",
"POPULI_API_KEY": "${env:POPULI_API_KEY}"
}
}
}
}Any other MCP client
Run npx -y @kisasa/populi-mcp as a stdio server with POPULI_BASE_URL and POPULI_API_KEY in its environment.
More than one instance
Add one entry per instance under different names (populi-sandbox, populi-live), each with its own key.
Hosted server (Claude and ChatGPT connectors)
The stdio server above runs on each person's computer. To let a whole staff use Populi from Claude or ChatGPT (including the web and mobile apps, which can only reach remote servers), run the same code as a hosted server with --http and add it as a custom connector.
Each person signs in with their own Populi API key, so every request runs with that person's Populi permissions and rate limit. A key never has to be shared, and the operator holds no credentials: the key lives only inside an encrypted token that the person's AI app stores.
Claude / ChatGPT ──OAuth + MCP over HTTPS──▶ populi-mcp --http ──▶ Populi
(person clicks Connect, pastes their key once) (stateless, no database)How sign-in works
The app discovers the server (
/.well-known/oauth-...) and registers itself (RFC 7591), then sends the person to/authorize.That page asks for their Populi API key (and instance address, unless the deployment pins one), checks it with one live request, and optionally lets them opt in to writes.
The server returns an authorization code; the app trades it (with PKCE) for a one-hour access token and a 30-day refresh token. Both are AES-256-GCM sealed copies of the person's credentials, so the server stores nothing and any instance can serve any request.
Run it
docker build -t populi-mcp .
docker run -p 8080:8080 \
-e POPULI_MCP_SECRET="$(openssl rand -base64 48)" \
-e POPULI_BASE_URL=https://yourschool.populiweb.com \
-e POPULI_MCP_PUBLIC_URL=https://mcp.yourschool.edu \
populi-mcpWithout Docker: POPULI_MCP_SECRET=... npx -y @kisasa/populi-mcp --http. The connector URL is the public address plus /mcp. It must be served over HTTPS (put it behind a load balancer or reverse proxy, or use a host that terminates TLS for you).
Variable | Required | Description |
| yes | 32+ random characters. Seals every token. Changing it signs everyone out, so keep a copy. |
| no | Comma-separated older secrets that still open tokens, for rotation: put the new secret in |
| recommended | The |
| no | Pin everyone to one Populi instance; the connect page then asks only for a key. Tokens for any other instance stop working. |
| no | When the instance is not pinned, the hostname suffixes people may enter. Default |
| no |
|
| no | Where sign-in may send people back to: |
| no | As above. |
| no | Default |
Add it as a connector
Claude (claude.ai or Desktop): Settings > Connectors > Add custom connector, paste
https://<your address>/mcp. On Team and Enterprise plans an owner adds it once and each member then clicks Connect and signs in themselves.ChatGPT: Settings > Connectors (or Apps), enable developer mode if your workspace requires it, create a connector with the same URL, and choose OAuth. Workspace admins may need to allow custom connectors first.
Claude Code:
claude mcp add --transport http populi https://<your address>/mcp, then run/mcpto sign in.
Deploying it
The image runs anywhere containers do, and --http needs only Node.js 20+ if you would rather not use one. Where and how you deploy (which platform, what terminates HTTPS, how secrets are supplied) is up to you. A few things matter whatever you choose:
Pin a released version (
@kisasa/populi-mcp@x.y.z) rather than building frommain.Keep
POPULI_MCP_SECRETin your platform's secret store, and keep a copy: losing it signs everyone out.Allow long requests. Some Populi reports take minutes, so a front end that cuts requests off at 30 seconds will break them.
Allow request bodies of about 5 MB if people will upload files.
What differs from the local server
Files. There is no local files folder.
populi_downloadreturns text and JSON in full and attaches a file to the result (up to 4 MB);populi_writeuploads takecontent_base64only (the request body is limited to about 5 MB).No sessions. Every request is self-contained, so scaling and restarts are invisible. A warm instance still keeps each person's one-at-a-time queue and 429 backoff.
Protocol versions. Clients on MCP 2026-07-28 start with
server/discoverand send each request on its own, with noinitialize. Older clients get the classicinitializehandshake, answered statelessly. Both get plain JSON replies, never a stream, so buffered hosts work. The server advertises no tool-list changes, and turns downsubscriptions/listenstraight away rather than holding a stream open.Revoking access. Tokens can't be listed or revoked individually. Delete the person's key in Populi (the immediate fix), or rotate
POPULI_MCP_SECRETto sign everyone out.Authorization codes are not single-use (no database to track them), but they last five minutes and need the PKCE verifier only the connecting app holds.
Logs contain method, path, status and duration only: never bodies, tokens or keys.
API behaviors worth knowing
Rate limits. 50 requests/min per key from 3AM-7PM PST, 100/min overnight, plus per-IP and per-school limits. On HTTP 429 the call returns an error with how long to wait, and later calls fail fast with the remaining wait instead of hammering a limited key. Prefer one filtered call over many unfiltered ones.
One request at a time. Populi allows a single "heavy" call (Data Slicer, big exports) at once, so the server runs requests sequentially even if the client sends several in parallel.
Pages. Lists return at most 200 records.
all_pagesfollows every page up to 500 pages, stopping oncemax_records(default 500, up to 1,000,000) is reached. The page that crosses the limit is kept whole, so nothing is dropped. The result says whether itcompleted and otherwise gives anext_pageto resume from. If a rate limit or timeout hits part-way, the pages already fetched are returned, not thrown away.Filters. Populi ignores filter field names it does not know and returns the whole list, which looks like "everyone matches".
populi_describe_apilists the valid condition names for a route;populi_find_peopleuses the right ones for people.GET parameters.
filter,expand,pageandlimittravel in aparametersquery value, because most HTTP clients cannot send a GET body. If that would make the URL longer than about 7 KB (for example a filter listing thousands of ids), the request is sent as aGETwith a JSON body instead, which Populi documents as the normal form.POST/PUT/DELETEsend a JSON body.Large responses from
populi_getare truncated atmax_chars(default 40,000, up to 1,000,000) with a note on how to narrow the request. Usepopuli_downloadto save the whole thing to a file instead.File downloads. Routes that return a file (PDF/XLS/CSV exports, transcripts, Data Slicer results, file downloads) are fetched with
populi_download, which writes into the files folder. It never overwrites (an existing name gets-1,-2, ...), and only uses names, never paths, so it can't write outside the folder.populi_getdescribes a file response but can't show it.File uploads.
populi_writetakesfiles, each either apathinside the files folder orcontent_base64. They are sent asmultipart/form-datawith the file asfileand the other fields as a JSONparameterspart, which is how Populi's upload routes (/people/{id}/upload_file,/people/{id}/update_profile_picture,/libraryresources/{id}/update_image,/libraryresources/{id}/digitalresources/upload) expect them. As a safety cap, this server refuses files over 100 MB.The files folder is a boundary. A model can only read uploads from, and save downloads to,
POPULI_FILES_DIR. Paths that leave it, including through symlinks, are refused, so a prompt-injected "upload my SSH key" has nothing to read. Point it at a broader folder only if you want that.Timeouts. Populi publishes no timeout, and reports such as Data Slicer can be slow, so the default is two minutes. Your MCP client may enforce its own tool timeout as well, which this server can't raise; check its settings if a long report is cut off.
Student data is sensitive. Records can include SSNs, birthdates, grades and financial aid. The server never logs request or response bodies, and the key is never echoed in errors, but whatever a tool returns goes to your model provider. Use the narrowest key role and
expandyou need.
Development
git clone https://github.com/kisasa/populi-mcp.git
cd populi-mcp
npm install
npm run build # compile to dist/
npm test # unit + in-memory MCP tests, no networkTry it against a real instance:
POPULI_BASE_URL=https://yourschool.populiweb.com POPULI_API_KEY=sk_sandbox_... \
npx @modelcontextprotocol/inspector node dist/index.jsRefreshing the API catalog
data/catalog.json is scraped from the rendered API docs (Populi publishes no OpenAPI file):
npm run build:catalogReview and commit the diff when Populi ships API changes.
Releasing
Publishing is automated by .github/workflows/publish.yml on every push to main, and only acts when the version is new. To release:
Bump
versioninpackage.jsonand bothversionfields inserver.json.Merge to
main. The workflow publishes to npm (with provenance), the MCP Registry asio.github.kisasa/populi-mcp, and creates a GitHub release.
npm authentication uses trusted publishing if configured for this repo, otherwise the NPM_TOKEN repository secret.
License
MIT. Not affiliated with Populi. "Populi" is a trademark of its owner.
Available Tools
6 toolspopuli_describe_apiDescribe a Populi API routeARead-onlyIdempotent
Full reference for one route: path placeholders, required/optional parameters with types, expandable properties, filter conditions, required Populi roles, and a link to the docs. Pass a route id from populi_search_api, or a concrete method and path.
Inputs: id, path, method.
populi_downloadDownload from Populi to a fileA
GET a Populi route and save the response to a file in the files folder instead of returning it. Use it for routes that return files (PDF/XLS/CSV exports, transcripts and grade reports, Data Slicer results, file and backup downloads, images) and to keep a big list or full export out of the conversation (use all_pages). Takes the same arguments as populi_get. Never overwrites: an existing name gets -1, -2, ... appended. Returns the saved path and a short preview.
Inputs: path (required), page, limit, expand, +6 more.
populi_find_peopleFind people in PopuliARead-onlyIdempotent
Look up people by email address and/or name. Email is an exact match; first and last name are 'contains' matches. Returns Populi's people list: ids, names and status, plus a report_data block with the primary email and phone (contact_primary_email, contact_primary_phone). For full contact records fetch /people/{id} with expand=['email_addresses', 'phone_numbers']. Needs at least one criterion.
Inputs: email, limit, last_name, first_name.
populi_getRead from PopuliARead-onlyIdempotent
GET any Populi API v2 route (read-only). Path is under /api2, e.g. /people/123, /academicterms, /people/123/leads. Lists return up to 200 records per page; use page, limit, or all_pages. Use expand to inline related records (see populi_describe_api for the allowed names) and filter to narrow lists. A filter looks like {"0":{"logic":"ALL","fields":[{"name":"first_name","value":{"type":"CONTAINS","text":"john"},"positive":1}]}}. Populi allows about 50 requests/min per key, so prefer one filtered call over many unfiltered ones. Routes that return a file (PDF/XLS exports, transcripts, Data Slicer results, file downloads) can't be shown here: use populi_download for those. If a rate limit stops all_pages part-way, the pages already fetched are returned with a next_page to resume from.
Inputs: path (required), page, limit, expand, +6 more.
populi_search_apiSearch Populi API routesARead-onlyIdempotent
Search the Populi API v2 route catalog (697 routes across 180 models) by keyword, e.g. 'application', 'enrollments', 'invoice', 'course offering'. Returns route ids with method and path. Use this first to find the right route, then populi_describe_api for its parameters.
Inputs: query (required), limit, method.
populi_statusPopuli connection statusARead-onlyIdempotent
Shows which Populi instance this server talks to, whether the key is a sandbox key, and whether writes are enabled. Set verify to make one live request that checks the key works.
Inputs: verify.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct role: status/diagnostics, catalog search, route description, generic GET, file-saving GET, and people lookup. The main overlaps are populi_download vs populi_get (both fetch a route) and populi_find_people vs populi_get with filters, but the descriptions draw clear boundaries (files/big exports vs inline reads; name/email shortcut vs generic filtering).
All names share the populi_ prefix and snake_case, with mostly verb-based patterns (search_api, describe_api, get, download, find_people). populi_status is a noun rather than a verb, a minor deviation in an otherwise coherent scheme.
Six tools is well-scoped for a generic API gateway: discovery, execution, and two convenience wrappers, with no redundant entries. Nothing feels padded or missing at the count level.
The read path is well covered (search catalog, describe route, GET, download, plus a people shortcut), but there are no write/mutation tools despite populi_status explicitly reporting whether writes are enabled, implying a capability the surface doesn't expose. An agent asked to create or update records would hit a dead end.
Maintenance
Related MCP Connectors
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Find, document and execute authenticated API calls across 1000+ apps via one MCP server
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- FlicenseCqualityCmaintenanceEnables MCP-based access to the Edvibe School API for supported Pro-plan schools, exposing 78 operations categorized by risk for read, write, high-risk, and sensitive actions.78-
- FlicenseAqualityCmaintenanceEnables read-only interaction with CMU Student Information Online data, including student context, schedules, grades, enrollment, account activity, and campus life through MCP tools.8-
- AlicenseAqualityCmaintenanceEnables MCP clients to query Mindbody Public API v6 for schedules, attendance, sales, services, contracts, and client details, with PII masked before results reach the model and per-site rate pacing. Read-only by default, with writes and webhook administration available only behind explicit flags.13MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP-capable clients to browse, search, and manage projects, todos, messages, card tables, documents, uploads, comments, events, and webhooks through OAuth-authenticated API calls.-