Halo LMS MCP Server

MCP server that exposes Grand Canyon University's Halo LMS APIs as tools for AI agents. Provides access to classes, grades, discussions, announcements, inbox messages, notifications, assignment submissions, and user profiles.

Setup

1. Install dependencies

cd HaloMCP
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure tokens

Copy the example config and fill in your tokens:

cp config.example.json config.json

Edit config.json with your Halo auth and context tokens (without the Bearer prefix — it's added automatically):

{
  "authToken": "eyJ...",
  "contextToken": "eyJ...",
  "transactionId": "tenant-uuid-user-uuid"
}

Alternatively, set environment variables (these override config.json):

export HALO_AUTH_TOKEN="eyJ..."
export HALO_CONTEXT_TOKEN="eyJ..."
export HALO_TRANSACTION_ID="..."

Related MCP server: Moodle MCP Server

Running

Claude Code (stdio)

Add to your Claude Code MCP config (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "halo-lms": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/HaloMCP"
    }
  }
}

Direct (stdio)

python server.py

Docker (Streamable HTTP on port 8000)

docker compose up -d

Then add it to Claude Code CLI:

claude mcp add --transport http halo-lms http://localhost:8000/mcp

The Docker container bind-mounts config.json (writable, so token refresh can persist new tokens) and your home directory (read-only) from the host, so file uploads via file_path work the same as stdio mode.

Note: Previous versions used SSE transport (/sse endpoint). Streamable HTTP (/mcp endpoint) is the current MCP standard and is recommended for all new deployments.

Token Refresh

Halo tokens expire periodically, but the server handles this automatically:

One-time setup

After configuring config.json with your tokens, call the setup_session tool. This creates a long-lived session (~30 days) that enables automatic token refresh.

setup_session → "Session created, expires 2026-03-24T..."

How it works

1. setup_session calls Halo's next-auth API to create a session from your tokens

2. The session cookie is stored in config.json

3. When tokens expire during any API call, the server automatically:

   • Uses the session cookie to fetch fresh tokens

   • Saves the new tokens to config.json

   • Retries the failed request

4. This is completely transparent — no user intervention needed

When the session expires (~30 days)

1. Get fresh tokens from your browser (DevTools → Network/Cookies)

2. Update config.json with the new authToken and contextToken

3. Call setup_session again

Manual token management

• check_tokens — verify current tokens are valid

• reload_tokens — hot-reload tokens from config.json

• refresh — manually trigger a session-based token refresh

• setup_session — create/renew the long-lived session

Available Tools