---
title: Agents and MCP
description: "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:

```bash
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](/developers/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](/developers/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](/developers/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](/developers/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:

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

A failed call returns an error result whose text is `code: message`. See [Errors](/developers/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](/developers/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:

```json
{
  "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](https://www.standardwebhooks.com/) 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`.
