Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Agents and MCP

Connect AI agents to Soljio through the MCP server: how agents sign in, which tools, views, and events exist, and how tool approval and read-only hints work.

Soljio runs a Model Context Protocol (MCP) server so AI agents, such as ChatGPT or Claude, can work with a school’s data without anyone writing integration code. A school owner or admin approves the agent through OAuth and chooses what it may do. After that, the agent calls tools that run the same operations as the HTTP API.

Server address https://soljio.com/mcp
Transport Streamable HTTP
Sign-in OAuth 2.0 with PKCE, or a device code
Tools One for each operation in the contract, 200 in total
Views Schedule, class roster, and change preview
Events Four, delivered to a webhook

Connect a client

Add https://soljio.com/mcp as a remote MCP server in your agent. In an agent that supports connectors, that is a custom connector. In Claude Code, for example:

claude mcp add --transport http soljio https://soljio.com/mcp

The first request is answered with 401 and a WWW-Authenticate challenge that points to the server’s OAuth metadata. A compliant client follows it, sends the person to Soljio to approve access, and continues on its own. What the person sees is described in Connect an agent.

An agent that cannot open a browser can use the device flow instead. It asks for a code, shows the person a sign-in link and a short code, and polls until the person approves.

How sign-in works

The OAuth server publishes standard discovery documents on soljio.com:

  • /.well-known/oauth-protected-resource
  • /.well-known/oauth-authorization-server

Its endpoints live under https://soljio.com/mcp/oauth/:

Endpoint Purpose
register Dynamic client registration for public clients (no client secret)
authorize Authorization code flow. PKCE with S256 is required
token Exchange a code or refresh token, or poll a device code
device Start the device flow. The public client ID mcp-agent can be used
revoke Revoke a token

Access tokens last one hour. A refresh token lasts 30 days. Tokens from the device flow have no refresh token, so an agent starts a new device request when its token expires.

An approved agent connection itself lasts up to one year. After that it shows as Expired and the person must connect the agent again.

What an agent can do

An agent connection acts for the person who approved it, in the one school they chose.

  • Scopes. The approving person chooses the access in areas (None, Read, or Write) on the approval page. The result is a list of the same scopes service tokens use. See Scopes.
  • Never more than the person’s role. On every call, an agent’s scopes are intersected with what the person’s current role may grant. An admin who approves an agent cannot give it owner-only scopes, and if the person stops being an owner or admin, the connection is paused and authorizes nothing until it is connected again.
  • Tool list. The server lists a tool only when the connection holds that tool’s first required scope. A call is still checked against every scope the operation needs, so a listed tool can be refused with an error.
  • No secret to rotate. Agent connections have no static secret. Disconnecting an agent in Settings ends its access immediately and revokes its OAuth tokens. Agent connections do not count toward the limit of 25 service tokens.
  • Same checks as the API. A tool call goes through the same scope checks, school isolation, idempotency handling, rate limits, and audit log as an HTTP request. See Rate limits.

Tools

The server builds one tool for every operation in the OpenAPI contract that is marked for MCP use. The tool name is the operation’s operationId, such as list_programs, get_program, search_programs, create_program, or get_job. The arguments come from the operation’s request schema, so the tools and the HTTP API cannot drift apart.

  • Resource reads take the same inputs as the HTTP reads: limit and cursor for lists and id for a single record.
  • Commands take an optional idempotency_key argument. Pass the same key to retry a call safely. If it is omitted, the server generates a new random key for the call, so the retry is not protected. See Idempotency.
  • A command whose body exceeds its byte limit is refused before it runs.
  • HEAD operations are not exposed.

A successful call returns the result as text and as structured content. For reads that page, the result includes next_cursor where the operation has one:

{ "data": [], "next_cursor": null }

A failed call returns an error result whose text is code: message. See Errors.

The server also sends these instructions to the client: Tools act on one swim school with the access its owner or admin granted. Preview tools show what a change will do without saving it; call them before the matching apply tool. Read job tools to follow asynchronous work.

Tool approval policy

Each operation in the contract carries an x-mcp extension with three fields. The server reads them to decide how a tool is described to the agent and to the person using it.

Field Values Effect
expose true or false Whether the operation becomes a tool. Every query, command, and resource read is exposed. HEAD variants are not
readOnly true or false Sets the tool’s annotations. Read-only tools get readOnlyHint: true and idempotentHint: true. Others get destructiveHint: true. All tools get openWorldHint: false
approval none or required When required, the tool’s description adds: This reaches families or changes what they owe; confirm with the user before calling.

In the current contract, 93 tools are read-only, and 107 change data. Of those 107, 95 require approval. The other 12 are the preview tools: they run without confirmation because they save nothing.

Tool type Annotated as Asks the person first?
Reads and queries Read-only No
Preview tools (preview_...) Not read-only No. They roll back everything they do
Apply and other write commands Not read-only Yes. The description tells the agent to confirm, and clients that honor the destructive hint ask the person

How a client acts on the hints is up to the client. Soljio supplies the annotations and the instruction text; it does not make a person click through every call. For schedule changes, the apply step also needs the reviewed approval token from a preview, which proves the change matches what was previewed but does not prove a person agreed. See Previews and approvals.

