Skip to main content

Integration

Claude Code + Scribelet: Give Your Coding Agent a Notes MCP Server

Scribelet exposes a hosted MCP server at `https://api.scribelet.app/mcp`. One `claude mcp add` command, an OAuth consent screen where you pick the desks, and Claude Code can search your notes, follow their links, read your memories and write new notes. Nothing to run locally.

Updated 2026-10-27

Setup

  1. Find your MCP server URL

    In the Scribelet web app, open Account from the sidebar, then AI Agent Connections. The server URL is shown at the top: https://api.scribelet.app/mcp. It is the same for every account; the page also has the token generator you may need later.

  2. Add the server to Claude Code

    Run this in your terminal:

    claude mcp add scribelet --transport streamable-http https://api.scribelet.app/mcp

    The transport must be streamable HTTP, and the URL must include the /mcp path.

  3. Authorize and pick your desks

    The first time Claude Code calls a Scribelet tool, a consent screen opens in your browser. It names the agent, lists the scopes it is requesting and shows your desks. Select the desks the agent may access and click Allow. You can revoke this from AI Agent Connections at any time; the agent will re-authorize on its next request.

  4. Check the scopes match what you want to do

    The default grant is desks:read notes:read profile:read. Searching and reading work immediately. Creating or updating notes needs notes:write; reading memories needs memories:read. If a call fails with Insufficient scope, revoke the connection and authorize again; the agent can request broader scopes on the next attempt.

  5. Run a first prompt

    Ask something you know the answer to: "Search my Scribelet notes for 'on-call' and list the titles." If the titles are right, the connection and desk selection are correct. If it returns nothing, see the FAQ on desk access below.

  6. Optional: use an API token for scripts

    For an agent or script that cannot do OAuth, open AI Agent Connections, scroll to For Developers and click Generate MCP Token. Copy it immediately; it is shown once. Pass it as a Bearer token in the Authorization header to the same URL. Tokens grant all scopes, so treat them as secrets.

5 examples

What you can ask it to do

Prompts and workflows that work once the connection is live.

1.Load the project's decisions before touching code

When it fits: Use this at the start of a session on a module you have not worked on for weeks, when the reasons for the current design live in notes rather than in the code.

Load the project's decisions before touching codeExample 1

Prompt

Before changing anything in the billing module, search my Scribelet notes for "Paddle webhook" and "RevenueCat" and summarize every decision you find, with the note title and date for each. Then tell me which decisions the current code in backend/src/billing/ appears to contradict.

What happens

Claude Code calls search_notes for each phrase in your default desk (or the desk you name), reads the matching notes with get_note, and lists decisions with their source notes. Then it reads the code and compares. Typical output: three decisions from an October 2026 design note, one of which (idempotency keys stored for 30 days) is not implemented. You fix the code or update the note, and either way the two agree again.

Scopes needed: notes:read and search (the defaults).

2.Write an architecture decision record after a refactor

When it fits: Use this when you have just made a non-obvious choice and know you will not remember why in three months.

Write an architecture decision record after a refactorExample 2

Prompt

We just moved attachment extraction from the request path to a Kafka worker. Create a note in Scribelet titled "ADR: async attachment extraction, 2026-10-27" with sections Context, Decision, Alternatives considered, Consequences. Fill it from this session's diff and our discussion. Tag it adr and attachments. Link it to the existing note "Attachments pipeline" with a wikilink.

What happens

Claude Code drafts the ADR from the conversation and calls create_note with the title, Markdown content and tags. The [[Attachments pipeline]] wikilink in the body shows up in that note's backlinks panel, so anyone opening the pipeline note sees the decision that changed it.

Scopes needed: notes:write. If the consent screen only granted read scopes, the agent gets an "Insufficient scope" error; revoke and re-authorize, and it will request write access.

3.Keep a running work log while debugging

When it fits: Use this on a long debugging session where you want a record of what was tried, so the next person (or you tomorrow) does not repeat it.

Keep a running work log while debuggingExample 3

Prompt

Create a note "Debug log: flaky Kafka integration tests, 2026-10-27" tagged debugging. Every time we rule something out or find something in this session, append a timestamped bullet to it with update_note. Start with what we know: the failure is a 30 second startup timeout on the testcontainer, only under load.

What happens

The agent creates the note, then calls get_note and update_note as the session progresses, appending bullets such as "14:32 Not the Kafka config: same failure with defaults" and "15:05 Reproduces only when another suite holds the Docker VM". At the end you ask for a one-paragraph conclusion at the top. The log is searchable from the app on your phone when the same test fails next month.

Scopes needed: notes:read, notes:write.

4.Start every session with your memories

When it fits: Use this when you want the agent to know your conventions, people and project vocabulary without pasting them in each time.

Start every session with your memoriesExample 4

Prompt

Call retrieve_memories for "coding conventions" and "deploy process" in my Scribelet desk and treat the results as standing instructions for this session. Then list anything in them that conflicts with what you see in CLAUDE.md.

What happens

