Skip to main content
Glama
ManageBac MCP Server

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).