Views

In a client that supports MCP Apps, such as ChatGPT or Claude, the server can show the person a view beside the conversation instead of a block of text. A client without view support loses nothing: every tool still returns its full result as text and structured content.

View Shown by What the person sees
Schedule show_schedule The classes in a date range, grouped by day, with enrollment against capacity
Class roster show_class_roster One class date’s roster: each student with attendance, enrollment and payment status, and allergy or medical notes
Change preview Any preview_... tool What a change will do, before the agent applies it
  • show_schedule takes the same arguments and returns the same data as get_schedule_week. show_class_roster does the same for get_session_roster. Each is listed only when the connection has the read behind it. An agent calls the plain read instead when the person does not need to see the result.
  • A preview tool opens the change preview view when the connection also has the tool that applies the change. The agent makes no extra call.
  • A view draws only the result of the tool call that opened it and loads nothing else, so it never shows more than the connection may read. Views follow the client’s light or dark theme.

Events

A client can subscribe to events and be told when something happens in a school, instead of polling. The server implements MCP Events with events/list, events/subscribe, and events/unsubscribe. MCP Events is a draft protocol, so its wire format may still change. Events are delivered to a webhook only.

Event Sent when Scope needed
enrollment.created A student is enrolled in or waitlisted for a class enrollments.read
payment.failed A card payment for an enrollment is declined payments.read
conversation.message_received A family sends the school a message communications.read
job.completed Asynchronous work the same connection started finishes or fails None

events/list returns only the events the connection may subscribe to. Events take no arguments. A CSV import sends no events.

A delivery names the record that changed and carries no student or message content. The agent reads the record with a tool, which applies the usual scope checks:

{
  "eventId": "...",
  "name": "enrollment.created",
  "timestamp": "2026-11-14T02:00:00.000Z",
  "cursor": null,
  "data": {
    "enrollment_id": "...",
    "offering_id": "...",
    "session_id": null,
    "status": "..."
  }
}
Event Fields in data Read the record with Scope that tool needs
enrollment.created enrollment_id, offering_id, session_id (may be null), status search_enrollments invoices.read
payment.failed enrollment_id, payment_id (may be null) list_enrollment_payments payments.read
conversation.message_received channel, conversation_id, message_id get_conversation communications.messages.read
job.completed job_id, operation, status (complete or failed) get_job organization.read

The scope that lets a connection hear an event is not always the scope its read tool needs. Ask for both when you connect the agent, or the agent is told about a record it cannot read.

How subscriptions and deliveries behave:

  • Callback proof. The callback must be an HTTPS address. A subscription becomes active only after the callback echoes a signed, single-use challenge: Soljio posts { "challenge": "...", "type": "verification" } and expects a JSON response that contains the same challenge value. A callback the same connection proved in the last hour is not challenged again.
  • Signatures. Every request to a callback is signed as Standard Webhooks with the subscription’s secret, in the webhook-id, webhook-timestamp, and webhook-signature headers. The secret has the form whsec_.... An X-MCP-Subscription-Id header names the subscription.
  • Retries. A delivery is attempted up to six times over about five hours. A callback that answers 410 Gone ends its subscription. Redirects are not followed, and a callback has 10 seconds to answer.
  • Access. What a connection may hear is checked when it subscribes and again before every delivery, with the same role-narrowed scopes as tool calls. Disconnecting an agent deletes its subscriptions.
  • Limits. A subscription lasts at most 24 hours unless the client refreshes it. A connection holds at most 25 subscriptions and can make 20 subscribe attempts a minute.

The public documentation server

A second MCP server at https://soljio.com/mcp/docs lets an agent learn the API before it has any access. It takes no credentials and never touches school data.

Tool What it does
list_api_operations Lists operations with operationId, method, path, summary, and tags. An optional query matches text case-insensitively
get_api_operation Returns one operation’s full contract by exact operationId

It also serves the OpenAPI contract and a product overview as resources, and its instructions point agents at this guide. It is stateless: only POST is accepted, and GET and DELETE return 405 with Allow: POST. Its server card is at https://soljio.com/mcp/server-card and it is listed in https://soljio.com/.well-known/ard.json.

Troubleshooting

  • The client keeps asking to sign in. The access token was refused. The connection may have been disconnected, expired, or paused because the person who approved it is no longer an owner or admin. Connect the agent again.
  • A tool is missing. The connection does not hold that tool’s first required scope. Connect the agent again with more access.
  • A tool is listed but fails with forbidden. The operation needs more than one scope, and the connection holds only some of them.
  • unauthorized: This agent connection has ended. Connect the agent again. An owner or admin disconnected the agent. Approve it again.
  • show_schedule or show_class_roster is missing. The connection cannot call get_schedule_week or get_session_roster. Connect the agent again with read access to that area.
  • A subscription never becomes active. The callback did not echo the challenge, is not reachable over HTTPS from the public internet, or answered with a redirect.
  • rate_limited. The connection or the school is over its request budget. Wait a few seconds and retry with the same idempotency_key.

Was this page helpful?