retrieve_memories does a semantic search over the facts, preferences and procedures Scribelet has remembered from your notes and chats (the same engine the in-app chat uses). The agent gets back items like "Deploys run from the repo root with ansible-playbook, never from deploy/" and "Never use git stash in this repo" and follows them. The conflict check catches a convention that changed in notes but not in the repo file.

Scopes needed: memories:read. To let the agent save new memories with create_memory, you need memories:write and the admin role on the desk.

5.Check what depends on a note before renaming it

When it fits: Use this when a runbook or design note is about to be renamed or split, and other notes link to it.

Check what depends on a note before renaming itExample 5

Prompt

I want to split the note "Runbook: consumer restart" into one runbook per environment. Use get_note_links to find every note that links to it, list them, and then propose the new titles and which backlinks should point where.

What happens

get_note_links returns the forward links and backlinks for the note. The agent lists the five notes that reference the runbook (two incident notes, a daily note, an onboarding checklist and a design doc), proposes Runbook: consumer restart (prod) and Runbook: consumer restart (staging), and maps each backlink. If you approve, it creates the two notes with create_note and updates the referring notes with update_note so no link breaks.

Scopes needed: notes:read, notes:write.

What a notes MCP server gives a coding agent

Claude Code is good at the code in front of it and blind to everything around it: why the queue was made async, what the on-call runbook says, which vendor you decided against in March. That context usually lives in notes, and the default way to supply it is to paste it into the prompt, session after session.

An MCP server for notes removes the paste step. The agent gets tools to search, read, link and write your notes, and calls them when a task needs them. With Scribelet the server is hosted, so there is no process to keep running, and the same notes are on your phone, which matters when you want to read the ADR the agent wrote on the train.

The tools available after you connect, as documented in the MCP server guide:

  • Notes: search_notes, search, get_note, list_recent_notes, create_note, update_note, delete_note, get_note_links, find_similar_notes
  • Memories: list_memories, retrieve_memories, create_memory, update_memory, delete_memory
  • Organization: list_desks, get_desk, list_tags, get_user_profile

Resources such as note://{desk_id}/{note_id} give read-only, URI-addressable access to a note as Markdown with frontmatter, and desk://{desk_id}/notes pages through recent notes.

Notes vs memories: what to put where

Treat them as two different kinds of context.

Notes are documents. An ADR, a runbook, a design doc, the notes from Tuesday's incident. They have titles, tags and [[wikilinks]], and the agent should read them when a task touches their subject. "Search for Paddle webhook decisions" is a notes question.

Memories are standing facts. "Deploys run from the repo root." "Priya owns the iOS release." "Never use git stash in this repo." Scribelet extracts these from your notes and chats, and retrieve_memories searches them by meaning. Load them at the start of a session; they are the part of CLAUDE.md you never got around to writing.

The failure mode to avoid is putting standing facts in a long note the agent has to find and read every time. If a fact is true across projects and weeks, let it become a memory. If it was true for one decision on one date, it is a note.

The permission model, briefly

OAuth 2.1 with scopes, granted per connection and per desk on a consent screen you see in the browser. The default grant is desks:read notes:read profile:read: enough to search and read, nothing else. Write access to notes is notes:write; memories have their own read and write scopes; insights:read exposes weekly insights. You can see every connection, its scopes and its last access on the AI Agent Connections page, and revoke any of them instantly.

An API token is the alternative for agents that cannot do OAuth. It grants all scopes and is shown once when generated. Use it for scripts, not for your daily agent.

A daily workflow

  1. Session start. "Retrieve my memories about this project and treat them as standing instructions." Thirty seconds, and the agent knows your conventions.
  2. Before a design change. "Search my notes for prior decisions on X and summarize with sources." Catches the decision you forgot you made.
  3. During long debugging. A running log note the agent appends to with update_note. Searchable later from any device.
  4. After a non-obvious choice. "Write the ADR" with create_note, tagged and linked to the component's note.
  5. Weekly. Open the Tags view, filter to the agent's tag, and read what it wrote. Correct or delete anything wrong; the agent's notes should meet the same bar as yours.

Troubleshooting

  • "Not authenticated." The token expired or was revoked. OAuth connections re-authorize on their own; for an API token, generate a new one.
  • Agent cannot find the server. Check the full URL including /mcp, and that the transport is set to streamable HTTP.
  • "Insufficient scope." The agent is trying something its grant does not cover. Revoke and re-authorize; it can request broader scopes next time. An API token sidesteps this at the cost of granting everything.
  • Connected but no notes. Desk scoping. Ask for list_desks, name the desk, or re-authorize with the right desk selected.

If you also want the agent to verify what it wrote against the repository rather than only against your notes, the GitHub connector lets Scribelet's verification check a note's claims against your code.

