Documentation

Updated July 20, 2026

Everything you need to get the most out of Samong — from your first whiteboard to connecting AI assistants to your knowledge with MCP.

1.Getting started

Samong is a visual, infinite-canvas app for your knowledge — a place where reading becomes thinking. ("Samong", สมอง, means "brain" in Thai.) Instead of filing notes away in folders, you lay them out in space and connect them like a map.

Your workspace is built from four kinds of content, all living on canvases you can pan and zoom:

Whiteboards — infinite canvases where you arrange and connect ideas. Create and browse them from the Whiteboards gallery.
Cards — every note is a card. Write in rich text and connect cards to each other with `[[wikilinks]]`.
Journal — a dated space for daily notes and thinking.
PDFs — drop a PDF onto a board to read it inside Samong and pull highlights straight into cards.

Press ⌘K (Ctrl K on Windows) anywhere to search across everything in your workspace.

2.Working on the canvas

A whiteboard is an endless surface. Scroll or pinch to zoom, drag the background to pan, and drag nodes to move them. Double-click empty space to drop a new card, or use the toolbar to add other kinds of nodes.

Beyond cards, boards hold text blocks, sections (grouping areas), images, shapes, links, and embedded media — plus two structural nodes worth knowing:

Mindmaps

Branch an idea into a tree and Samong lays it out automatically. Drag a branch and its whole subtree comes along, so you can restructure your thinking with a single gesture.

Sub-whiteboards

Drop a board reference to nest one whiteboard inside another. Double-click it to descend, and follow the trail chip back up — useful for breaking a big map into focused sub-maps.

You never need to hit save — every change is stored automatically, and open boards sync live across your devices and collaborators.

3.Reading & extracting from PDFs

Open a PDF from a board to read it in the side panel. The reader has two tools you switch in its toolbar:

Cursor — the default. Drag over text to select it, drag on empty space to draw a region box, or click an existing highlight or region to manage it.
Region select — a crosshair mode that always draws a region box, handy for figures and scanned pages.

Select a passage or region, then Extract to card. Samong creates a card with the text and a source link back to the exact page — double-click the source badge on a card any time to jump straight there.

4.AI features & credits

From the AI button in the PDF panel, Samong can turn a document into knowledge for you:

PDF → mindmap — a Buzan-style mindmap of a page range, dropped onto your canvas.
PDF → summary card — a concise markdown summary as a new card.
Chat with a PDF — ask questions about the pages you select.

Each AI action spends credits from your monthly allowance (Free includes 10 per month; Pro includes 500). Short documents cost 1 credit and longer page ranges cost a little more — always shown before you spend, and always for the pages you actually asked for, scanned books included. Your remaining credits appear in the sidebar.

6.Connect AI assistants (MCP)

MCP (the Model Context Protocol) lets AI assistants like Claude securely read and work with your Samong knowledge — only after you grant permission. Connect a client once and it can search your workspace, read your cards and whiteboards, and, if you allow it, build and edit whiteboards and cards for you. Reading is free for everyone; the write tools are part of Pro (grant the permission on any plan — writing simply switches on when you upgrade, no reconnect needed).

What you’ll need

An MCP-capable client that supports remote connectors — for example, the Claude desktop app.
To be signed in to Samong in your browser (the connection is authorized on a Samong consent page).

Your connection URL

This is the single address you paste into your AI client. Everything else — sign-in, permissions, and the secure OAuth handshake — happens automatically.

https://samong.app/mcp

Connected earlier with the old address ending in /api/mcp? It keeps working exactly as before — no need to reconnect.

Connect the Claude desktop app

1Open Claude → Settings → Connectors.
2Click Add custom connector.
3Paste your Samong connection URL from above and confirm.
4Your browser opens a Samong consent page — sign in if you’re prompted.
5Choose the one workspace the assistant may access, review the permissions it’s asking for, then click Allow.
6That’s it — Claude can now use Samong’s tools to help you.

The same URL works in any MCP client that supports remote (Streamable HTTP) servers with OAuth — not just Claude.

What the assistant can do

Every connection is limited to the single workspace you pick, and to one of two permission levels:

Read — search your workspace and read your cards, whiteboards, journal entries, and PDF names.
Write — everything above, plus create and edit note cards, append to your journal, create new whiteboards, and edit whiteboards: build whole arrangements in one go — kanban columns, flowcharts, grids, all laid out automatically — insert real fold-able mind maps from an outline, add text, sections, new or existing cards, PDFs, and board links, move and restyle nodes, connect them with labeled arrows, and remove nodes or connections. Whiteboard edits show up live if the board is open, and earlier board states can be restored from the board’s version history.

The full tool list

These are all the tools a connected assistant is offered, with the exact descriptions it sees. This list is generated straight from the live server, so it always matches reality. Read tools come with every connection; write tools appear only on connections you granted write permission, on a Pro workspace — and none of them ever replaces a whole board.

Read tools — every plan(8)

