SchoolBridge

SchoolBridge is a small MCP (Model Context Protocol) server that lets an AI agent safely query and act on school data — attendance, fees, student records — without ever bypassing role-based access control. It exists to answer one question: can an AI agent be given access to a school's data without that access becoming a liability?

Every single read or write request, from any role, goes through one shared authorization function. If that function doesn't explicitly allow a request, it is denied — there is no default-allow path anywhere in this project. Every request, allowed or denied, is written to an audit log. Write actions (like recording a fee payment) never happen in a single step: an agent can only propose a write, and a school admin must separately confirm it before anything is actually saved.

This is a proof-of-concept built with 100% synthetic, fictional data. It does not connect to any real school, ERP vendor, or student records.

Who is who (roles)

Role	Can see
Admin	Everything in their own school; the only role that can confirm write actions
Teacher	Only the classes they're assigned to teach
Parent	Only their own child's record (never a whole class)
Student	Only their own record, read-only

Prerequisites

• Python 3.10 or newer installed on your machine.
• No internet connection or API keys are needed — everything runs locally against a local SQLite database file.

To check you have Python installed, open a terminal and run:

python --version

If that fails, try python3 --version or py --version instead — use whichever one works for the rest of these commands.

Setup

Open a terminal in this folder (school-erp-mcp/) and run the following, one line at a time.

Windows (PowerShell or Command Prompt):

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

You'll know it worked if your terminal prompt now starts with (.venv).

Create the demo data

This generates a local database file (data/school_erp.db) with two fake schools, fake classes, fake students, and fake staff/parent accounts. No real people or real schools are involved.

python -m data.seed

You should see output like:

Seeded 2 schools, 8 students, 22 requesters, 0 pending actions.

If you ever want to start over with a completely fresh database, delete data/school_erp.db and run this command again.

Run the tests

This proves the access-control rules actually work — every role, every "who can see what" boundary, and the write-approval flow.

pytest tests/ -v

All tests should show PASSED. If you see any FAILED, something is broken and should not be trusted — please report it rather than assuming it's fine.

Try it yourself

For a full, copy-pasteable walkthrough — an allowed query, a denied query, a complete write-approval flow, and the resulting audit log — see docs/demo.md.

Run the actual MCP server

Once you're happy with the demo, the server itself is started with:

python server.py

This starts the MCP server over stdio, ready for an MCP-compatible AI client (e.g. Claude Desktop, or any MCP client) to connect to it and call its tools (get_attendance, get_fee_status, get_student_summary, flag_defaulters, get_recent_audit_log, propose_fee_payment, propose_attendance_update, confirm_action).

How access control works, in plain terms

Every tool call goes through one function: authorize() (core/access_control.py). It checks, in this exact order:

1. Does this requester_id actually exist? If not, deny.
2. Is the thing they're asking about (a student, a class) in their own school? If it's in a different school, deny — no exceptions.
3. Are they an admin? If so, allow (within their own school).
4. Are they a teacher, and is this their class (or a student in their class)? If so, allow.
5. Are they a parent, and is this specifically their own child (never a whole class)? If so, allow — otherwise deny.
6. Are they a student, and is this specifically their own record, read-only? If so, allow — otherwise deny.
7. Anything else: deny.

No tool ever implements its own version of this check — they all call the exact same function, so there's exactly one place in the whole codebase where "who can see what" is decided.

How the audit log works

Every single request — allowed or denied — is appended to logs/audit.jsonl as one line of JSON: who asked, what role they have, what they asked for, and whether it was allowed. It deliberately never records the actual sensitive data (fee amounts, attendance numbers) — only that the request happened. Only admins can read this log (get_recent_audit_log), and only for their own school.

How write actions (like recording a payment) work

An AI agent can never go straight from "record this payment" to it being saved. It's always two separate steps:

1. Propose — propose_fee_payment or propose_attendance_update creates a pending request and returns an id. Nothing is saved yet.
2. Confirm — a school admin calls confirm_action with that id. Only then is the change actually applied. The confirmation re-checks that the confirming admin is still allowed to approve this — it does not just trust that the original request was fine.

Pending requests that aren't confirmed within 15 minutes expire and can no longer be confirmed.

What this project deliberately does not do (v1 scope)

• It does not connect to any real school ERP (Fedena, Entab, etc.) — that would be a future integration layer on top of this.
• It has no web dashboard or user interface — it's an API layer for AI agents, accessed via MCP.
• It does not handle billing, multi-school onboarding, or real payment processing.
• All data is synthetic. There is no real student, parent, or staff information anywhere in this repository.