origo-mcp

An MCP (Model Context Protocol) server that gives an AI agent (Claude, or any other MCP-compatible client) full administrator-level control of the Origo Abroad platform, by wrapping origo_backend's /admin, /crm, and /auth REST API as MCP tools.

It authenticates once as an admin/manager/staff account, caches the JWT, and automatically re-authenticates if the token expires. It runs locally over stdio, so it can be plugged straight into Claude Desktop, Cowork, or any other MCP client config.

What it covers

56 tools spanning: students (create/update/delete/notes & tasks), staff assignments, applications, CRM leads & consultations, loans (applications and product catalogue), scholarship applications, users & roles, management hierarchy, student-deletion approvals, referral codes, and the analytics/reporting endpoint. A generic admin_api_request fallback tool covers anything not wrapped by a dedicated tool, so new backend endpoints remain reachable without a server update.

Setup

pip install -r requirements.txt
cp .env.example .env   # then fill in your values

Required environment variables (see .env.example):

• ORIGO_API_BASE_URL — your origo_backend deployment URL, e.g. the Render service URL (no trailing slash).
• Either ORIGO_ADMIN_EMAIL + ORIGO_ADMIN_PASSWORD (recommended — the server logs in and auto-refreshes on expiry), or a pre-issued ORIGO_ADMIN_TOKEN.

The account you authenticate with determines what the agent can see and do: an admin account has unrestricted access; cluster_manager, manager, and staff accounts are scoped to their reporting hierarchy, same as when they log into the dashboard directly.

Run directly:

python origo_mcp_server.py

Connecting it to Claude Desktop / Cowork

Add to your MCP client's server config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "origo-admin": {
      "command": "python",
      "args": ["/absolute/path/to/origo_mcp_server.py"],
      "env": {
        "ORIGO_API_BASE_URL": "https://your-backend.onrender.com",
        "ORIGO_ADMIN_EMAIL": "you@origoabroad.com",
        "ORIGO_ADMIN_PASSWORD": "your-password"
      }
    }
  }
}

Safety notes

• delete_student, delete_user, and approve_deletion_request are irreversible. The tool descriptions flag this so agents confirm intent before calling them, but there is no server-side undo.
• The server only ever holds one bearer token in memory (not persisted to disk); credentials live in your environment/config, not in this repo.
• Every action is subject to the same role-based access control as the dashboard itself — the MCP server does not bypass origo_backend's permission checks, it just calls the same API a logged-in staff member would.

Extending it

Each tool is a thin wrapper: a Python function decorated with @mcp.tool() that calls _call(method, path, params=..., json_body=...). To add coverage for a new backend endpoint, either add a small dedicated wrapper next to the related tools, or just call it via admin_api_request until you do.