Skip to main contentSkip to navigation
Beta

Integration guide

How to authenticate, what data model you're reading, and where the tools live. See the full tool catalog for every tool name and its scope.

Connect in three steps

1. Point your client at the endpoint

{
  "mcpServers": {
    "studentcenter": {
      "type": "http",
      "url": "https://www.studentcenter.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

2. List what your key can reach

curl -s -X POST https://www.studentcenter.io/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools/listis the source of truth. If a tool isn't listed, your key's scope doesn't include it.

3. Call a tool

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "sc_list_games",
    "arguments": { "limit": 50 }
  }
}

A key is bound to a single institution at creation. Every tool call is scoped to that institution automatically, and passing a different institution's id in the arguments is ignored rather than honoured, so you always get your own data back.

Two independent data models

StudentCenter has two separate ways an institution can recognize a learner's progress. Reading the wrong one for your use case looks like missing data when it isn't.

Badge system

learning_paths · learning_path_games
badge_definitions · issued_badges

Points-based. A learner passes games, accumulates points against a required threshold, and earns a badge at that threshold.

Read with sc_list_learning_paths and sc_list_badge_definitions.

Credential pipeline

skill_curricula · skill_curriculum_steps
learner_skill_progress · minted_credentials

Mastery-based. Steps gate on skill mastery scores or an anchor game, and completing every step mints an on-chain credential.

Read with sc_list_curricula.

Consequence: sc_list_curriculareturning an empty array doesn't mean your data is missing, it means you're reading the other model. The two never cross-populate.

Tool map

Games

sc_list_games

Games for the institution (limit 1-200).

sc_get_game_detail

Full game config.

sc_get_game_analytics

Play, pass, and completion metrics.

sc_audit_institution_games

Config health across every game.

Credentials issued

sc_list_credentials

Minted credential rows (limit 1-500).

sc_get_credential

One credential including on-chain detail.

sc_credential_stats

Total minted, mint rate, minted this week.

sc_list_templates

Credential templates.

Learners and bulk export

sc_list_learners

Enrolled learners.

sc_get_member_stats

Membership aggregates.

sc_export_csv

CSV text export, the fastest full sync.

sc_export_csv accepts an entity of learners, credentials, templates, games, or audit_log, with a limit up to 10,000 rows per call. One call per entity is usually the cheapest way to mirror everything.

Badge system reads

sc_list_learning_paths

Paths, points required, linked badge, mapped games.

sc_get_learning_path

One path, games resolved to titles, flags dangling mappings.

sc_list_badge_definitions

Badges including level and credential template.

sc_list_issued_badges

Issued badges joined to learner email.

sc_get_learner_badge_progress

Points vs required, per learner and path.

sc_badge_system_health

Diagnostic sweep. Run this first.

Badge system writes

sc_record_game_completion

Records an attempt, recomputes path points idempotently.

sc_issue_badge

Records issuance. Refuses to double-issue or issue below threshold.

sc_upsert_learning_path

Create or update a path.

sc_upsert_badge_definition

Create or update a badge.

sc_set_path_games

Replace a path's game mapping, fully validated before writing.

sc_remove_path_game

Drop one mapping.

Every write is persisted to the audit log and visible in the institution dashboard.

Public verification endpoints (no key required)

GET /api/credentials/[id]/vc

W3C Verifiable Credentials 2.0 / Open Badges 3.0 document for one minted credential.

GET /api/credentials/status/[listId]

Revocation status list for a batch of credentials.

These are the endpoints a verifier (an employer, another platform) hits to check a credential without needing an API key at all.

Error codes

401

Unauthorized. Missing, invalid, or expired API key.

402

Payment required. This is a host-level response if the deployment itself is paused, not an error the API emits during normal use.

404

Not found. The institution, credential, or template id doesn't exist or doesn't belong to your key.

429

Rate limited. See Rate limits on the MCP page; retry after the Retry-After header.

Gotchas worth knowing

Key scope is immutable.

A key is bound to one institution at creation. Passing a different institution id is ignored, not rejected. Keys can't be re-scoped, only reissued.

Two path models.

sc_list_curricula and sc_list_learning_paths read different tables. Empty in one says nothing about the other.

Slugs are globally unique.

learning_paths.slug and badge_definitions.slug are unique across every institution, not per-institution. Prefix yours if you hit a conflict.

Rate limits.

Per key, returning 429 with Retry-After. Back off rather than retrying tightly.

API, not the database.

The MCP endpoint is the supported integration path. Keys are institution-scoped by design; direct database connections aren't offered.

Back to the tool catalog and status page