populi-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| POPULI_API_KEY | Yes | A Populi API key token, found in Account & Settings > API > Keys. Sent as a bearer token to POPULI_BASE_URL only. | |
| POPULI_BASE_URL | Yes | Your Populi instance URL, e.g. https://yourschool.populiweb.com. Must be https; a trailing /api2 is optional. | |
| POPULI_FILES_DIR | No | The folder downloads are saved to and uploads are read from. | ~/populi-mcp-files |
| POPULI_TIMEOUT_MS | No | How long one Populi request may take, from 1000 to 600000 milliseconds. | 120000 |
| POPULI_ALLOW_WRITES | No | Set to true to enable the populi_write tool. Default is read-only. | false |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Populi is a student information system (people, admissions, academics, billing). This server exposes its API v2.
Workflow: populi_search_api to find a route, populi_describe_api for its parameters, then populi_get to read. Use populi_find_people to look up a person by email or name.
List routes return at most 200 records per page and the key is limited to about 50 requests per minute, so filter on the server side (
filter) instead of paging everything.Many routes need a path id (e.g. /people/{id}); replace placeholders such as (person) with real ids.
Fetching a person returns their record, not their contact details, unless you pass expand (e.g. email_addresses, phone_numbers).
Records can contain sensitive student data (SSNs, birthdates, grades, financial aid). Request only the fields and expands you need.
Routes that return files (PDF/XLS/CSV exports, transcripts, Data Slicer results, file downloads) need populi_download, which saves into the files folder (or, on a hosted server, attaches the file to the result). all_pages with populi_download also keeps a large export out of the conversation.
Requests run one at a time (Populi allows a single heavy call at once). If the key is rate limited, later calls fail fast with the wait time instead of retrying; a partly fetched all_pages returns what it got and a next_page to resume from.
This server is read-only; creating, updating and deleting records is disabled.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| populi_statusA | Shows which Populi instance this server talks to, whether the key is a sandbox key, and whether writes are enabled. Set |
| populi_search_apiA | 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. |
| populi_describe_apiA | 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. |
| populi_getA | 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 |
| populi_downloadA | 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. |
| populi_find_peopleA | 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 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.