ManageBac MCP Server
by Bjoseph23
README.md
# ManageBac MCP Server
A read-only [MCP](https://modelcontextprotocol.io) server, written in Python with
[FastMCP](https://gofastmcp.com), that lets an AI assistant query school data from
the [ManageBac](https://www.managebac.com) API v2.
## The problem
Teachers and administrators at a school that uses ManageBac often want to ask an AI
assistant questions about their classes, grades, attendance and students. ManageBac
exposes this data through a paginated REST API, which an AI agent can't use directly:
it needs well-described tools, results trimmed to what matters, and every page of a
long list collected for it. This server sits between the two. It exposes ManageBac as
**read-only** MCP tools, protects access with a bearer token, and returns compact,
predictable results with short error messages.
## How it works
- **FastMCP server** (`managebac_server.py`) with **48 read-only tools** (every tool
makes `GET` requests only), for example `get_classes`, `get_class_roster`,
`get_term_grades`, `get_class_term_attendance`, `search_students`,
`get_daily_excusals`, `get_program_performance_report` and `get_student_trend`.
- **Bearer-token authentication.** Every MCP request must send
`Authorization: Bearer <MCP_AUTH_TOKEN>`. The token is checked with
`hmac.compare_digest` (constant-time comparison), and the server **refuses to start
if `MCP_AUTH_TOKEN` is not set** (fail closed). Only `/health` is unauthenticated,
and it returns `{"status": "ok"}` and no school data.
- **Async HTTP client.** A single shared `httpx.AsyncClient` with a 20 second timeout.
- **Pagination.** `_get_all_pages` follows ManageBac's `meta.total_pages`, up to a hard
cap of 20 pages, and reports `truncated` if the cap is hit. `get_classes` and
`search_students` collect every page unless you pass `page` explicitly.
- **Concurrency limit.** Reports that combine several classes
(`get_program_performance_report`, `get_student_trend`) run their upstream calls
concurrently, with at most 5 in flight (`_gather_limited`).
- **Safe errors.** Upstream error bodies are logged on the server only. The model gets a
short message such as `ManageBac API returned HTTP 500.`.
- **Trimmed results.** Tools return only the fields an assistant needs, in a consistent
`{"ok": true, "summary": ..., ...}` / `{"ok": false, "error": ...}` shape.
- **Optional MCP Apps spike** (`mcp_apps.py`). Setting `ENABLE_MCP_APPS=1` registers one
extra tool, `grade_distribution_app`, which renders a grade histogram in hosts that
support MCP Apps. Its payload contains aggregate counts and statistics only, with no
student names or IDs. Off by default.
## Project context
This repository is a standalone sample extracted from a larger private project (a school
data assistant / chatbot that consumes this MCP server). It was published separately as
a clean code sample, so it has a short commit history.
## Setup
Tested on Python 3.13.
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # then fill in real values; never commit .env
```
### Environment variables
| Variable | Required | Purpose |
|---|---|---|
| `MCP_AUTH_TOKEN` | **yes** | Bearer token clients must send. The server will not start without it. Use 32+ random characters. |
| `MANAGEBAC_API_TOKEN` | yes, for real data | ManageBac API token. Create it read-only with minimal scopes. |
| `ENABLE_MCP_APPS` | no | `1` registers the experimental `grade_distribution_app` tool. |
| `LOG_LEVEL` | no | Default `INFO`. Upstream error bodies are logged here, never returned to the model. |
## Run
```bash
fastmcp run managebac_server.py --transport sse --host 0.0.0.0 --port 8000
```
The SSE endpoint is `/sse` and the health check is `/health`. Clients must send
`Authorization: Bearer $MCP_AUTH_TOKEN`.
## Deploy (Render)
Create a Render web service from this repository and set:
- **Build command:** `pip install -r requirements.txt`
- **Start command:** `fastmcp run managebac_server.py --transport sse --host 0.0.0.0 --port $PORT`
- **Environment:** `MCP_AUTH_TOKEN` and `MANAGEBAC_API_TOKEN` (and optionally `LOG_LEVEL`)
- **Health check path:** `/health`
Verify a deployment (replace `<your-deployment-host>`):
```bash
curl -s -o /dev/null -w "%{http_code}\n" https://<your-deployment-host>/sse # 401 without a token
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $MCP_AUTH_TOKEN" -m 3 https://<your-deployment-host>/sse # 200 (stream opens; -m 3 stops it)
curl -s https://<your-deployment-host>/health # {"status":"ok"}
```
## Testing
The tests use mocked HTTP (`httpx.MockTransport`), so they need no network and no real
ManageBac account.
```bash
pip install -r requirements-dev.txt
pytest
```
What is covered:
- `tests/test_auth.py`: the verifier accepts only the exact token, the server refuses to
start without `MCP_AUTH_TOKEN`, `/health` is open, and the MCP endpoint returns 401 for
a missing or wrong token.
- `tests/test_pagination.py`: pages are followed and collected, the 20-page cap reports
`truncated`, an error on a later page is surfaced, `get_classes` auto-paginates, and
the concurrency limit holds.
- `tests/test_upstream_errors.py`: upstream error bodies are logged but not returned,
connection failures and non-JSON responses give short messages, the ManageBac token is
sent upstream, and the server contains no write (`POST`/`PUT`/`PATCH`/`DELETE`) calls.
## Security notes
- The server is **read-only**: it only issues `GET` requests to ManageBac.
- Use a read-only ManageBac API token with the minimum scopes you need.
- Never commit `.env`; it is listed in `.gitignore`. Use `.env.example` for placeholders.
- The tools return real student data, so deploy behind HTTPS and keep `MCP_AUTH_TOKEN`
secret.
- Dependencies are pinned. fastmcp 4.x / mcp 2.x change APIs, so upgrade deliberately.
## Project layout
```
managebac_server.py FastMCP server: auth, HTTP client, pagination, tools
mcp_apps.py optional aggregate-only grade-distribution MCP App
tests/ pytest suite (mocked HTTP)
.env.example placeholder configuration
```
## License
MIT. See [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues