Setup guide

Step-by-step setup for brightspace-mcp. If your school uses Microsoft Azure AD or Google Workspace SSO, also read presets.md.

Step 0 (optional): Non-interactive setup for CI/scripts

If you're in a CI pipeline or DevContainer with no TTY, use init instead of setup:

npx brightspace-mcp@latest init \
  --base-url https://yourschool.brightspace.com \
  --strategy browser \
  --preset microsoft \
  --username-ref env:BRIGHTSPACE_USERNAME \
  --password-ref env:BRIGHTSPACE_PASSWORD \
  --tz America/Bogota \
  --locale es-419

Run npx brightspace-mcp@latest init --help to see all flags and strategy-specific options.

Step 1 — Install

npm install -g brightspace-mcp     # global
# or
npx brightspace-mcp@latest setup   # one-shot, no install

Requires Node ≥ 20.

Step 2 — Find your Brightspace base URL

Open Brightspace in a browser. The URL bar shows something like:

• https://learn.example.edu/d2l/home/... → base URL is https://learn.example.edu
• https://learn.school.edu/d2l/home/... → base URL is https://learn.school.edu

⚠️ Do not leave https://school.brightspace.com as the default — it's a placeholder. The server will fail at startup with version discovery failed if it's wrong.

Step 3 — Choose your auth strategy

Four setup paths (use init from Step 0 if you're in CI/scripts with no TTY):

A. Interactive wizard (typed credentials)

npx brightspace-mcp@latest setup

Walks through base URL, auth strategy, credentials, MFA, timezone, and display language — then writes ~/.brightspace-mcp/config.yaml with mode 0600. Prompts appear in your system language automatically.

B. Recorder (you log in manually, we steal the cookie)

npx brightspace-mcp@latest record-auth --save-to keychain

Opens a real browser. You log in however your tenant requires — TOTP, push notification, biometric, Yubikey, anything. As soon as you reach /d2l/home, the recorder captures your session cookies and writes them into the config under the session_cookie strategy.

This is the only viable path for tenants with auth flows that cannot be scripted (Microsoft Authenticator number-matching, FIDO2/Yubikey, fingerprint, etc.). Cookie expires in ~1 hour — re-run when auth fails.

C. Manual YAML

If you know what you need, edit the YAML directly. See auth-strategies.md.

TL;DR for picking a strategy:

• Admin gave you a Valence API token → api_token
• Email/password + TOTP authenticator (scriptable MFA) → browser
• Email/password, no MFA, server-rendered form → headless
• Tenant has OAuth client registration → oauth
• Anything else (biometric, push, USB key, complex SSO) → use option B (record-auth)

Step 4 — Verify auth works

npx brightspace-mcp@latest auth --test

Expected output:

✓ Authenticated as Jane Doe
✓ D2L API versions discovered: lp=1.59, le=1.93
✓ Session expires in 60 min

If this fails, see troubleshooting.md.

Output: timezone and language

The server formats every response in your chosen timezone and language.

output:
  tz: America/Bogota       # IANA name; default: detected from system
  locale: es-419           # en-US | es-419 | pt-BR | fr-CA; default: detected
  format: markdown         # markdown (default) | plain
  include_meta_footer: true

The setup wizard prompts for both. To change later, edit ~/.brightspace-mcp/config.yaml directly.

Locales

Locale	Language
en-US	English (US)
es-419	Español (Latinoamérica)
pt-BR	Português (Brasil)
fr-CA	Français (Canada)

To add a new locale, PR a <locale>.json to src/shared-kernel/output/i18n/catalogs/. The parity test will show missing keys.

Step 5 — Wire it into your MCP client

See clients.md for Claude Desktop, Cursor, Windsurf, and Claude Code.

Quick test from any client:

"List my Brightspace courses."

Should invoke list_my_courses and return your enrollments.

Configuration file location

OS	Path
macOS / Linux	~/.brightspace-mcp/config.yaml
Windows	%USERPROFILE%\.brightspace-mcp\config.yaml

Override with BRIGHTSPACE_CONFIG=/path/to/config.yaml or --config /path/....

Multiple profiles

You can keep multiple Brightspace tenants in one file:

default_profile: undergrad

profiles:
  undergrad:
    base_url: https://learn.school.edu
    auth: { ... }
  research:
    base_url: https://researchportal.school.edu
    auth: { ... }

Switch the default with npx brightspace-mcp@latest profile use <name> (persisted in YAML), or per-invocation with BRIGHTSPACE_PROFILE=research npx brightspace-mcp@latest serve.

List defined profiles with npx brightspace-mcp@latest profile list (or just npx brightspace-mcp@latest profile).

What the wizard skips that you may need

The setup wizard covers 80% of cases. For the remaining 20%, edit the YAML manually:

• Custom Microsoft AAD selectors → see presets.md
• Redis-backed session cache → set session.cache_backend: redis and redis.url
• Write operations → set writes.enabled: true and pass --enable-writes to serve. See writes.md.
• Fallback auth chains → auth.fallbacks: [api_token, browser] to try multiple strategies in order

Common setup checkpoints

The fastest way to verify everything: run npx brightspace-mcp@latest doctor.

$ brightspace-mcp doctor
✓ Config file (/Users/you/.brightspace-mcp/config.yaml)
✓ Config validates (1 profile(s))
✓ Profile resolves (myschool → https://learn.school.edu)
✓ D2L API versions discovered (lp=1.59, le=1.93)
✓ Authentication (Jane Doe, source: browser)
✓ list_my_courses smoke read (12 course(s) enrolled)
✓ Writes gate (enabled)

All checks passed.

A red ✗ includes the next-action hint. Manually:

✅ npx brightspace-mcp@latest config show prints config (secrets redacted) without errors. ✅ npx brightspace-mcp@latest config validate exits 0. ✅ npx brightspace-mcp@latest auth --test shows your name and API versions. ✅ npx brightspace-mcp@latest serve starts and prints Discovered D2L API versions ... to stderr.

If doctor is green, you're done. Move on to clients.md.

Web UI dashboard

Once configured, start the visual dashboard:

npx brightspace-mcp@latest ui          # opens at http://localhost:9876
npx brightspace-mcp@latest ui --open   # auto-opens your browser

The dashboard shows auth status, upcoming due dates, grades, announcements, and lets you edit config without touching YAML. It also provides cache management, audit logs, and diagnostics — all in one place.