MCP server overview
For what this means for the people using it, see Using an AI assistant.
@spelling-creator/mcp (in apps/mcp) is an MCP server for the Spelling Creator hub. It lets any MCP-capable AI assistant (Claude on the web, desktop and mobile, Claude Code, Cursor and others) author and publish lessons to the hub on a user's behalf.
The assistant writes the content; the server gives it a structured, validated path to a real lesson. It publishes through the same Worker endpoints the web app uses (/lessons, /git, /images, /lessons/:id/pulls for proposals, and /collab/:code/agent for live sessions), authenticating as the user with a Supabase token, so every lesson goes through the existing validation, ban checks and author attribution. Nothing here bypasses the normal API.
Every write is also a version. A lesson is a real git repository, and the server commits each edit the way the web editor does, so what an assistant did turns up in the lesson's History tab with the diff, under the user's name with a note that an AI assistant made it, and revertable. See Tools.
It can also fork a lesson and open a proposal against it, rather than writing to it: the assistant edits a copy, and a human reads the diff and decides. That's the only route into a lesson somebody else wrote, and the one to use when the user would rather check the assistant's work before it goes live. See Tools.
On a client that renders MCP Apps (Claude on web, desktop and mobile), some results come back as a small interface rather than as text: search_images shows the Commons candidates as pictures, the assistant stands back rather than choosing, and the one the user clicks goes into the lesson; review_proposal shows a proposal as a diff with Merge and Decline. Everywhere else the same tools answer in text.
An assistant can also take part in a live session, editing the unsaved lesson alongside the people in the room.
Ways to connect
The tool layer (src/tools.js) and API client (src/api.js) are transport-agnostic, and three entry points sit on top of them:
| Route | Entry point | Auth | Page |
|---|---|---|---|
| Remote (hosted), recommended | apps/api mounts the server at https://spellingcreator.org/mcp (Streamable HTTP) | OAuth 2.1 with a browser consent screen; no token handled by the user | Remote (hosted) mode |
.mcpb bundle for Claude Desktop | src/stdio.js, launched by Claude Desktop | Supabase refresh token entered in the install dialog | Packaging the bundle |
| Local stdio | src/stdio.js (the package's bin, spelling-creator-mcp) | login helper session file or env tokens | Local setup |
The remote route needs Cloudflare (Durable Objects), so a self-hosted Node deployment of the API doesn't serve /mcp; the stdio server works against any deployment.
Pages in this section
- Local setup: running the stdio server and pointing a client at it.
- Configuration: environment variables for the stdio server.
- Remote (hosted) mode: the OAuth route in
apps/api. - Tools: the tool surface.
- Lesson validation: what the write path enforces.
- Interactive views: the MCP Apps views.
- Live sessions: taking part in live collaboration.
- Development: code layout, tests, building views.
- Packaging the bundle: building and releasing the
.mcpb.