---
name: iblai-connect-ellucian-colleague
description: "Read and write Ellucian Colleague data through the Ellucian Ethos Integration (Ethos Data Model APIs, Ethos GraphQL, Data Connect) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Ellucian Colleague data, or to set up an Ellucian Colleague MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Ellucian Colleague connector for AI agents

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

Ellucian Colleague is an ERP that colleges and universities use for student and administrative records. Through Ellucian Ethos it exposes person, class and other records using the same Ethos Data Model as Banner.

## Auth & conventions

- **API:** Ellucian Ethos Integration (Ethos Data Model APIs, Ethos GraphQL, Data Connect) (Mixed). Ethos Integration proxies Ethos Data Model (EEDM) REST resources and Ethos GraphQL to Colleague and delivers change notifications from a subscriber queue at /consume. Ellucian's examples use the same calls for Colleague and Banner.
- **Base URL:** https://integrate.elluciancloud.com/api/{resource}
- **Access:** Issued by your administrator. The institution connects Colleague to Ethos Integration, creates an application, grants it resources and issues its API key. Outside developers obtain the key from the institution.
- **Auth:** API key exchanged for a JWT bearer token. Exchange the application's API key at /auth for a JWT access token and send it as Authorization: Bearer. Tokens expire after 5 minutes; an expired token returns 401 Unauthorized.
- **Limits:** Paging uses offset and limit; the maximum page size varies by resource and Ellucian's SDK reads it per resource. Ellucian warns against fetching all pages of a resource in one request. No request-rate limit was found in public docs.
- Keep Ellucian Colleague 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

- **Ethos Data Model resources** — GET /api/{resource} or /api/{resource}/{id}, e.g. persons; filter with ?filter= and page with offset and limit.
- **Ethos GraphQL** — Returns related objects in one call, e.g. a person's classes for today.
- **Change notifications** — GET /consume?lastProcessedID=&limit= reads messages from the application's subscriber queue.
- **Data Connect serverless APIs** — Institution-built Ethos Data Connect APIs; Ellucian's examples call them for account details and emergency contacts.
- **Available resources** — GET /available-resources and /appconfig list what the application is configured to use.

## Writes

- **Create or update records** — POST and PUT to /api/{resource} create or update records the application is authorized to change.
- **Delete records** — DELETE /api/{resource}/{id} on resources that support deletion. **Confirm with the user first.**
- **Ethos error records** — Create, read and delete entries in the Ethos errors service at /errors.

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

Ellucian 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`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
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

- "Look up this student's person record and preferred email in Colleague"
- "List the classes I teach today"
- "Pull new change notifications for person records since the last processed ID"
- "Show the emergency contacts on file for this student"

## Guardrails

- Colleague holds FERPA education records and may hold financial and employee data. Grant the Ethos application only the resources a task needs.
- Request the narrowest Ellucian Colleague 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

- Ethos Integration SDK documentation: https://ellucian-developer.github.io/integration-sdk-doc/csharp/index.html
- Ethos Integration API collection (Bruno): https://github.com/ellucian-developer/integration-bruno
- Ellucian Experience Ethos examples: https://github.com/ellucian-developer/experience-ethos-examples
- This connector on ibl.ai: https://ibl.ai/developer/connectors/ellucian-colleague
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections