MCP Tools Reference
Becoming’s MCP server exposes 20 tools — 12 for reading your library and Themes, and 8 for taking action: adding highlights and sources to your library and acting on The Academy — plus several resources for MCP-compatible AI clients.
Read tools need a matching :read scope. Write tools need a matching :write scope and require the client to confirm each action (see Write tools below).
If you haven’t yet connected a client, see Connecting an MCP Client.
Read tools
Section titled “Read tools”search_highlights
Section titled “search_highlights”Search highlights in the user’s library using full-text, semantic (vector), or hybrid retrieval. Hybrid is the default and combines both signals via reciprocal-rank fusion; it falls back to full-text when an embedding for the query isn’t available.
Required scope: highlights:read
Inputs:
| Field | Type | Notes |
|---|---|---|
query | string (required) | The search text. |
mode | fulltext | semantic | hybrid | Default hybrid. |
source_id | integer | Restrict to highlights from a single source. |
limit | integer (1–50) | Page size. Default 10. |
cursor | string | Returned in the previous response’s meta.next_cursor. |
Returns: matching highlights with content, location, source metadata, note count, and pagination metadata.
list_sources
Section titled “list_sources”List sources in the user’s library.
Required scope: sources:read
Inputs:
| Field | Type | Notes |
|---|---|---|
q | string | Optional title/author search. |
type | Book | Article | Video | Podcast | Optional filter. |
limit | integer (1–50) | Page size. Default 20. |
cursor | string | Returned in the previous response’s meta.next_cursor. |
Returns: sources with title, type, author, cover URL, and per-source highlight counts.
get_source
Section titled “get_source”Fetch a single source and the user’s highlights attached to it.
Required scope: sources:read
Inputs:
| Field | Type | Notes |
|---|---|---|
id | integer (required) | Source id. |
Returns: source metadata plus the user’s highlights for that source.
get_highlight
Section titled “get_highlight”Fetch a single highlight with its source metadata.
Required scope: highlights:read
Inputs:
| Field | Type | Notes |
|---|---|---|
id | integer (required) | Highlight id. |
Returns: highlight content, location, source metadata, and the user’s note count for the highlight.
get_import
Section titled “get_import”Poll the status of an import started by add_source. Imports run in the background; once one completes, confirm the new source with list_sources.
Required scope: sources:read
Inputs:
| Field | Type | Notes |
|---|---|---|
id | integer (required) | The import_id returned by add_source. |
Returns: the import’s status (pending | processing | completed | failed), its result counts, and the failure reason when it failed.
For a video cut short by credits, note that the nightly sweep resumes it as a new import: the original import_id keeps its out-of-credits result for good, so re-polling that id reports a truncated video long after the rest has been highlighted. Follow the source’s highlights_count with list_sources or get_source instead — it rises as the sweep lands chunks. Neither is a completion flag, so expect a rising count rather than a terminal state.
Themes and Practices (read)
Section titled “Themes and Practices (read)”These tools read your Academy data. get_academy_status needs no scope — a client can call it to check whether the Theme and Practice tools are available before using them.
| Tool | Purpose | Inputs | Required scope |
|---|---|---|---|
get_academy_status | Check Academy access and Theme/Practice availability | None | None |
list_themes | List the user’s Themes, active and past | None | themes:read |
get_theme_timeline | Get one week of a Theme’s Practice timeline, around a date | theme_id (required); date (optional ISO date, defaults to today) | themes:read |
get_theme_generation | Check the status and result of a Theme generation | id (required) | themes:read |
list_theme_practices | List the Practices belonging to a Theme | theme_id (required) | practices:read |
get_today_practices | Get today’s Practices | None | practices:read |
get_practice_reflection | Read a saved reflection for a Practice | practice_id (required) | reflections:read |
Write tools
Section titled “Write tools”Write tools change data in your library, so they carry an extra safeguard. Each one requires the matching :write scope, and the client must pass confirm: true together with a short user_intent string describing what you asked for. If either is missing, the call is rejected — nothing is written by accident.
add_highlights and add_source work on every plan; the Theme, Practice, and reflection write tools are available on The Academy only.
Every write tool takes confirm: true and user_intent in addition to the tool-specific inputs below.
| Tool | Purpose | Inputs | Required scope |
|---|---|---|---|
add_highlights | Save up to 20 passages as highlights — to an existing library source, or to a Book/Article found or created from metadata | source_id or source (type Book | Article; title; author required for Book; url required for Article; language optional); highlights (array of content with optional location, timestamp_seconds) | highlights:write |
add_source | Add a source without highlights — a link (YouTube videos import their transcript; other pages are fetched and saved as readable articles) or a book | url or book (title + author, language optional). Async: poll the returned import_id with get_import | sources:write |
start_theme_generation | Start generating a new Theme from your library, a highlight, or an intent | intent (optional, max 280 characters); seed_highlight_id (optional) | themes:write |
generate_theme_practices | Generate the daily Practices for a Theme | theme_id (required); context (work | personal | both, required); mix (act | reflect | balanced, required) | practices:write |
complete_theme | Finish a Theme | theme_id (required) | themes:write |
complete_practice | Mark a Practice done | practice_id (required) | practices:write |
skip_practice | Skip a Practice | practice_id (required) | practices:write |
log_practice_reflection | Save a reflection for a Reflect practice | practice_id (required); body (required, non-empty) | reflections:write |
AI credits
Section titled “AI credits”Two of these tools spend AI credits from the same allowance the apps draw on:
add_sourcewith aurl— Becoming fetches the page and reads it for you, which costs 1 credit for a web page, or 1 per ~15 minutes of transcript for a YouTube video. Adding a book costs nothing.start_theme_generation— 66 credits from your whole library, or 10 from aseed_highlight_idor anintent. The Practices are included, sogenerate_theme_practicescosts nothing on top.
Everything else here — add_highlights included — is free. Out of credits, add_source still saves the source; only the highlighting waits.
Resources
Section titled “Resources”Resources are stable URIs that an MCP client can read on demand. Becoming exposes both collection URIs (returning a list) and per-item templates.
| URI | What it returns | Required scope |
|---|---|---|
becoming://highlights | Recent highlights collection | highlights:read |
becoming://highlights/{id} | A single highlight | highlights:read |
becoming://sources | Sources collection | sources:read |
becoming://sources/{id} | A single source with its highlights | sources:read |
becoming://notes | Notes collection | notes:read |
becoming://notes/{id} | A single note | notes:read |
Scopes
Section titled “Scopes”Eleven scopes are available; you grant them at the consent screen when connecting a client. get_academy_status needs no scope.
| Scope | Allows |
|---|---|
highlights:read | search_highlights, get_highlight, highlight resources |
highlights:write | add_highlights |
sources:read | list_sources, get_source, get_import, source resources |
sources:write | add_source |
notes:read | Notes collection and per-note resources |
themes:read | list_themes, get_theme_timeline, get_theme_generation |
themes:write | start_theme_generation, complete_theme |
practices:read | list_theme_practices, get_today_practices |
practices:write | generate_theme_practices, complete_practice, skip_practice |
reflections:read | get_practice_reflection |
reflections:write | log_practice_reflection |
Granting fewer scopes is fine — tools or resources requiring scopes the connection didn’t grant simply return a permission error. Theme, Practice, and reflection write scopes take effect on The Academy; highlights:write and sources:write work on every plan.
Errors
Section titled “Errors”The MCP server uses standard JSON-RPC error codes for protocol-level failures and tool-result errors for application-level failures. Notable codes:
| Code | Meaning |
|---|---|
-32001 | Authentication required (token invalid, expired, or revoked). |
-32002 | Insufficient scope or subscription required. |
-32003 | Resource not found. |
-32004 | Rate limited; back off and retry. |
-32010 | Academy subscription required for this tool. |
-32011 | Invalid input — e.g. a write tool called without confirm: true and user_intent, or a validation failure. |
-32099 | Unexpected backend failure; retry later. |
Per-connection rate limits apply. Most clients handle backoff automatically.
Pagination
Section titled “Pagination”search_highlights and list_sources use cursor-based pagination. Pass the meta.next_cursor value from the previous response as the cursor input on the next call. Continue until next_cursor is null.