nocal Docs

MCP Server

Reference details for the nocal MCP server, including available tools, write-safety rules, and security guidance.

Reference

What the nocal MCP server exposes

Use this page as the technical reference for the nocal MCP server. It covers the currently available note tools, the write constraints clients need to respect, and the security model around token handling.

Tools Reference

Compact reference for the current note tool surface.

5 tools
Tool

notes_search

Description

Full-text search across user notes with ranked snippets.

Arguments
  • queryrequired
  • limitoptional, 1-20
Tool

notes_list_recent

Description

List recently modified notes, optionally scoped to a folder.

Arguments
  • limitoptional, 1-50
  • folder_idoptional
Tool

notes_get

Description

Read one note by id including content and metadata.

Arguments
  • note_idrequired
Tool

notes_create

Description

Create a new note from ProseMirror JSON and persist synced ydoc state.

Arguments
  • titlerequired
  • content_pmrequired
  • folder_idoptional
  • after_note_idoptional
  • idempotency_keyoptional
Tool

notes_patch

Description

Apply targeted ProseMirror insert/delete operations to existing note content.

Arguments
  • note_idrequired
  • patchesrequired
  • expected_last_modifiedrequired
  • schema_hashrequired
  • idempotency_keyoptional

Write Safety

Optimistic Concurrency

notes_patch requires expected_last_modified. If the note changed, fetch latest content and retry.

Idempotency

Write tools accept idempotency_key so retries can safely reuse prior results.

Schema-Aware Writes

Call notes_get_schema before writes and pass the returned schema_hash.

Security Note

A pre-auth URL includes your token directly in the URL. Treat it like a password. If exposed, rotate your MCP token immediately.

Related Setup

Need to connect a client first? Use the setup guide for Claude, ChatGPT, Cursor, or VS Code.

Open Connect Agents