---
name: iblai-connect-handshake
description: "Read and write Handshake data through the Handshake EDU API and Importer and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Handshake data, or to set up a Handshake MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Handshake connector for AI agents

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

Handshake is a career network connecting students, employers and university career centers. It holds student profiles, jobs and postings, applications, appointments, career fairs, events, employer contacts and first-destination survey responses.

## Auth & conventions

- **API:** Handshake EDU API and Importer (Mixed). The EDU API exposes a school's Handshake data as tables such as Students, Applications, Appointments, Career fairs, Jobs, Employers and First destination responses. The Importer loads CSV student data via S3.
- **Access:** Issued by your administrator. Handshake grants API access only to Career Services partner schools, on request through the school's Handshake Relationship Manager, and offers it 'as-is'. Importer access and AWS credentials come from Handshake Support.
- **Auth:** AWS access key and secret (Importer S3 upload). EDU API authentication is documented only behind the login-gated developers.joinhandshake.com. For the Importer, Support issues AWS credentials and a school-specific, write-only S3 path in us-east-1.
- Keep Handshake 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

- **Students** — Students table (name, major and similar); student_id links to applications, appointments and attendance.
- **Applications** — Student applications to jobs: job_id, employer_id, status, withdrawn, created_at, updated_at.
- **Appointments** — Career center appointments: student_id, check-in, start and end time, type, staff member, notes.
- **Career fairs and attendance** — Career fairs, sessions, student attendance and employer engagement records.
- **Jobs, postings and employers** — Jobs, postings, employers, industries and employer labels for the institution.
- **First destination responses** — Outcomes survey responses linked to first_destination_survey_id.

## Writes

- **Student records (Importer)** — Upload a UTF-8 CSV to the school's S3 folder; the Importer creates or updates students. Handshake states an import cannot be deleted. **Confirm with the user first.**

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

Handshake 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

- "How many seniors had a career center appointment this semester?"
- "List students who checked in at the fall career fair but have not applied to any job."
- "Summarize first-destination survey outcomes by major for last year's graduates."
- "Show which employers engaged most with our fall events."

## Guardrails

- Student profiles, appointments, applications and outcomes data a school shares are FERPA-protected education records.
- Request the narrowest Handshake 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.
- Page through large result sets and back off on rate-limit responses instead of retrying in a loop.

## References

- Handshake: University Technical Support Guidelines: https://support.joinhandshake.com/hc/en-us/articles/360000869147-University-Technical-Support-Guidelines-and-Resources
- Handshake EDU API endpoint definitions: https://support.joinhandshake.com/hc/en-us/articles/35762729693719-EDU-API-Endpoint-Definitions
- Handshake Importer: automating your student sync: https://support.joinhandshake.com/hc/en-us/articles/360012323314-Importer-Automating-Your-Student-Sync
- This connector on ibl.ai: https://ibl.ai/developer/connectors/handshake
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections