ChatGPT plugin walkthrough

1. Install and connect the plugin

The Fluid Recall plugin is already uploaded to ChatGPT's personal library. Install and enable it from there. The package is a connection path, not a second server: it points ChatGPT at the same stateless Streamable HTTP MCP door every other agent uses, POST https://fluidrecall.com/mcp (POST /api/mcp is the same door). That door answers initialize and tools/list without a bearer.

Nothing is duplicated behind the plugin. The MCP tools call the same deterministic service the JSON and Markdown doors call, and no second scheduler exists. The FAQ covers how agents connect in general; the Muse custom connector page covers the non-plugin path Muse uses today.

2. Link the account with OAuth 2.1

When ChatGPT first needs credentials it discovers the authorization server itself. GET /.well-known/oauth-protected-resource tells it which server protects https://fluidrecall.com/mcp, and GET /.well-known/oauth-authorization-server lists the authorization and token endpoints plus the supported PKCE method.

ChatGPT then opens https://fluidrecall.com/oauth/authorize, the consent page. On that page the person either pastes an existing personal API token or creates an account. Either path binds the new grant to the existing Fluid Recall user. There is no second tenant, and no website signup beyond that one page.

PKCE is S256 only. ChatGPT sends code_challenge with code_challenge_method=S256, the person approves, and ChatGPT exchanges the one-time code plus the code_verifier at POST /oauth/token for a Bearer token. Codes and tokens are stored hashed at rest.

Every MCP call after that sends Authorization: Bearer <token>. A wrong, missing, or revoked token is 401. This consent page is the only interactive page on the site. There is no study screen to land on afterward.

3. Bootstrap an account and start a session

Example prompt: “Start a Fluid Recall study session for me.”

If no token exists yet, ChatGPT calls createAccount (alias bootstrapAccount) with no Authorization header and an optional short label. The response mints a personal token. startSession does the same when called with no bearer, and returns the due queue in the same call. The token is the tenant: no tool accepts a caller-supplied user id, and one token owns that person's decks, cards, reviews, mailboxes, and events.

startSession and nextDue return the due queue (ordered learning, then review, then new) plus the first item and the deckNote/cardNote coaching notes. The queue is prompts only. listDue never returns answers, and neither does the session bootstrap. After linking, get_profile is the one read that describes the tenant back: its label and settings.

4. Drill one card: reveal, grade, trust the returned dueAt

Example prompt: “Quiz me on my next due card.”

ChatGPT says one prompt out loud and waits for the person's attempt in the chat. Only then does it call revealCard for that cardId. It is the only drill call that returns an answer, and only after an attempt. It never folds the reveal into the queue and never fetches every answer up front.

ChatGPT compares the attempt with the revealed answer, picks one rating (again, hard, good, or easy) and calls gradeAndNext with a fresh idempotencyKey (8–200 characters). That records the review and returns the next prompt plus the new dueAt. The same key with a different body is a 409, and recordReview is the only call that moves dueAt.

Trust the returned dueAt and schedule from it. A delay of minutes is normal for a new or missed card. A mistaken grade is fixed with undoReview, which restores the prior schedule instead of retiring or recreating the card.

5. Make a deck: newCardsPerDay is chosen, not defaulted

Example prompt: “Make a deck for the five steps of the cardiac cycle.”

Before creating anything, ChatGPT chooses newCardsPerDay (the number of brand-new cards introduced per study day) with the person. There is no default of 20. It asks how long the person will really study this deck each day and how dense the cards are.

If the person has a deadline, previewDeadlinePlan returns a recommendedNewCardsPerDay floor to weigh against that answer. Then ChatGPT calls createDeck with the name and the agreed newCardsPerDay, and addCards with 1–100 prompt/answer pairs in one all-or-nothing call. New cards are eligible immediately, but the daily queue still introduces only that deck's newCardsPerDay.

6. Email: headers first, sends only after a clear yes

Example prompt: “Do I have any new mail?”

listMailboxes lists the mailboxes the token owns on fluidrecall.com, listMailMessages returns headers only: from, to, subject, dates, and thread. No bodies come with the list.

getMailMessage opens one message including its body, and ChatGPT should ask the person before opening mail they did not ask about. sendMailMessage and replyMailMessage always require explicit human confirmation of the recipient, subject, and body first: draft, show, get a clear yes, then send.

Honest limitations

• No study UI. fluidrecall.com is a landing page, a health check, and the public contract. There is no deck browser and no study screen; the person studies in the chat with ChatGPT as the coach. The home page has the starter prompt for any agent.
• listDue never returns answers. revealCard is the only answer path, and only after an attempt.
• The scheduler is deterministic and non-AI. A rating of again, hard, good, or easy goes in; a dueAt comes out. No model sits in the scheduling loop.
• Email sends and replies always need explicit human confirmation. Headers come before bodies, and getMailMessage is asked for.
• MCP Events are webhook-only on the same /mcp door: events/list, events/subscribe, and events/unsubscribe over three events: email.message.received, review.recorded, and email.message.sent. There is no poll, no push, and no gap or terminated control notifications.
• The personal API token is the tenant, and nothing is locked in. An authorized agent can export the person's full record (decks, cards, schedules, reviews) so they can take it and leave.

What a reviewer can verify without the video

None of this needs a recording. Against the live service you can check that the MCP door answers initialize and tools/list, that both well-known OAuth documents return JSON over HTTPS, that the consent page accepts a pasted token or a new account, that an exchange without S256 is rejected at /oauth/token, and that a bad bearer is 401. The endpoint table and the submission checklist behind this walkthrough ship in the plugin's own documentation package.

Elsewhere on this site

Start at the home page, read the FAQ, see the Muse connector, or review the privacy and terms pages.