Mosyn connector documentation

Mosyn is an Android study app. This connector lets Claude or ChatGPT build your study sets for you: you paste a list into the assistant you already have open, and the cards appear on your phone while you watch. The assistant can also write you a custom study game for that material, in code, which loads on the phone as it is written.

This page covers setup, everyday use, the full tool surface, limits, troubleshooting, data deletion, and how authentication works. Questions not answered here: mosyn@lycatra.com.

Before you connect

The connector and Android app use the same Mosyn account. You can connect first and install the app later; sign in with the same Google identity or email address to see the sets the assistant created. The app is free; the connector costs nothing to add.

Setup

Claude

Open Settings → Connectors in Claude (web, desktop, or mobile).
Choose Add custom connector and paste the server URL shown on your Mosyn Settings screen under Connected assistants.
Claude opens Mosyn's browser sign-in. Continue with Google or request a one-time email link, then review and approve the consent page.
The connector appears in your tool list. Nothing else to configure.

ChatGPT

Custom connectors require a paid plan with developer mode enabled (Settings → Connectors → Advanced).
Add a connector, paste the same server URL, and choose OAuth when asked how it authenticates.
Approve the same consent page described above.

Everyday use

Ask in plain language. The assistant decides which tools to call.

"Here are the 30 people in my cohort — make me a set with their photos." The assistant finds a picture for each name with its own web search, attaches them, and adds the cards.
"Add the irregular verbs from chapter 4 to my French set."
"Build me a game for the anatomy set — clicking the right region on a diagram." The assistant writes the code and it appears on your phone.
"That game is broken." The assistant reads the runtime errors your phone reported and fixes its own code.

Everything a tool writes syncs to the phone immediately — there is no import step and no file.

Tools

The connector exposes 16 tools. Read-only tools are marked; the two destructive ones require an explicit confirmation and say so when called without it.

Tool	What it does
`list_sets` (read-only)	Lists your study sets.
`get_set` (read-only)	Reads one set, optionally with its cards.
`create_set`	Creates a set.
`update_set`	Renames a set or changes its description.
`delete_set` (destructive)	Deletes a set and its cards. Requires `confirm: true`.
`add_cards`	Adds up to 50 cards per call.
`update_card`	Rewrites one side of a card.
`delete_cards` (destructive)	Deletes specific cards. Requires `confirm: true`.
`reorder_cards`	Sets the card order for a set.
`attach_media`	Fetches images or audio from URLs the assistant found and stores them.
`create_experience`	Creates a custom study experience from a file bundle.
`update_experience_files`	Edits an experience; the phone reloads it live.
`get_experience` (read-only)	Reads an experience and its files.
`publish_experience`	Promotes a draft experience to published.
`get_component_library_docs` (read-only)	Serves the Mosyn Kit documentation the assistant builds experiences against.
`get_device_feedback` (read-only)	Returns runtime errors your phone reported, so the assistant can fix its own code.

Limits

Per-call limits, enforced by the server. When a call exceeds one, the error states the limit and what to do instead, so the assistant can correct itself without you intervening.

50 cards per add_cards call, and 10 URLs per attach_media call.
2000 characters per card side.
20 files per experience, 256 KB per file, 1 MB per bundle.

Account limits depend on your plan. The free plan includes 3 sets, 100 cards, 25 MB of media, and 1 custom experience. When you reach one, the assistant is told the limit has been reached and tells you; it is never shown a price or a purchase link, and neither Claude nor ChatGPT can make a purchase. Plans are managed in the Android app.

Authentication

The connector uses OAuth 2.1 with PKCE and dynamic client registration. Approving the consent page creates a grant scoped to your account and to that assistant. Mosyn never sees your Google password; email links are single-use; and the assistant never receives either provider's credentials.

Every request is scoped to the account that granted it: one grant cannot read or write another account's data. Grants are listed in the app under Settings → Connected assistants and can be revoked there individually. Revocation is immediate — an assistant holding a revoked grant is refused on its next call, including mid-conversation.

Troubleshooting

Symptom	What it means
The assistant says it cannot find your sets, or the tool list is empty.	The grant was revoked or expired. Remove the connector in the assistant and add it again.
The consent page will not accept your sign-in.	Start the connection again so Mosyn can create a fresh browser sign-in. Complete Google or email authentication, then approve the consent page before the 10-minute authorization expires.
Cards were created but the phone does not show them.	The phone applies changes when it is online and foregrounded. Open the app; it catches up from its last position. Nothing is lost by being offline.
An image failed to attach.	The URL was a web page rather than an image file. The error tells the assistant to find the direct image URL and retry; asking it to try again is usually enough.
A custom experience shows an error on the phone.	The phone keeps the previous working version and reports the error. Ask the assistant to check `get_device_feedback` — it can read the failure and fix its own code.

Security

Custom experiences are code written by an assistant, so they run in a sandbox with no network access at all: no fetch, no sockets, no remote fonts or images, and no navigation off their own origin. Each experience gets its own isolated origin and can only read the media belonging to its own set. This is enforced by the app and covered by an adversarial test suite that runs against a real device.

Session tokens are opaque and stored only as hashes. Media is served over per-user signed URLs that expire. Study history stays on your phone: a connected assistant can write cards, and cannot see how you are doing.

Deleting your data

Delete individual sets or cards by asking the assistant, or in the app. To delete your account and everything in it, use Settings → Delete account in the Android app; this removes your sets, cards, media, experiences, and grants. You can also request deletion by writing to mosyn@lycatra.com from the address on your account.