MCP Tools Reference

Becoming’s MCP server exposes 22 tools — 14 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

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

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

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

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.

export_highlights

Export the user’s whole library as CSV text — one row per highlight with its source, notes, tags and dates, the same file as Export Your Highlights. The result is paged: the first page carries the header row, and the client appends the pages into one file.

Required scope: highlights:read

Inputs:

Field	Type	Notes
cursor	string	Returned in the previous response’s meta.next_cursor. Omit for the first page.
limit	integer (1–1000)	Rows per page. Default 500.

Returns: csv (the page’s text), row_count, and meta.next_cursor — null on the last page.

get_source_markdown

Export one source as a Markdown file — the same file the Markdown export produces: YAML frontmatter with the source’s details, the highlights in reading order with their tags, notes and location links, and the notes on the source itself. The text block carries the file verbatim, so the client can save it as .md as is. The whole-library zip is not offered over MCP; fetch sources one at a time.

Required scope: highlights:read

Inputs:

Field	Type	Notes
id	integer (required)	Source id, from list_sources.

Returns: markdown (the file’s text), source_id and highlight_count.

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)

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

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

Two of these tools spend AI credits from the same allowance the apps draw on:

• add_source with a url — Becoming fetches the page and reads it for you, which spends credits; a YouTube video costs more the longer it runs. Adding a book costs nothing.
• start_theme_generation — the most expensive action in Becoming when it runs across your whole library. A seed_highlight_id or an intent costs a fraction of that. The Practices are included, so generate_theme_practices costs 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

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

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, export_highlights, get_source_markdown, 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

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

search_highlights, list_sources and export_highlights 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.