# 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

```bash
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:

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

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