search
Search this Samong workspace (note cards, whiteboards, journals, PDFs) by keyword. Handles Thai/Arabic/Latin. ALWAYS prefer this over listing when looking for something specific. Returns compact hits with ids for the read_* tools.
list_whiteboards
List whiteboards (id, name, node count, last update), most recently updated first. Paginated.
read_whiteboard
Read a whiteboard as a compact text outline: one line per node (type, text preview, linked card/board/pdf ids), then the edge list (#id: #source → #target, labels) on the final page. Paginated by offset (which continues into the edge list); node text is truncated — use read_whiteboard_node for one node's full content. Never returns raw canvas geometry.
read_whiteboard_node
Read ONE whiteboard node in full (its complete text and references). Use after read_whiteboard when an outline entry was truncated.
list_cards
List note cards (id, title, last update), most recently updated first. Paginated. Prefer `search` when looking for a specific card.
read_card
Read one note card's full markdown content by id.
card_links
The [[wikilink]] graph around one card: cards it links to and cards that link back to it (id + title + excerpt).
read_journal
Read the journal entry for one date (YYYY-MM-DD) as markdown. Empty if no entry exists.

Write tools — Pro(14)

create_card
Create a new note card from markdown. The first line becomes the card's display title. Returns the new card's id.
append_journal
Append a markdown block to a journal entry (defaults to today). Never overwrites existing content.
update_card
Replace one note card's markdown content (the first line is its display title). Read the card first — this overwrites the whole body. Note: the [[wikilink]] graph (card_links) refreshes only when the card is next edited in the app, so don't rely on card_links to reflect links you just wrote.
create_whiteboard
Create a new, empty whiteboard. Returns its id — then build it up with add_whiteboard_node / connect_whiteboard_nodes.
add_whiteboard_nodes
Add SEVERAL nodes (and optional connections) to a whiteboard in one call, auto-arranged — the tool for building out a board. Layouts: 'flow' ranks connected items into a left-to-right flowchart; 'row' places items side by side (kanban: section items + members via items[].section); 'column' stacks; 'grid' packs collections; 'auto' (default) picks flow when connections exist, row when sections exist, else grid. Sections grow to wrap their members. Item kinds match add_whiteboard_node (text/card/section/pdf/board). Read whiteboard_design_guide first for sizes, colors and recipes. Returns every new node's id.
add_whiteboard_mindmap
Insert a NEW mind map (the app's foldable, draggable tree) onto a whiteboard from a nested outline. Use this for hierarchical or brainstorm content instead of many text nodes: branches auto-balance left/right of the root with the app's own layout and branch colors, and users can extend/fold it in the app afterwards. To grow a map that already exists, use extend_whiteboard_mindmap instead. Keep labels short (a few words); max 150 topics, 6 levels.
extend_whiteboard_mindmap
Grow an EXISTING mind map: graft new sub-topics (each may nest its own children) under one of its nodes — the root or any branch. Pass the mindmap-node's id from the whiteboard outline; the new branches inherit the map's side, style and branch colors, and the app re-balances the whole map next time the board is opened. A folded branch is expanded so the additions are visible. The combined map keeps the creation caps (150 topics, 6 levels).
whiteboard_design_guide
How to compose a GOOD whiteboard over MCP: canvas coordinates, real node sizes, spacing rules, the app's color palettes, which layout fits which content, and ready recipes (kanban, flowchart, study map). Read once before building or restyling a board.
add_whiteboard_node
Add ONE node to a whiteboard (for several related nodes, use add_whiteboard_nodes — it auto-arranges). kind 'text' = a text block (requires text); 'section' = a dashed grouping frame (text = its label); 'card' = a note card — pass card_id to place an EXISTING card, or text (markdown) to create a new card and place it; 'pdf' = an existing PDF (requires pdf_id); 'board' = a link to another whiteboard (requires board_id). Omit x/y to auto-place below the board's content. Returns the new node's id. If people are co-editing the board, the node appears for them live.
update_whiteboard_node
Edit one whiteboard node: its text/label, position (x+y), size (width/height), or color. Only the fields you pass change. Card-backed nodes keep their text in the card itself — use update_card for those.
delete_whiteboard_node
Remove one node from a whiteboard, along with every edge connected to it. Does not delete a referenced card/PDF/board — only the node on this canvas.
connect_whiteboard_nodes
Draw a connection (edge) between two whiteboard nodes, optionally labeled. Returns the new edge's id.
update_whiteboard_edge
Edit one whiteboard edge: relabel it (empty label removes the label) and/or re-point its source/target to other nodes.
delete_whiteboard_edge
Remove one connection (edge) from a whiteboard. The nodes it joined are untouched.

Good to know

A connection can only touch the one workspace you approved — nothing else in your account is visible to it.
PDF file contents aren’t readable over MCP yet — PDFs currently appear by name in search results only.
Large results are trimmed to keep the assistant fast and focused; if something looks cut off, ask it to search or page through.

Managing & revoking connections

See every connected assistant — with its workspace and last-used date — under Settings → Connected AI apps. Disconnect removes access immediately.

Treat a connection like a key to your workspace: only approve clients you trust, grant write access only when you need it, and disconnect anything you no longer use.

7.Account, plans & billing

Manage your plan, storage, and AI credits from the sidebar meter and Settings. Free covers up to 1,000 cards, 10 whiteboards, 500 MB of storage, 10 AI credits a month, one workspace, 3 live editors per board, and 3 days of version history. Pro lifts the card and whiteboard caps entirely and adds 500 AI credits a month, 50 GB of storage, up to 5 workspaces, whole-workspace sharing with your team, 10 live editors per board, full version history, all 30 mind map styles and the sticker packs, share-link controls (password, expiry, hiding the "Made with Samong" badge, view stats, PDF downloads), high-resolution 4× and transparent exports, and MCP write access so connected AI assistants can build and edit boards for you (reading via MCP is free for everyone).

Your data is always yours — export whiteboards as PNG, SVG, or PDF whenever you like.

8.Getting help

Hit a bug, or have an idea? Use the Feedback button in the top bar to send a report (you can attach screenshots), or email us at [email protected].

Samong is in active beta and we read and reply to everything — your feedback shapes what we build next.

← Back to Samong Home