Pinto Notes

npx add-mcp 'https://mcp.pintonotes.com'

Pinto Notes, the notes app for iPhone and Mac, has a remote MCP server built in. This page is for developers and anyone curious how it works: the address, how an AI app signs in and gets approved, and every tool it can call.

Pinto Notes asking "Allow ChatGPT to use your notes?" with a choice of Read and Edit or Read Only, and Allow and Don't Allow buttons.

The address

https://mcp.pintonotes.com

The older address, https://mcp.ambernotes.app, is the same server and keeps working, so anything you connected before needs no change.

• Transport: MCP Streamable HTTP, answering with JSON. There is no server-sent stream; clients post each request.
• Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
• Server name: pinto-notes. It sends instructions on initialize that tell the model how the notes are laid out.

How access works

There are two ways in. Both need a Pinto Notes account, and both are approved by the person.

Sign in with OAuth (ChatGPT, Claude and other apps)

1. An unauthenticated request gets a 401 with a WWW-Authenticate header pointing to the protected resource metadata, at the address above plus /.well-known/oauth-protected-resource.
2. The client registers itself (dynamic client registration) and starts OAuth 2.1 with PKCE (S256). Scopes are notes:read and notes:write.
3. The authorization server metadata is at the address above plus /.well-known/oauth-authorization-server.
4. The authorization step opens pintonotes.com/connect. The person signs in there (email and password, or Sign in with Apple), and the page shows a two-digit number. Pinto Notes on their iPhone or Mac asks “Allow [app] to use your notes?” and where access goes; they type the number, choose Read and Edit or Read Only, then Allow. With no device nearby, they can approve on the page with their recovery key.
5. The client gets an access token (valid for an hour) and a refresh token. The tokens only open this server.

Access token (Claude Code, Codex and scripts)

In Pinto Notes, Settings, Connect an AI, Claude Code or Codex creates a token starting with pane_, read only or read and edit. Send it as Authorization: Bearer pane_…. The Claude Code and Codex guide has the exact setup.

Settings, Connect an AI: guided setup for each app, and everything that's connected.

Every connection shows up in Pinto Notes under Connected, and the person can disconnect it at any time. Each tool call runs as that person, with row-level security, so a token can only ever reach its owner's notes. Calls are rate limited per account.

Notes are end-to-end encrypted, so the server can't read them at rest. Approving a connection gives it a copy of the notes' key, locked with a secret derived from its own token. During each request the server unlocks the key in memory, decrypts what the call needs, and drops it when the request ends; disconnecting deletes that copy. Locked notes stay out of reach, since their key comes from the notes password. An encrypted notes app that ChatGPT and Claude can use explains the trade-off.

What happens to changes

• Every edit keeps the previous version. history lists them and restore puts one back.
• In the app, the person sees what an AI changed, with Undo.
• Deleted notes go to Recently Deleted for 30 days and can be brought back with restore.
• A read-only connection only sees the tools marked reads below.

Tools

The tools treat your notes like a folder of files, the way coding agents already work. Each note is a markdown file with a path, like Work/Acme.md, and its first line is the title. A note's sub-notes and attached files sit in a folder with its name, like Work/Acme/Agenda.md. Checklists are - [ ] lines, and tables are markdown tables.

edit is an exact search and replace, like a coding agent's Edit. The AI has to read a note with fetch before it changes it, and an edit is refused if the note changed since. That covers ticking a checklist item, adding a row to a table and fixing a sentence, without rewriting the rest of the note.

A note can also hold an app: a small React project at a path like Work/Habits.app/, with its data in data.json. The same tools read and change it, and see_app shows what it looks like.

