Skip to main content
Glama
ManageBac MCP Server

ManageBac MCP Server

by Bjoseph23

ManageBac MCP Server

A read-only MCP server, written in Python with FastMCP, that lets an AI assistant query school data from the ManageBac 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.

Related MCP server: Synapse MCP

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.

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

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

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.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers