---
name: iblai-connect-clever
description: "Read and write Clever data through the Clever API v3 (Secure Sync data API, SSO/Identity API, LMS Connect) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Clever data, or to set up a Clever MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Clever connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/clever — not part of the iblai/vibe repository. Checked against Clever's documentation on October 20, 2026; test it against your own Clever setup before you rely on it.

Clever connects K-12 district student information systems and identity providers to learning apps. It syncs districts, schools, users (students, teachers, staff, guardians), sections, terms and courses, and provides SSO.

## Auth & conventions

- **API:** Clever API v3 (Secure Sync data API, SSO/Identity API, LMS Connect) (REST). Secure Sync exposes districts, schools, users, sections, terms, courses and an events feed for delta syncs. SSO returns the signed-in user via /me. LMS Connect (v3.1) creates assignments and updates submissions in district LMSs.
- **Base URL:** https://api.clever.com/v3.0/
- **Access:** Partner or license program. Developers sign up at apps.clever.com/signup and get a sandbox district. Production data needs each district's authorization; Secure Sync, events and LMS Connect need a Clever Complete subscription.
- **Auth:** OAuth 2.0 authorization code; OpenID Connect; Bearer token (district-app token). SSO uses https://clever.com/oauth/authorize and https://clever.com/oauth/tokens; user tokens reach /me and the user's own records. District-app bearer tokens from the App Dashboard read district data.
- **Limits:** 1,200 requests per minute per bearer token; over the limit returns 429 with X-RateLimit-* headers. Lists return 100 records by default, up to 10,000 via limit, paged with starting_after/ending_before and next links (district tokens only).
- Keep Clever credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Districts and schools** — /v3.0/districts and /schools/{id} return district and school details.
- **Users** — /v3.0/users returns students, teachers, staff and guardian contacts; multi-role users share one Clever ID.
- **Sections** — /v3.0/sections returns classes that connect users to curriculum (Secure Sync district tokens).
- **Terms and courses** — Districts contain terms and courses; sections link to both.
- **Events** — GET /v3.0/events: created, updated and deleted changes for delta syncs; kept 30 days (Secure Sync only).
- **Signed-in user (/me)** — Returns token type, Clever user ID and district ID after SSO.

## Writes

- **Assignments** — POST/PATCH /v3.1/sections/{section_id}/assignments creates or updates an assignment in the district LMS.
- **Assignment deletion** — DELETE /v3.1/sections/{section_id}/assignments/{assignment_id}. **Confirm with the user first.**
- **Submissions (grades)** — PATCH .../assignments/{assignment_id}/submissions/{user_id} updates a student's submission and grade. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Clever did not publish an MCP server of its own when this skill was checked. Host a small MCP server that wraps the calls above, then register it below.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Clever supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "List every section a teacher is rostered to in our Clever sandbox district"
- "Pull all Clever events since yesterday and tell me which students changed schools"
- "Find the guardian contacts linked to this student's Clever ID"
- "Create a 'Chapter 4 quiz' assignment in each of my Clever sections and post the scores"

## Guardrails

- Student education records protected by FERPA: student and staff identities, demographics, class rosters, guardian contacts and grades sent back to the LMS.
- Request the narrowest Clever scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Clever API Overview: https://dev.clever.com/docs/api-overview
- Clever Secure Sync Quickstart Guide: https://dev.clever.com/docs/secure-sync-rostering
- Clever OAuth Implementation: https://dev.clever.com/docs/oauth-implementation
- This connector on ibl.ai: https://ibl.ai/developer/connectors/clever
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections