Capture, find, read and update Notes from external tools. Omit 

 to create a root Note, or pass another Note's identifier to add a Note beneath it.

Note content uses one representation: complete authored RichtextMarkdown (RMD),

including metadata, inline styles, the authored stylesheet and Theme/import

references. Generated resolved CSS is not included. Create, read and save return

content and its version together. No format, view flag or read receipt is accepted.

VFS separately offers bounded reads and targeted editing.

# Research decision

Keep the existing approval flow.

create_note

Version 0. Edit that returned content and send it with the returned version to

adding another Note. Repeating a successful creation creates another Note.

Every Note stores its own content. Adding a Note leaves its ancestors' content and revisions unchanged.

For a web page, send its URL rather than constructing resource identifiers:

The server builds Web → Site → URL from the page's host and full address, without the

credentials a link carries (signatures, tokens, user info), which are never stored.

Another host is another site. The address without its credentials remains the return

link. It is not fetched. A capture the browser extension made sends

. The segment form below also supports Platform resources.

 records where the thought was captured. It is independent of the subject's

 reference and of Note parentage. For example, a browser extension capturing

Keep the opening focused on the customer's first five minutes.

 has one to eight segments, ordered broad to specific in the order the

 looks up at most four segments: a Note captured deeper

is listed under its four-segment ancestor with its complete capture. IDs and labels are limited to 256 characters,

return URIs to 4,096 characters, and the encoded resource address to 1,500 UTF-8 bytes.

Return URIs accept local routes or HTTP(S) URLs without credentials. A 

segment names a Material by its identity alone: a label sent with it is not stored, and

each reader sees the title they may read. A Platform segment (

) returns to the Platform's own page for its identity, so a

 sent with one is not stored; a quote under a page returns to its passage on that

page. A page and its site are identified by the page's link: a 

 segment's id and label derive from it, whatever was sent.

 are the Platform's own channels and are refused.

Origin does not change resource identity. The server derives

Search prefixes; callers cannot submit those query fields.

Place details are a frozen snapshot, readable by the Note's readers. They grant no

access to the referenced resource and are not verified evidence of the caller's

screen. A Place that names a Material is accepted only when you can read that Material;

 for an unrelated thought. Notes without a place remain ordinary

 filter and source controls use this association for recall

 finds the active root Notes you can read at a Place and more specific

Places, whoever wrote them: your own and those shared with you. Children, archived

list_notes

notes: [{noteId, title, createdByYou, lastEditTimestamp, place}]

timestamp is Unix milliseconds; results sort newest edit first, with descending

 is true for your own Note and false for one shared

with you. Place includes captured labels and return URLs.

Badge counts are exact from 0–9, then show 9+.

matches. At that boundary the response contains 

; it is a lower bound, not an exact total. Below ten,

 is false. Use this count for the badge, not the number of Notes

 and the cursor to browse every Note: the count cap does

snapshot. It survives editing or deletion of that record; every request still

checks the caller and scope. Counts and pages are separate reads, and concurrent

edits can reorder the live list. Refresh to restart browsing.

Passing a captured Place, including its nested origin, does not narrow the capture

 argument filters it. For example, one Browser

capture and one MCP capture of a post return total 2; adding 

returns total 1. A site lookup includes captures of other posts too.

 finds the Notes you can read whose content is closest in meaning to a

query, closest first: your own and those shared with you. It searches every Note you

can read that is not deleted, once the Note is indexed for search, so unlike

 it is not limited to the active root Notes at a Place.

search_notes

notes: [{noteId, title, createdByYou, lastEditTimestamp, place?, score}]

 is the relevance to the query: higher is closer. The text result says

whether each Note is yours or shared with you.

Thumbnails are for programs that show results. Each one named in 

 (base64 bytes) in the structured result, once the Note

has been rendered; the text result never carries them.

 (a root or child) and returns that Note's content. 

 for related Notes. Related Notes are direct children unless 

read_note

. Parents precede descendants; siblings are newest first. Follow 

 is true. Each page ends at a complete Note. Each Note requires its own current grants, including historical reads.

The addressed Note and every included child return complete authored 

. Only the set of related Notes paginates. An individual

Note that exceeds the response budget fails explicitly rather than returning a

partial document; VFS provides bounded reads for those cases. Read metadata is

outside the content: submit only the content field when saving.

The text response marks each generated footer as 

[version N; Note read metadata, not document content]

. Saving that marker is refused; ordinary authored text such

Full-fidelity administrative exports use 

 on the Defect MCP server. That export preserves stored content, metadata and relationships with Firestore sentinels.

 accepts the complete edited content. The server computes granular

Richtext edits, including authored stylesheet changes, and saves through ordinary

collaboration. It leaves the Note's Place, source, capture origin, parent and

# Research decision

Keep approval before publishing.

update_note

canonical authored RMD at that acknowledged version, including concurrent changes

incorporated. Always use the returned content and version together as the next

editing baseline; retaining the submitted text with a newer returned version can

Identical content creates no edit and returns the unchanged authoring content and

Version, even if later Versions exist. Converted submissions have the same 512 KiB

limit as creation. Retain metadata and styles while editing: the complete submitted

document is authoritative, so omissions can remove presentation. Unchanged authored

CSS retains its stored form. A stylesheet change that cannot be stored is refused,

For example, the extension reads Version 7 and edits its opening while someone

adds a separate paragraph in Drive. Sending 

changes against that state and rebases them over the Drive edit. Version is not an

unchanged-document precondition. Omitting it compares the full submission with the

latest state loaded by the server, so omitted current writing is a requested deletion.

A later append race still uses ordinary collaboration. A confirmed client overwrite

omits the version; it needs no preliminary read, receipt or separate overwrite flag,

If typing continues during a save, retain those newer local edits and reconcile them

with the returned baseline. Do not replace the live editor blindly, or label its

unreconciled content with the returned version.

Overlapping changes follow ordinary collaboration. The shared differ can group

separate block changes into a wider replacement; it does not promise a minimal or

semantic merge. A body-only edit preserves concurrent stylesheet changes; competing

stylesheet replacements conflict because a stylesheet is one stored attribute.

The output schema declares both success and failure fields. The text response begins

Read the current Note before forming a new update after either outcome. A partial

failure is not a rollback. Other failures retain the ordinary MCP error contract.

 and current Editor access on the addressed Note,

including at the write. A child does not require an ancestor grant to edit.

An inline image lives inside Note content, the way a pasted image lives inside a

document. It is not a Drive Asset and never appears in Drive; to put a file in Drive,

reference. Anyone with the URL can open the image.

upload_inline_image

# Evidence

![Screenshot of the page](https://firebasestorage.googleapis.com/v0/b/…?alt=media&token=…)

Seen 2026-09-19 12:00 UTC.

. Other arguments are refused rather than ignored: a

folder, a name or a description means the caller wanted an Asset, not an inline image.

RMD content is converted to ProseMirror before storage. Schema-based editors can use

@charmiq/service-common/richtextEditor/client

Never hand-unescape content or submit local editor JSON as RMD.

512 KiB of serialized ProseMirror content

, measured in UTF-8 bytes. The root is depth zero; the maximum depth is 16.

A source is an optional subject reference. Its URI and label are trimmed; blank labels are omitted. Creating a Note does not fetch the referenced resource or grant access to it.

The connection uses the authenticated User and Organization context and requires access to create Notes. The creator owns a new root Note; adding a Note requires at least Commenter access to the addressed parent. The parent and every ancestor must be active.

A new child copies its immediate parent's grants and gives its creator Owner. Later sharing changes affect only the addressed Note; permission propagation is separate. Organization membership, authorship, source/place references and optional Charm attribution do not bypass a Note's current grants.

Capture, find, read, and update Notes from external tools — in RichtextMarkdown, with the page they came from.

Argument	Required	Description
`content`	Yes	Complete authored RichtextMarkdown
`parentId`	No	Identifier of the parent Note; omit for a root
`source`	No	Subject reference with a `uri` and optional `label`
`place`	No	`{url, label?, quote?}` or `{segments}`, with an optional `origin`; the Platform encodes URL Places

Argument	Description
`place`	`{url}` for this page; `{url, scope: 'site'}` for its site; or `{segments}` for a resource prefix
`origin`	Optional capture-channel filter: `platform`, `browser`, `mcp`, or `action`
`limit`	Maximum Notes per page, 1–50; default 50
`cursor`	Return the previous response's cursor unchanged with the same Place and origin filter

Argument	Description
`query`	Required. What the Notes are about, in natural language: a topic, a page title, a passage
`maxResults`	Maximum Notes to return, 1–25; default 10
`include`	Optional thumbnails for each Note: `thumbnail` (light), `thumbnailDark` (dark)

Argument	Description
`maxDepth`	With recursive reads, maximum levels below `noteId` (1–16); 1 means children. Omit for all descendant levels
`limit`	Maximum related Notes per page; the response byte budget may shorten a page
`cursor`	Continuation from the previous page; keep the starting Note and selection unchanged
`version`	Omit for current content; supply a retained Richtext Version for historical content

Argument	Required	Description
`noteId`	Yes	Existing root or child Note identifier
`content`	Yes	Complete edited content; an empty string clears existing writing
`version`	No	Authoring Version paired with the content from create, read or save; omitted means latest when editing starts

Note MCP Server

Create a Note

Captured Place

Find Notes at a Place

Find Notes by Meaning

Read a Note or Subtree

Update a Note

Upload an Inline Image

Content and Sources

Access

Code	Meaning
`conflict`	No authored change landed; a competing stylesheet edit or removed target prevented the save
`partial-application`	Some authored changes remain saved; others were dropped

Argument	Required	Description
`mimeType`	Yes	`image/png`, `image/jpeg`, `image/gif` or `image/webp`; the server reads the bytes and refuses a mismatch
`data`	Yes	The image bytes, base64-encoded; up to 10 MiB of image bytes