MCP Server - nocal Docs

Server Overview

Endpoint

https://api.nocal.app/mcp

Auth

Authorization: Bearer YOUR_NOCAL_TOKEN

Pre-auth URL

https://api.nocal.app/mcp?token=YOUR_NOCAL_TOKEN

Transport

HTTP MCP endpoint. Use a bridge for clients that only support stdio.

Protocol

JSON-RPC 2.0 MCP methods and simple REST-style tool envelope are supported.

Provider Setup

ChatGPT

Enable Developer Mode / custom MCP connectors in your ChatGPT workspace settings.
Create a new custom app/connector and select MCP server.
Set endpoint to https://api.nocal.app/mcp.
Set authentication to Bearer and provide your nocal token.
Save and select the connector in your chat.

Claude

Open Settings -> Connectors.
Click Add Custom Connector.
Paste https://api.nocal.app/mcp?token=YOUR_NOCAL_TOKEN as the URL.
Save and use the nocal connector in chat.

Gemini

For Gemini MCP clients that use stdio server definitions, route nocal through mcp-remote.

{
  "mcpServers": {
    "nocal": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.nocal.app/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer ${NOCAL_TOKEN}"
      ],
      "env": {
        "NOCAL_TOKEN": "YOUR_NOCAL_TOKEN"
      }
    }
  }
}

VS Code

In VS Code, open MCP config via MCP: Open Workspace Folder MCP Configuration (or user config) and add this server:

{
  "servers": {
    "nocal": {
      "type": "http",
      "url": "https://api.nocal.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NOCAL_TOKEN}"
      }
    }
  }
}

Cursor

Add nocal to project .cursor/mcp.json or global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nocal": {
      "url": "https://api.nocal.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NOCAL_TOKEN}"
      }
    }
  }
}

Tools Reference

notes_search

Full-text search across user notes with ranked snippets.

Arguments: query (required), limit (1-20, optional).

notes_list_recent

List recently modified notes, optionally scoped to a folder.

Arguments: limit (1-50, optional), folder_id (optional).

notes_get

Read one note by id including content_raw and metadata.

Arguments: note_id (required).

notes_create

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

Arguments: title (required), content_pm (required), folder_id, after_note_id, idempotency_key.

notes_append

Append ProseMirror content to an existing note with conflict checks.

Arguments: note_id (required), append_pm (required), expected_last_modified (required), idempotency_key.

notes_edit

Replace full content or apply patch operations against existing content.

Arguments: note_id (required), expected_last_modified (required), plus either content_pm or patch, and optional idempotency_key.

Write Safety and Conflicts

Optimistic concurrency: notes_append and notes_edit require expected_last_modified. If the note changed, the server returns a content conflict.

Idempotency: write tools accept idempotency_key. Replays with identical arguments reuse the prior result; changed arguments with the same key return conflict.

Content transform: write tools transform ProseMirror JSON to HTML + ydoc before persistence to keep note content and collaborative state aligned.

Quick JSON-RPC Example

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "notes_search",
    "arguments": {
      "query": "Q2 planning",
      "limit": 5
    }
  }
}

Security Note

A pre-auth URL includes your token directly in the URL. Treat it like a password, do not share it, and rotate your MCP token if the URL is exposed.

Recommended GPT Instructions

Paste this into your custom GPT instructions (or your first prompt) for reliable, safe note updates.

You can use the nocal MCP tools to read and write my notes.

Working rules:
- Prefer notes_search and notes_list_recent to find the right note before editing.
- Before mutating a note, call notes_get and keep note_id + last_modified_date.
- For updates, use:
  - notes_append to add sections.
  - notes_edit to replace/patch existing content.
- Always pass expected_last_modified for append/edit calls.
- Use a unique idempotency_key for each write attempt.
- If you receive a conflict, re-fetch with notes_get, merge, and retry once.
- Summarize exactly what changed after each write.