Assistant Connector

Reading Journey · Updated 3 November 2026

Overview

The Reading Journey connector lets an AI assistant you connect read and manage your own Reading Journey library: books, reading status and dates, ratings and reviews, notes and journal entries, Next Up, Top Four, collections and reading goals. Changes reach the Reading Journey apps through ordinary sync. A free Reading Journey account is enough; the connector sells nothing and takes no payments. It never reads other readers' data.

Endpoint: https://mcp.readingjourney.app (MCP over streamable HTTP, stateless, tools only). /mcp on the same host serves the same server.
Authorization: OAuth 2.1 authorization code flow with PKCE (S256), dynamic client registration at /oauth/register, metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. Access tokens last one hour; refresh tokens rotate and last 60 days. Reconnecting an assistant replaces its earlier grant.
Sign-in: the reader signs in with email and password, Apple or Google, or creates an account, then approves access on a consent page. Removing the connector in the assistant, or deleting the Reading Journey account, revokes access.

Scopes

Scope	Grants
`mcp`	Read and change the library: books, statuses, dates, ratings, Next Up, Top Four, collections and goals.
`library:private`	Read and change notes, review text and journal entries, including progress and place names; add, replace or remove photos. Places are names only: the connector never accepts or returns coordinates, and photos are never returned.

Tools

34 tools: 8 read, 18 write and 8 sensitive write. Read tools change nothing. Write tools change only the connected reader's library. Sensitive writes permanently delete data or send a message outside the library. Tools that delete or replace data, and feedback, take confirmed: true only after the reader approves the exact action; removing a book that has reading history, notes or photos is refused without it. Write tools accept an optional requestId: a retry with the same id within 24 hours returns the first result instead of repeating the change. A ? marks an optional input.

Tool	Class	What it does	Inputs	Scope
`send_feedback` Send Feedback	Sensitive write	Send reader-approved feedback and up to three attachments to the Reading Journey team through Arejay in Slack. Requires the reader’s approval of the exact message and files. Attach images, PDFs or UTF-8 text as base64 (2 MiB per file, 4 MiB total). Limited to 3 submissions per account per hour and 10 per day, plus a shared cap. Always reuse requestId when retrying; do not resubmit uncertain delivery with a new id. The report carries the reader’s account id so the team can identify them.	`message` string `category`? "bug" \| "feature_request" \| "other" `confirmed` true `requestId` string `attachments`? array of object	mcp
`list_books` List Books	Read	List books in the reader’s library, newest additions first. Filter by status, collection or a title/author search. Returns id, title, authors, status, rating, Next Up flag and collection names.	`status`? "want_to_read" \| "reading" \| "paused" \| "finished" \| "did_not_finish" `collectionId`? string `query`? string `limit`? number `cursor`? string	mcp
`get_book` Get Book	Read	One book with its edition details, reads (status, start and finish dates, format, snooze date, rating, journal entry count), collections, Next Up and Top Four positions. With access to private data (privateAccess: true) it also returns the reader’s note, each read’s review and the current reading progress, where reachedEnd says the logged position is the end of the book.	`bookId` string	mcp
`list_journal_entries` List Journal Entries	Read	The reader’s journal entries, newest first: text (cut at 2,000 characters, see textTruncated; get_journal_entry returns all of it), reactions, place name, minutes read, the progress logged with the entry and whether it has a photo. Filter by book, read or a date range. Never returns coordinates or photos.	`bookId`? string `readId`? string `since`? string `until`? string `limit`? number `cursor`? string	mcp + library:private
`get_journal_entry` Get Journal Entry	Read	One journal entry with its full text, reactions, place name, minutes read, progress and whether it has a photo.	`entryId` string	mcp + library:private
`attach_journal_photo` Attach Journal Photo	Write	Add a photo to a journal entry: an image the reader gave you or chose, from a url (preferred) or dataBase64. You cannot see stored photos. An entry that already has one is refused with photo_exists; to replace it, tell the reader the current photo, which you cannot see, will be replaced, and only if they agree pass replaceExisting: true. Always pass confirmed: true only after the reader agreed.	`entryId` string `url`? string `dataBase64`? string `replaceExisting`? boolean `confirmed` true `requestId`? string	mcp + library:private
`remove_journal_photo` Remove Journal Photo	Sensitive write	Remove the photo from a journal entry; the entry stays. You cannot see the photo, so tell the reader which entry’s photo will be removed and pass confirmed: true only after they agreed.	`entryId` string `confirmed` true `requestId`? string	mcp + library:private
`set_cover_photo` Set Cover Photo	Write	Set the reader’s own cover photo for a book: an image the reader gave you or chose, from a url (preferred) or dataBase64. You cannot see stored photos. It replaces an edition cover add_book stored without asking; a cover photo the reader set is refused with photo_exists, and replacing it needs replaceExisting: true after the reader agreed. Always pass confirmed: true only after the reader agreed.	`bookId` string `url`? string `dataBase64`? string `replaceExisting`? boolean `confirmed` true `requestId`? string	mcp + library:private
`remove_cover_photo` Remove Cover Photo	Sensitive write	Remove the stored cover photo of a book; the app then shows the edition cover from its address, if it has one. You cannot see the photo, so confirm with the reader and pass confirmed: true only after they agreed.	`bookId` string `confirmed` true `requestId`? string	mcp + library:private
`get_top_four` Get Top Four	Read	The reader’s Top Four favorite books by position, 1 to 4. Empty positions are left out.	none	mcp
`set_top_four` Set Top Four	Write	Set the reader’s Top Four favorite books: the whole new list, a position from 1 to 4 for each book (gaps allowed). Books left out leave Top Four but stay in the library. Read it with get_top_four first, confirm the new list with the reader, then pass confirmed: true.	`slots` array of object `confirmed` true `requestId`? string	mcp
`list_goals` List Reading Goals	Read	The reader’s reading goals: kind (books, pages or minutes per day, week, month or year), target, the first and last day of the current period in the reader’s time zone, and whether the goal was already reached in it. Progress toward a goal is shown only in the app.	none	mcp
`add_journal_entry` Add Journal Entry	Write	Add a journal entry to a book: text, reactions, a place, minutes read, reading progress or a photo, at least one of them. Also logs progress: "I’m on page 120" is progress { value: 120, unit: "pages" }. It goes on the book’s current read (or readId); a book with no read gets a Want to Read read, and logging never changes the status. Reaching the end does not finish the book: when reachedEnd is true, ask the reader whether to mark it finished with set_status.	`bookId` string `readId`? string `text`? string `reactions`? array of string `date`? string `timeZone`? string `progress`? object `minutesRead`? number `location`? object `photo`? object `requestId`? string	mcp + library:private
`update_journal_entry` Update Journal Entry	Write	Change a journal entry. Only the fields given change; null clears the text, reactions, minutes read or place. Progress can be changed but not removed.	`entryId` string `text`? string or null `reactions`? array of string or null `date`? string `progress`? object `minutesRead`? number or null `location`? object or null `requestId`? string	mcp + library:private
`delete_journal_entry` Delete Journal Entry	Sensitive write	Delete a journal entry, with the progress logged with it and its photo, if any. Confirm with the reader first, then pass confirmed: true.	`entryId` string `confirmed` true `requestId`? string	mcp + library:private
`set_goal` Set Reading Goal	Write	Create a reading goal, change its target, or turn an existing goal into another kind (replaceType names the goal to change). One goal per kind: books, pages or minutes per day, week, month or year; there is no minutes per year, and pages per year can only be changed, not created. A minutes goal cannot exceed the minutes in its period. Daily goals and minutes goals appear in Reading Journey 2.4 or later. A "read so far" correction is made only in the app.	`type` "pages_per_day" \| "pages_per_week" \| "pages_per_month" \| "pages_per_year" \| "books_per_day" \| "books_per_week" \| "books_per_month" \| "books_per_year" \| "minutes_per_day" \| "minutes_per_week" \| "minutes_per_month" `target` number `replaceType`? "pages_per_day" \| "pages_per_week" \| "pages_per_month" \| "pages_per_year" \| "books_per_day" \| "books_per_week" \| "books_per_month" \| "books_per_year" \| "minutes_per_day" \| "minutes_per_week" \| "minutes_per_month" `timeZone`? string `requestId`? string	mcp
`delete_goal` Delete Reading Goal	Sensitive write	Delete the reader’s goal of one kind. Its history stays. Confirm with the reader first, then pass confirmed: true.	`type` "pages_per_day" \| "pages_per_week" \| "pages_per_month" \| "pages_per_year" \| "books_per_day" \| "books_per_week" \| "books_per_month" \| "books_per_year" \| "minutes_per_day" \| "minutes_per_week" \| "minutes_per_month" `confirmed` true `timeZone`? string `requestId`? string	mcp
`list_collections` List Collections	Read	The reader’s collections (their own shelves) with id, name and book count.	none	mcp
`get_next_up` Get Next Up	Read	The books the reader plans to read next, in order (up to five).	none	mcp
`add_book` Add Book	Write	Add a book as Want to Read by default. Take details from the publisher’s website for the exact language and edition, with its blurb copied verbatim as synopsis, and always pass coverUrl: the exact edition’s cover if you can find it, otherwise another edition’s cover of the same book. Supply sourceUrl and languageCode; coverUrl is downloaded and uploaded to private media storage before adding. A cover upload failure adds no book. A duplicate (same ISBN or title/authors) returns the existing book and preserves its metadata/status; collectionIds still apply, but status/nextUp are listed as ignored (use set_status/set_next_up).	`title` string `authors` array of string `isbn13`? string `pageCount`? number `publicationYear`? number `languageCode`? string `publisher`? string `synopsis`? string `sourceUrl`? string `coverUrl`? string `status`? "want_to_read" \| "reading" \| "paused" \| "finished" \| "did_not_finish" `collectionIds`? array of string `nextUp`? boolean `requestId`? string	mcp
`set_status` Set Reading Status	Write	Start, pause, finish or abandon a book, or mark it Want to Read. Starting a finished book again begins a reread and keeps the earlier read. Changing status removes the book from Next Up. A pause can take until, the day the snooze ends and the book returns to reading.	`bookId` string `status` "want_to_read" \| "reading" \| "paused" \| "finished" \| "did_not_finish" `date`? string `until`? string `timeZone`? string `requestId`? string	mcp
`rate_book` Rate Book	Write	Rate a book from 0.25 to 5 stars in quarter steps, write or change its review, or both. An omitted field is kept; null clears it, and clearing both removes the rating. It belongs to the book’s current read, or to readId for an earlier read.	`bookId` string `readId`? string `rating`? number or null `review`? string or null `requestId`? string	mcp; library:private for review text
`update_read` Update Read	Write	Change a read’s start date, finish date (finished or abandoned reads only) or format. null makes a date unknown. A start after the finish moves the finish to it, and a finish before the start moves the start, as the app does; the answer says so.	`readId` string `startedAt`? string or null `finishedAt`? string or null `format`? "print" \| "ebook" \| "audio" or null `timeZone`? string `requestId`? string	mcp
`delete_read` Delete Read	Sensitive write	Delete one read of a book with its journal entries, progress and rating. The book’s only read cannot be deleted. Confirm with the reader first, then pass confirmed: true.	`readId` string `confirmed` true `requestId`? string	mcp
`set_next_up` Add to Next Up	Write	Put a book the reader has not started in Next Up, optionally at a position (1 is next). Next Up holds five books; when it is full, name a book to replace.	`bookId` string `position`? number `replaceBookId`? string `requestId`? string	mcp
`remove_from_next_up` Remove from Next Up	Write	Take a book out of Next Up. The book stays in the library.	`bookId` string `requestId`? string	mcp
`create_collection` Create Collection	Write	Create a collection. If one with the same name exists, it is returned instead.	`name` string `requestId`? string	mcp
`rename_collection` Rename Collection	Write	Rename one of the reader’s collections. Refused with collection_exists when another collection already has that name (case and spacing ignored).	`collectionId` string `name` string `requestId`? string	mcp
`delete_collection` Delete Collection	Sensitive write	Delete a collection. Its books stay in the library and in their other collections. Confirm with the reader first, then pass confirmed: true.	`collectionId` string `confirmed` true `requestId`? string	mcp
`add_to_collection` Add to Collection	Write	Put a book in a collection. Nothing changes if it is already there.	`bookId` string `collectionId` string `requestId`? string	mcp
`remove_from_collection` Remove from Collection	Write	Take a book out of a collection. The book stays in the library. Confirm with the reader first.	`bookId` string `collectionId` string `requestId`? string	mcp
`move_books_between_collections` Move Books Between Collections	Write	Move 1–100 selected books from one collection to another in a single action. Validates the whole batch before changing anything. Other collections and reading history stay unchanged. Confirm with the reader first. Repeating a completed move is harmless.	`bookIds` array of string `sourceCollectionId` string `destinationCollectionId` string `requestId`? string	mcp
`remove_book` Remove Book	Sensitive write	Delete a book from the library. A book with reading history (a started read, a rating, a journal entry, progress or a Top Four place) or a note or cover photo the reader added is refused unless confirmed is true; the refusal lists what would be lost. Always confirm with the reader first; pass confirmed: true only after they agreed to lose that history.	`bookId` string `confirmed`? true `requestId`? string	mcp
`update_book` Update Book	Write	Change a book’s details as the app’s edit screen does: title, full title, authors, categories, page count, publication year, publisher, synopsis, ISBN, edition language, edition format, audiobook length, the reader’s note, or marked for reread (only for a book they did not finish). Only the fields given change; null clears an optional one. Refused with duplicate_book when the new ISBN, or title and authors, belong to another book. The cover cannot be changed here. Never guess an ISBN.	`bookId` string `title`? string `fullTitle`? string or null `authors`? array of string `categories`? array of string `pageCount`? number `publicationYear`? number or null `publisher`? string or null `synopsis`? string or null `isbn13`? string or null `languageCode`? string or null `format`? string or null `audioDurationMinutes`? number or null `note`? string or null `markedForReread`? boolean `requestId`? string	mcp; library:private for review text

Results and errors

Each tool returns a short summary and the full result as structured data, with links into the Reading Journey app where relevant. A failed call returns an error result with structuredContent.error.code: invalid_input, book_not_found, collection_not_found, entry_not_found, read_not_found, not_eligible, next_up_full, in_progress, no_open_read, no_read, has_reading_history, changed_recently, library_full, rate_limited (with retryAfterSeconds), write_failed, insufficient_scope, account_deleted, unavailable and internal_error. Feedback can also return feedback_pending or delivery_unknown; retry with the same requestId. HTTP errors outside MCP use RFC 7807 problem responses.

Rate limits

Limit	Value
Read calls per connection	60 per minute, 2,000 per day
Write calls per connection	30 per minute, 500 per day
Feedback per account	3 per hour, 10 per day
Request body	64 KiB; 3 MiB for photo and journal tools; 6 MiB for feedback
Books per library	100,000

Data handling

The connector processes only the connected reader's library to answer their requests. See the privacy policy for what the assistant receives, what we store and how deletion works, and the terms of service.

Support

Email [email protected] or see Support.