VolantisSupport

Developer documentation

Connect to Nido with MCP

Bring student portraits and the evidence behind them into your assistant. Nido's Model Context Protocol (MCP) server gives a connected app access to existing records in your school and campus. With your separate approval it can also change your teaching hours, book your experience sessions, and write evidence as you.

ChatGPTAsk about your students right where you already chat.
  1. Copy Nido’s address.
  2. In ChatGPT, open Plugins and add a new one. Developer mode must be on.Open ChatGPT
  3. Paste the address, then sign in to Nido when it asks.
ClaudeBring Nido into your conversations with Claude.
  1. Copy Nido’s address.
  2. In Claude, open Settings, then Connectors, and add a custom connector.Open Claude
  3. Paste the address, then sign in to Nido when it asks.
Another assistantAdd Nido wherever it asks for an MCP server address.
Coding toolsCodex and Claude Code, from a terminal.
  • CodexRun this, then sign in to Nido.
    codex mcp add nido --url https://nido.volantisedu.com/api/mcp && codex mcp login nido
  • Claude CodeRun this, then use /mcp to sign in.
    claude mcp add --transport http nido https://nido.volantisedu.com/api/mcp
Transport
Streamable HTTP
Authentication
OAuth with PKCE (S256)
Permission scope
mcp:read, optional mcp:write

Connect your assistant

You need an activated Nido staff account with access to an active school and campus. An operator-only backoffice account cannot authorize this connection.

  1. Pick your assistant in the list above. Teachers can do the same from Settings, under Assistants.
  2. When the assistant opens Nido, sign in.
  3. Choose your school and campus if prompted, then review and approve access.

You can see what you connected, and disconnect it, under Assistants in your Nido settings.

Nido checks your membership and school access on every tool call. A connection reads only, unless it asks to make changes and you approve that on the consent screen; you can also choose “Allow reading only” there. It cannot request new analyses, and it does not use an API key.

ChatGPT, Claude, and Cursor have accepted OAuth callbacks; Codex and Claude Code use a local callback. Other hosted connectors, including Muse, need their exact callback URL approved before they can connect. Directory acceptance and a successful account connection are separate steps.

Set up ChatGPT

  1. Enable Developer mode in Settings → Security and login. Your account or workspace must permit it.
  2. Open ChatGPT Plugins, select the plus button, and add Nido with the address you copied.
  3. Use OAuth and dynamic client registration if asked. Leave the client ID and secret empty so ChatGPT can register its public client.
  4. Complete the Nido sign-in and consent flow, then add the connection to a new conversation.

Nido supports ChatGPT's stable callback through issuer identification. This lets you connect a custom MCP server; it does not mean Nido is listed in OpenAI's public directory. See OpenAI's connection guide for the current ChatGPT steps and workspace requirements.

Check the connection

Confirm that the tools below appear. Find a student you have permission to view, read their portrait, and open one of its evidence references. Check that the answer keeps the portrait's limitations and source citations.

OAuth setup for connector developers

Use the authorization-code flow with PKCE S256. Request the scope mcp:read, and add mcp:write only if your connector makes changes. The token response states the scope the teacher granted, which may be mcp:read alone. Use the server URL as the resource parameter. Clients are public OAuth clients: token_endpoint_auth_method is none, so no client secret is required.

The server publishes its connection details at these URLs:

Discovery includes the authorization, token, and dynamic client registration endpoints. Send access tokens in the HTTP Authorization: Bearer <access_token> header. Access tokens last one hour; refresh tokens last seven days. The token endpoint supports both authorization_code and refresh_token grants.

Registered client IDs have no scheduled expiry. They identify the client and do not grant access to school data. Authorization responses, including a denied request, return iss=https://nido.volantisedu.com, matching the issuer advertised in discovery (RFC 9207).

Accepted callback URLs

Registration accepts HTTP loopback URLs on localhost, 127.0.0.1, or [::1]. The port can change at authorization time; every other part must match the registered URL. Hosted and app callbacks must match one of these exact URLs:

https://chatgpt.com/connector_platform_oauth_redirect
https://claude.ai/api/mcp/auth_callback
https://claude.com/api/mcp/auth_callback
https://www.cursor.com/agents/mcp/oauth/callback
cursor://anysphere.cursor-mcp/oauth/callback

For a new hosted connector, email support@volantisedu.com with the client name and exact OAuth callback URL. Unapproved callbacks are rejected during registration.

The MCP endpoint accepts requests without an Originheader, as used by server and desktop clients. If a request includes that header, it must be https://nido.volantisedu.com. Direct browser requests from another website are rejected.

Available tools

Start by finding a student, read their portrait, then follow its evidence references back to the source. Use the IDs returned by those calls. School and campus scope come from the signed-in account; they are not tool arguments.

findStudents

Search the current roster by name. Pass query, a string of 2 to 80 characters after trimming. Returns up to eight matches with student IDs, names, and class details.

{ "query": "Alex" }

getStudentPortrait

Pass studentId, a UUID returned by student search. Reads the stored portrait with its freshness, limitations, human decisions about its claims, and supporting or challenging evidence references.

getEvidence

Pass evidenceId, a UUID from the portrait's evidence references. Reads the evidence text, date, associated students, and citations to its original source records. Each citation includes its source ID and text.

Each tool accepts only the arguments listed here. Extra fields are rejected. The name in the search example is illustrative; this page contains no school records.

Making changes

These tools appear only on a connection granted mcp:write. Each acts as the signed-in teacher, on that teacher's own records, and follows the same rules as Nido itself.

  • setTeachingWeek replaces the teacher's usual teaching times. Read the week with readTeachingWeek, then send its version as expectedVersion with every time that should remain.
  • bookExperienceSession books one free part of the teacher's own plan. listExperiences returns the plan's currentVersionId and its parts.
  • moveExperienceSession and cancelExperienceSession change a planned session the teacher organizes. Send the session's current revision as expectedRevision.
  • writeEvidence records a piece of evidence from text and student IDs. Nido marks it as written through your connector's registered name, and it cannot be edited afterwards. A teacher can write at most 30 pieces of evidence an hour this way. Send only what the teacher told you they observed.

Every change takes a requestId, a UUID you generate. Repeating a call with the same ID and the same input returns the first result without changing anything twice. A refused change is marked isError: true and carries a code such as VERSION_CONFLICT, SESSION_CHANGED, PART_SCHEDULED or TOO_MANY_EVIDENCE; read the current record again before retrying. Times are local wall-clock times with an IANA time zone.

Read the result before drawing a conclusion

Results include structuredContent and the same JSON in an MCP text content block. A tool failure is marked with isError: true and an explanation.

A portrait can be gated, stale, incomplete, or unavailable. Keep its status and limitations alongside any summary you write. An empty result does not establish that a student has no evidence. Keep supporting and challenging citations attached to the claims they describe.

MCP request bodies and each serialized result data object are limited to 128 KiB. Oversized results withhold entries and explain the limit. They do not silently cut a piece of evidence in half. Search returns at most eight matches, so narrow the name if needed.

Reads use existing records and do not start model work. A piece of evidence you write is read by Nido afterwards, as any other piece of evidence is. A model outage does not itself prevent those reads, though a portrait may still be missing or out of date.

If the connection fails

401: sign-in required
The token is missing, expired, or invalid. Refresh it or reconnect through OAuth. Opening the MCP URL directly in a browser will also return 401.
Registration rejects the callback
Check the exact redirect URL against the accepted callbacks above. Contact support to arrange a new hosted connector.
403: request origin rejected
A browser request came from another origin. Use a server or desktop MCP client; the endpoint does not accept cross-origin browser calls.
413: request too large
Keep the request body within 128 KiB. These tools need a short name query or one record ID.
503 or a tool error
The service or requested school data may be unavailable. Read the error message, check that the account still has school and campus access, and contact support if it continues.

School data and support

Tool results can contain student names and evidence written by staff. Connect only an assistant your school permits to receive those records. Access is limited to the authorized school and campus, and the source evidence stays unchanged.

For connection help, email support@volantisedu.com. Include the client name and error message. Leave access tokens and student records out of the email.

Privacy policyTerms of use