Tips

  • Start read-only

    The default OAuth scope is desks:read notes:read profile:read. Live with that for a week. You will learn what the agent actually looks up before you decide what it should be allowed to change.

  • Give agents their own desk, or a chosen few

    The consent screen lets you pick which desks the connection can see. A work desk for the agent and a personal desk it never touches is a clean split, and you can revoke the connection from Account > AI Agent Connections at any time.

  • Tag what the agent writes

    Ask for a tag like agent on every note Claude Code creates. The Tags view then gives you one list to review, and a search for notes without that tag is your own writing.

  • Ask for citations by note title

    When the agent summarizes decisions, ask it to name the note and date each came from. search_notes and get_note return the metadata; the agent will include it if you ask, and you can open the note from your phone to check.

  • Tell the agent to look in notes first

    One line in your project's CLAUDE.md, such as "Before proposing a design change, search Scribelet for prior decisions on the topic", changes how often the agent reaches for the server. Without it, the tools sit unused.

  • Prefer OAuth over an API token

    An API token grants every scope on every desk and cannot be narrowed. Use one only for scripts or agents that cannot do OAuth, store it like a password, and rotate it from the AI Agent Connections page if it leaks.

In the app

How to do this in Scribelet

  1. Open Account then AI Agent Connections to see every connected agent, when it last accessed your data and which scopes it holds. Revoke any connection with one click.

  2. Notes the agent creates appear in your desk like any other note, encrypted at rest, with their #tags and [[wikilinks]] live. Open one on your phone and the backlinks panel already lists what links to it.

  3. Memories the agent reads are the same ones the in-app chat uses. Review or edit them on the Memories screen; procedural memories ("always use bullet points") apply to the agent's retrievals too.

  4. Turn an agent-written action item into a tracked task by adding @due(2026-11-03) after it. It shows up in the Tasks view and on your daily note.

Start with the quick start if you are new to Scribelet.

Frequently asked questions

How do you run an MCP server for notes?

With Scribelet you do not run anything. The server is hosted at https://api.scribelet.app/mcp and speaks streamable HTTP, so a remote agent connects over the internet with OAuth. Community servers for Apple Notes or Obsidian run locally on your machine, which means they work only where that machine is and need their own install, runtime and config.

Is there an MCP server for Apple Notes or Obsidian?

Yes, several community projects. They are local servers: an Apple Notes one needs macOS and a JavaScript runtime, an Obsidian one needs the vault path and can clash with a filesystem server. They work well for a single desktop. Scribelet's server is hosted, uses OAuth scopes per desk, and the notes it writes are on your phone too, which is the main practical difference.

What is the difference between notes and memories for a coding agent?

Notes are documents: ADRs, runbooks, meeting notes, with titles, tags and links. Memories are short facts, preferences, people and procedures Scribelet has extracted from your notes and chats. An agent uses search_notes and get_note to read documents and retrieve_memories to pull standing context such as "deploys run from the repo root". Load memories at the start of a session, read notes when a task touches a topic.

Can Claude Code write notes, or only read them?

Both, if you grant notes:write on the consent screen. The write tools are create_note, update_note and delete_note (a soft delete you can restore). Memory writes (create_memory, update_memory, delete_memory) need memories:write and the admin role on the desk. The default grant is read-only.

The connection works but no notes appear. Why?

The OAuth connection is scoped to the desks you selected on the consent screen, and most tools default to your default desk if no desk_id is passed. Ask the agent to call list_desks and name the desk explicitly. If the desk you need was not selected, revoke the connection in AI Agent Connections and authorize again with it ticked.

Does this work with Cursor or other agents?

Yes. Any agent that supports streamable HTTP MCP servers can connect to the same URL. In Cursor you add the URL to .cursor/mcp.json (or ~/.cursor/mcp.json) and turn the server on from the Customize page. The Cursor integration page covers that setup; the tools and scopes are identical.

Give Claude Code the context it keeps asking you for

Run one command, pick the desks on the consent screen, and your coding agent can search your decisions, follow your links and write the ADR itself. Free plan, OAuth scopes you control.

Connect Claude Code
or get the app
Download on theApp Store

Free plan, no credit card. See pricing

Guide

Note Taking App for Developers: Markdown, MCP and Notes Checked Against Your Code

Developer notes fail in a specific way: they are right on the day they are written and quietly wrong six months later. This page says which tool fits which developer, what belongs in the repo instead, and a setup where notes are Markdown, your coding agent can read and write them over MCP, and runbooks get checked against the actual code.

Integration

Cursor + Scribelet: A Notes Integration for Your Coding Agent

Scribelet runs a hosted MCP server at `https://api.scribelet.app/mcp`. Add it to Cursor's `mcp.json`, approve the desks you want on Scribelet's consent screen, and Cursor's agent can search, read, create and update your notes. The same notes are on the web and your phone.

Integration

Notes App With GitHub Integration: Check Your Notes Against Your Code

Scribelet's GitHub integration does not sync your notes into a repository. It connects a repository through a GitHub App with read-only code search, so verification can check what a note claims (an endpoint, a flag, a command) against the actual code and propose a diff you accept or dismiss.

Docs

Mcp server

From the Scribelet docs

Article

Agentic coding

From the Scribelet blog

Article

Architecture decision record examples

From the Scribelet blog

We use cookies for analytics to improve your experience. Learn more