• search (reads). Finds notes. With query: ranked full-text search (words, "quoted phrases", OR, -word), best first, with a snippet. With pattern: like grep, a regular expression (or plain text) matched line by line; output "files" (the matching paths), "content" (matching lines as path:line: text, with context lines) or "count". Names and paths match too. Narrow with path (a folder "Work/", a glob "Work/**/2026*", a note and its sub-notes, an app "Work/Habits.app" to search its code), type, pinned, modified_after/before (YYYY-MM-DD), title_only, sub_notes: false, deleted: true. Pages with limit and offset.
• list (reads). Lists like a file browser, newest first. No path: the top level. A folder ("Work/"), a note's folder ("Work/Acme/": its sub-notes and files), an app ("Work/Habits.app"), or "Recently Deleted/". pattern is a glob over every path below it ("**/*.md", "Work/**", "**/*.app", "**/*invoice*"). Pages with limit and offset.
• fetch (reads). Reads a note, an app file, an app's data.json or a file, with line numbers (cat -n). Long text is read in parts: offset is the first line, limit how many (default 2000). A folder reads as its listing. Files: text files (TXT, CSV, JSON, code) as text you can edit; PDFs, Word, Excel and PowerPoint as their text; pictures as images. raw: true returns the file itself (base64, up to 10 MB).
• create (changes). Creates a note, a folder or an app. A note: path "Work/Acme.md" (its name is its title; folders are made as needed) and content, its markdown. In a note's folder ("Work/Acme/Agenda.md") it becomes that note's sub-note. A folder: path "Work/Clients/". An app: path is the note that becomes the app (existing, or new like "Work/Habits.md"); it starts as a React + TypeScript + Tailwind + shadcn/ui project whose README.md says how apps run here, or, with template, as that pintonotes.com template's app, its data and its note. Notes are markdown: checklists "- [ ] item", links to notes [[Title]], and a tracker is a table with a line like <!-- pane-table: Date=date; Mood=scale 1-5; Walk=choice Yes|No --> above it (keep values in range).
• edit (changes; can remove or replace). Replaces old_string with new_string in a note, an app file, an app's data.json or a text file (TXT, CSV, JSON, code), like a coding agent's Edit. old_string is the exact text, without line numbers, and the item must have been read in this session. It must match once unless replace_all; an empty new_string deletes it. Answers with checks: what the change broke in a note (a table, a checklist line, a tracker value), or the app's compile, render and test results. Each edit is one change the person can undo.
• write (changes; can remove or replace). Writes a whole note, app file, data.json or file: creates it, or replaces all of it (an existing item must have been read in this session). The old version stays in history. A file ("To read/Summary.txt", "To read/Paper.pdf") takes content for text, or content_base64 with mime_type for anything else (a PDF, a picture, a spreadsheet), up to 10 MB. Answers with checks: what the change broke in a note, or the app's compile, render and test results. Notes are markdown: checklists "- [ ] item", links to notes [[Title]], and a tracker is a table with a line like <!-- pane-table: Date=date; Mood=scale 1-5; Walk=choice Yes|No --> above it (keep values in range).
• move (changes; can remove or replace). Moves or renames a note, a folder or an app file: a note to a folder ("Clients/", made if needed), into a note's folder ("Work/Acme/": it becomes a sub-note), or to a new name ("Work/New title.md"); a folder to a new path ("Archive/2025/"); an app file within its app; a file in a folder to another folder ("Archive/") or a new name ("To read/Old paper.pdf", same ending).
• delete (changes; can remove or replace). Deletes a note (to Recently Deleted with its sub-notes, for 30 days), a folder (its notes and files go to Recently Deleted), a file in a folder (to Recently Deleted for 30 days), an app file, or an app ("Work/Habits.app": the note stays; the app is kept in history).
• history (reads). Earlier versions, newest first, with who made each (a device or an AI): of a note's text, an app (code and data), or a file.
• restore (changes; can remove or replace). Brings back a note or file from Recently Deleted (no version), or an earlier version from history: of a note's text, an app (code and data as they were), or a file.
• pin (changes; can remove or replace). Pins a note to the top of the list, or unpins it.
• see_app (reads). Screenshots of a note's app at iPhone and Mac sizes, light and dark, over a sample with the shape of its data, with what each view shows and anything broken. With steps, uses the app like a person instead and answers after each step with what's on screen, console errors, what changed in its data, and screenshots: { tap: "Add" } (text, label or CSS selector), { type: "85", into: "Weight" }, { scroll: "down" }, { wait: 500 | "Saved" }, { press: "Enter" }, { resize: "phone" | "desktop" }, { dark: true }. Nothing is written back.

search and fetch follow the shape ChatGPT expects for searching and reading. Every tool carries MCP annotations (readOnlyHint, and destructiveHint where it applies), so clients can ask before a change.

Install in your AI tool

Each of these adds the address above. The first time the tool connects, your browser opens pintonotes.com/connect: sign in there, then approve on your iPhone or Mac by typing the number the page shows, and choose Read and Edit or Read Only. You need the free app and an account.

Claude Code

claude plugin marketplace add pinto-notes/pinto-notes
claude plugin install amber-notes

The plugin adds the server and a skill that tells Claude how your notes are laid out. Then run /mcp in Claude Code, pick amber-notes and sign in.

Or add only the server, for every project:

claude mcp add --scope user --transport http amber-notes https://mcp.pintonotes.com

Codex

codex mcp add amber_notes --url https://mcp.pintonotes.com

Codex starts the sign-in straight away. To sign in again later, run codex mcp login amber_notes.

Gemini CLI

gemini extensions install https://github.com/pinto-notes/pinto-notes

Then run /mcp auth amber-notes in Gemini CLI to sign in.

VS Code

code --add-mcp '{"name":"amber-notes","type":"http","url":"https://mcp.pintonotes.com"}'

The first time VS Code starts the server, it asks you to sign in.

Incredible

1. Open Apps and search for notes.
2. Choose Connect, then Allow in Pinto Notes.
3. Back in Incredible, choose Let's go.

Pinto Notes shows it as an app on this computer that calls itself "incredible". Allow it only if you just chose Connect. On an older version of Incredible, choose Add it here at the bottom of Apps (or Add another MCP server), paste https://mcp.pintonotes.com, then Continue and Sign in, and Add server after you allow it.

With a token instead of signing in

Any of these tools can use an access token instead. In Pinto Notes, open Settings, Connect an AI, Codex, and choose Create Access Token. The token works in any MCP client; send it as an Authorization: Bearer pane_… header, the way the Claude Code and Codex guide shows. It's shown once, so keep it private.

Connect it

• Claude: Pinto Notes in Claude's connector directory, then Connect to Claude.
• Connect ChatGPT or Claude to your notes: add the address as a custom app in ChatGPT, or as a custom connector in an older Claude app.
• Use your notes from Claude Code and Codex: one command, or a few lines of config.
• Gemini CLI, VS Code and Incredible: the steps for each are above.
• Anything else that speaks MCP: add the address and sign in when it asks.

Choosing a notes app for an agent? The best notes app for AI agents sets out the criteria. Coming from Apple Notes? Apple Notes MCP servers compared covers the local servers for Notes on a Mac, and how they differ from this one. Obsidian MCP servers compared does the same for Obsidian vaults.

The server is open source. Read it in supabase/functions/mcp on GitHub.

Checked against the app on .