MCP Tools Reference

Comprehensive documentation for all 23 Model Context Protocol (MCP) tools provided by SNotes.

The SNotes MCP server exposes 23 standardized tools for notes management, checklist item handling, and collection grouping.

Every tool operates with strict permissions, accessing only the notes owned by the authenticated account.

Tool Annotations

Each MCP tool provides execution hints to help AI models plan actions safely:

readOnlyHint: Indicates safe, non-mutating query tools (get_note, list_notes, list_collections).
destructiveHint: Warns models before executing permanent deletion actions (delete_note, empty_trash, delete_checkbox, delete_collection).
idempotentHint: Indicates that executing the tool multiple times with the same arguments produces the identical outcome.

1. Note Management Tools

`list_notes`

List the user's active notes, newest first. Excludes archived and trashed notes.

Annotations: readOnly: true, idempotent: true
Parameters:
- limit (integer, optional, default 20, max 100): How many notes to return.
- offset (integer, optional, default 0): How many notes to skip.

`list_archived_notes`

List notes that have been archived.

Annotations: readOnly: true, idempotent: true
Parameters:
- limit (integer, optional): Results limit.
- offset (integer, optional): Results offset.

`list_trashed_notes`

List notes currently in the trash, most recently trashed first.

Annotations: readOnly: true, idempotent: true
Parameters:
- limit (integer, optional): Results limit.
- offset (integer, optional): Results offset.

`get_note`

Fetch one note in full, including checklist items and attachment transcription text.

Annotations: readOnly: true, idempotent: true
Parameters:
- note_id (UUID string, required): The unique ID of the note.

`create_note`

Create a new note. For a checklist, pass note_type: "checklist" and add rows with add_checkbox.

Parameters:
- title (string, max 255): Note title.
- content (string): Body text in markdown. (Must be empty for checklist notes).
- note_type (string, enum: ["text", "checklist"], default "text"): Note type.
- color (string, max 7): Hex color code (e.g. "#fde68a"), or null.
- is_pinned (boolean): Pin to the top of the grid.

`update_note`

Change a note's title, body, color, or pinned state. Only provided fields are modified.

Annotations: idempotent: true
Parameters:
- note_id (UUID string, required): The note ID.
- title (string, max 255): New title.
- content (string): New body markdown (text notes only).
- color (string, max 7): New hex color code.
- is_pinned (boolean): Pinned status.
- expected_updated_at (ISO 8601 string): Timestamp for optimistic concurrency control.

`trash_note`

Soft-delete a note to the trash. It can be recovered with restore_note.

Annotations: idempotent: true
Parameters:
- note_id (UUID string, required): The note ID.

`restore_note`

Bring a trashed note back to the top of the active notes list.

Annotations: idempotent: true
Parameters:
- note_id (UUID string, required): The note ID.

`archive_note`

Move a note into the archive or unarchive it. Archiving automatically unpins the note.

Parameters:
- note_id (UUID string, required): The note ID.
- archived (boolean, optional): true to archive, false to unarchive. Omit to toggle.

`pin_note`

Pin a note to the top of the list or unpin it.

Parameters:
- note_id (UUID string, required): The note ID.
- is_pinned (boolean, optional): true to pin, false to unpin. Omit to toggle.

`delete_note`

Permanently destroy a note and all attached media. Skips the trash and cannot be undone.

Annotations: destructive: true, idempotent: true
Parameters:
- note_id (UUID string, required): The note ID.

`empty_trash`

Permanently destroy every note currently in the trash.

Annotations: destructive: true, idempotent: true
Returns: {"deleted": <count>}

2. Checklist Tools

`add_checkbox`

Append or insert a row into a checklist note.

Parameters:
- note_id (UUID string, required): The checklist note ID.
- label (string, max 500, required): Task description.
- is_checked (boolean, default false): Initial checked state.
- order (integer, optional): Zero-indexed insertion position. Omit to append at the end.

`update_checkbox`

Update label or tick/untick a checklist row.

Annotations: idempotent: true
Parameters:
- note_id (UUID string, required): The checklist note ID.
- checkbox_id (UUID string, required): The checkbox item ID.
- label (string, max 500, optional): New label.
- is_checked (boolean, optional): Ticked status. (Omit both to toggle is_checked).

`delete_checkbox`

Remove a row from a checklist note.

Annotations: destructive: true, idempotent: true
Parameters:
- note_id (UUID string, required): The checklist note ID.
- checkbox_id (UUID string, required): The checkbox item ID.

3. Collection Tools

`list_collections`

List all collections with note counts.

Annotations: readOnly: true, idempotent: true
Parameters:
- limit (integer, optional): Results limit.
- offset (integer, optional): Results offset.

`get_collection`

Fetch single collection metadata by ID.

Annotations: readOnly: true, idempotent: true
Parameters:
- collection_id (UUID string, required): The collection ID.

`create_collection`

Create a new collection, optionally populating it with existing notes.

Parameters:
- name (string, max 100, required): Collection name (unique).
- color (string, max 7, optional): Hex color code.
- note_ids (array of UUID strings, optional): Notes to add immediately.

`update_collection`

Rename or recolor a collection.

Annotations: idempotent: true
Parameters:
- collection_id (UUID string, required): The collection ID.
- name (string, max 100, optional): New name.
- color (string, max 7, optional): New hex color.

`delete_collection`

Delete a collection. (Notes inside are retained).

Annotations: destructive: true, idempotent: true
Parameters:
- collection_id (UUID string, required): The collection ID.

`list_collection_notes`

List the active notes belonging to a collection.

Annotations: readOnly: true, idempotent: true
Parameters:
- collection_id (UUID string, required): The collection ID.
- limit (integer, optional): Limit.
- offset (integer, optional): Offset.

`add_notes_to_collection`

Add one or more notes into a collection.

Annotations: idempotent: true
Parameters:
- collection_id (UUID string, required): The collection ID.
- note_ids (array of UUID strings, required): List of note IDs to add.

`remove_note_from_collection`

Remove a note from a collection.

Annotations: idempotent: true
Parameters:
- collection_id (UUID string, required): The collection ID.
- note_id (UUID string, required): The note ID.

Example: JSON-RPC 2.0 Tool Invocation

The following payload illustrates how an MCP client sends a tools/call request over HTTP POST to https://api.snotes.io/v1/mcp:

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "title": "Meeting Summary",
      "content": "Discussed EU privacy compliance and MCP deployment.",
      "color": "#fde68a",
      "is_pinned": true
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"note\": {\"id\": \"4d673bf8-5c4e-4f51-bca2-8db48ce83259\", \"note_type\": \"text\", \"title\": \"Meeting Summary\", \"content\": \"Discussed EU privacy compliance and MCP deployment.\", \"color\": \"#fde68a\", \"is_pinned\": true, \"archived\": false, \"trashed_at\": null, \"checkboxes\": [], \"categories\": [], \"media\": [], \"reminder_at\": null}}"
      }
    ]
  }
}

MCP Tools Reference

On this page