YOUR NOTES, WITH YOUR ASSISTANT
A little context.
A more useful AI.
Connect Folio to the tools you already use. Let your assistant read your daily notes, find an idea, or help you plan what comes next.
MCP & API · FOLIO
Before you connect
- 01
Use a Pro account
A Folio purchase includes API and MCP access. Verify your email first. Your saved notes remain available to read and download.
- 02
Create an integration token
Open Settings → Integrations. Give the token a name, choose an expiry, and start with Read only. Choose Read and write if you want your assistant to edit notes.
- 03
Keep your token somewhere private
Copy it when it appears. Folio only shows the secret once. Store it in your client’s credential field or local environment, never in a prompt or a committed config file.
MCP endpoint · Streamable HTTPhttps://writefolio.app/mcp/folio
API base URLhttps://writefolio.app/api/v1
Connect your assistant
Choose your tool for its configuration and connection check. These examples contain placeholders, never your actual token.
Add Folio to Claude Code
In your terminal, add a user-scoped HTTP server. Replace YOUR_FOLIO_TOKEN locally. This stores the header in your local Claude configuration; do not share it.
claude mcp add --transport http --scope user folio 'https://writefolio.app/mcp/folio' \
--header 'Authorization: Bearer YOUR_FOLIO_TOKEN'Start a new Claude Code session. Run /mcp and check that Folio is connected. Ask it to read your Folio context and today’s note.
Try it out
Start with a read. Your assistant should use your account’s local date rather than guess what “today” means.
Read my Folio context and today’s note. Summarize my open tasks without changing anything.Add “Review the launch checklist” to today’s note in Folio. Read the full note first, preserve all existing content and formatting, and tell me when the save succeeds.For MCP clients, you can also ask: “Find my notes about the launch, then list the days worth revisiting.” Search and calendar tools are available in MCP; the GPT starter covers reading and writing daily notes and Pages.
Tools & API
MCP exposes 11 tools with a Read and write token. Read-only tokens list only read tools. API requests use the same token, notebook permissions and content format.
curl 'https://writefolio.app/api/v1/me' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $FOLIO_TOKEN"| MCP tool | API endpoint & use |
|---|---|
| Account & calendar | |
| get_context | GET /meLocal date, timezone, plan and editing rules. |
| update_timezone | PATCH /me/timezoneSet your timezone with { timezone }. |
| get_calendar | GET /calendar?from=YYYY-MM-DD&to=YYYY-MM-DDDays with notes and nearest earlier/later dates. Request a range of at most 366 days. |
| Daily notes | |
| list_notes | GET /notesSearch saved daily notes with q. Paginate with page and per_page (up to 100). Results are summaries; use entry_date with get_day to read the full document. |
| get_day | GET /days/{date}Read a complete daily note by YYYY-MM-DD. A missing writable day has note: null and revision: 0. Reading creates no note or recurring tasks. Missing past days return 404. |
| save_day | PUT /days/{date}Save the full content document and latest revision. Pro can write any future day. |
| Pages | |
| list_pages | GET /pagesSearch persistent Pages by title or text with q. Paginate with page and per_page (up to 100). Results are summaries. |
| get_page | GET /pages/{id}Read the complete Page by its UUID, including the latest revision and read-only day_entries. Edit the source day to change a history entry. |
| create_page | POST /pagesCreate an undated Page with title and optional content. An omitted document starts empty. |
| save_page | PUT /pages/{id}Replace title and the full content document using the latest revision. Stale revisions return 409. |
| move_to_page | POST /days/{date}/move-to-pageMove a block into a Page. Send the saved source content, revision, block path, destination Page UUID as page and destination_revision. Both documents change atomically; stale revisions return 409. |
Integrations work with daily notes by date and Pages by UUID. Reconnect existing MCP clients to refresh the available tools. Lists support q, page and per_page. Returned user and note IDs are UUIDs; read and save daily notes using their calendar date. Use a Page UUID to read or save a persistent page.
Read first. Then write.
Folio stores the complete editor document as Tiptap JSON, including checklists, tables, images and mentions. A save replaces that document. Sending only your new paragraph would remove the rest.
- Read the full note with get_day or the Page with get_page. Daily notes use GET /days/{date}, and Pages use GET /pages/{id}.
- Apply the requested change to the returned content, preserving unrelated blocks, marks and attributes.
- Send the entire updated content with its revision. For Pages, include the title as well. Use 0 only when creating a missing daily note.
- On 409, read again and reconcile both edits. Do not retry the old document.
{
"revision": 0,
"content": {
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "A little space for today."
}
]
}
]
}
}When something doesn’t connect
- 401 · Authentication
- Check that your token is complete, not expired or revoked, and sent in the Authorization header. Set the environment variable before starting the client.
- 403 · Permissions
- Verify your Folio email and Pro plan. Editing needs a Read and write token. Reconnect after replacing a read-only token so the client refreshes its tool list.
- 404 · Unavailable
- Confirm the endpoint and calendar date. A missing past daily note is not created automatically; check the calendar for days with notes.
- 409 · Another edit
- Read the latest document and revision, reconcile your change, then save. Never force an old revision.
- 422 · Invalid input
- Check the returned validation errors. Dates use YYYY-MM-DD; content must be a full Tiptap document and revision must be an integer.
- 429 · Rate limit
- Folio allows 120 integration requests per minute. Wait before retrying; avoid repeatedly polling every note.
- OAuth prompt or connection timeout
- Use HTTP with a Bearer header, not an OAuth login. Check the exact URL, HTTPS reachability and client configuration. Cloud clients cannot reach folio.test.
To disconnect, revoke the token in Settings → Integrations and remove the server from your client. Revoking access does not remove your notes.