Connect your agent

Getting started in Claude

Add Very Simple Notes to Claude once, and Claude can read and write your notes in any chat.

1. In Claude, open Customize, then Connectors.
2. Press + and choose Add custom connector.
3. Name it Very Simple Notes and paste https://verysimplenotes.com/mcp. Press Add.
4. Press Connect and sign in with Apple or Google, the same account as in the app.
5. Ask Claude something like "put milk and bread on my shopping list".

It works the same in Claude on the web, on desktop and on your phone. Claude plans can add custom connectors, and the free plan allows one. You can see and revoke the connection in the app under Account.

In Claude Code, add it from the terminal, then run /mcp to sign in:

claude mcp add --transport http very-simple-notes https://verysimplenotes.com/mcp

MCP server and tools

Server URL: https://verysimplenotes.com/mcp (Streamable HTTP). Any MCP client that supports OAuth connects on its own: a call without a token answers 401 and points at /.well-known/oauth-protected-resource, the client registers itself and sends the person to sign in. A token from the app's Account works too, as Authorization: Bearer TOKEN.

• list_notes: list notes, active, archived or all.
• read_note: one note with its Markdown body.
• create_note: a new note, title and Markdown body.
• edit_note: change the title, the whole body, or the star.
• archive_note: archive or unarchive a note.
• delete_note: delete a note for good.

The tools follow the same rules as the REST API below: reading always works, and writing needs the person's active subscription.

REST API quickstart

If you are an agent acting for a person: tell them you want to connect to Very Simple Notes, then do this.

1. If you can speak MCP, use the MCP server instead; it handles sign-in for you.
2. If you have an OAuth client_id, open the authorize URL (below). They sign in with Apple or Google. You exchange the code for a token.
3. If you do not, ask them to open Very Simple Notes, go to Account, create a token, and paste it to you.
4. Call GET /api/v1/me with that token. If it returns the person, you are connected.
5. List, read, create, and edit notes. They write on the phone. You write too.

curl https://verysimplenotes.com/api/v1/me \
  -H "Authorization: Bearer TOKEN"

Authentication

Every call to /api/v1 needs a personal API token as a Bearer token. The token is scoped to one person. They can revoke it in the app under Account. Tokens do not expire on their own.

Authorization: Bearer TOKEN

Writing (create and edit) needs an active subscription. Reading does not. A lapsed subscription answers 402 on writes, with subscription_required.

GET /me

Connect check. Who this token belongs to.

GET https://verysimplenotes.com/api/v1/me
Authorization: Bearer TOKEN

{
  "id": "…",
  "email": "…",
  "name": "…"
}

DELETE /me

Revoke this token. Call it before you store a new one on reconnect, so Account does not fill with dead rows. A token that is already gone answers 401, which is the same end state.

DELETE https://verysimplenotes.com/api/v1/me
Authorization: Bearer TOKEN

{ "ok": true }

GET /notes

List notes. Query filter=active|archived|all (default active). Newest edit first. preview is a short plain-text snippet of the body, not the full Markdown.

GET https://verysimplenotes.com/api/v1/notes?filter=active
Authorization: Bearer TOKEN

{
  "notes": [
    {
      "id": "…",
      "title": "Shopping",
      "preview": "- [ ] Milk",
      "archived": false,
      "important": false,
      "updatedAt": "2026-09-11T12:00:00.000Z"
    }
  ]
}

GET /notes/:id

One note, including the Markdown body.

GET https://verysimplenotes.com/api/v1/notes/NOTE_ID
Authorization: Bearer TOKEN

{
  "id": "…",
  "title": "Shopping",
  "body": "- [ ] Milk\n- [ ] Eggs",
  "archived": false,
  "important": false,
  "createdAt": "2026-09-01T09:00:00.000Z",
  "updatedAt": "2026-09-11T12:00:00.000Z"
}

POST /notes

Create a note. Body { title?, body? }. Missing fields become empty strings. Needs an active subscription.

POST https://verysimplenotes.com/api/v1/notes
Authorization: Bearer TOKEN
Content-Type: application/json

{ "title": "Dinner", "body": "- [ ] Roast a chicken" }

Returns the full note, 201.

PATCH /notes/:id

Update a note. Send only the fields you want to change: title, body, archived, important. Needs an active subscription.

PATCH https://verysimplenotes.com/api/v1/notes/NOTE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

{ "body": "- [x] Roast a chicken" }

Returns the full note.

POST /notes/:id/archive

Hide a note from the active list. Same as PATCH with archived: true.

POST https://verysimplenotes.com/api/v1/notes/NOTE_ID/archive
Authorization: Bearer TOKEN

POST /notes/:id/unarchive

Put an archived note back on the active list.

POST https://verysimplenotes.com/api/v1/notes/NOTE_ID/unarchive
Authorization: Bearer TOKEN

DELETE /notes/:id

Permanently delete a note. This cannot be undone.

DELETE https://verysimplenotes.com/api/v1/notes/NOTE_ID
Authorization: Bearer TOKEN

{ "ok": true }

Markdown

body is Markdown. The person never sees the syntax; the app renders it. When you write, use:

• **bold** and *italic*
• - bullets and 1. numbered
• - [ ] unchecked and - [x] checked checklist items

Errors

• 401 missing or bad token ({"error":"Unauthorized"})
• 402 write without a subscription ({"error":"subscription_required"})
• 400 invalid JSON body on PATCH
• 404 no such note

OAuth 2.0

An app can obtain a token without a paste. The person signs in on verysimplenotes.com; your server swaps the code for the same kind of personal API token. Discovery: /.well-known/oauth-authorization-server.

GET https://verysimplenotes.com/oauth/authorize
  ?client_id=…
  &redirect_uri=…
  &response_type=code
  &state=…
  &code_challenge=…
  &code_challenge_method=S256

POST https://verysimplenotes.com/oauth/token
  grant_type=authorization_code
  code=…
  redirect_uri=…
  client_id=…
  client_secret=…
  code_verifier=…

→ { "access_token": "…", "token_type": "Bearer", "scope": "notes" }

PKCE S256 is supported. Optional label on authorize names the token in Account (for example Agent Heim · Freja).

MCP clients and other public apps register themselves at POST /oauth/register (dynamic client registration) and must use PKCE S256; they get no secret. Building an app with its own server and a client secret? Email verysimple@portfoliobox.net for a client_id. Agent Heim is already registered.