MCP Integration

Connect AI assistants to m-notes via the Model Context Protocol (MCP). Supports Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code Copilot.

For automated agent setup, point your AI assistant to https://mnotes.framework.by/api/agent-setup — it returns a machine-readable setup guide.

1. Generate an API Key

Open Settings > API Keys
Click Generate to create a new API key
Copy the key immediately — it is only shown once

2. Configure Your MCP Client

m-notes uses Streamable HTTP transport at /api/mcp. Replace YOUR_M_NOTES_URL with your m-notes URL (e.g., https://m-notes.app) and YOUR_API_KEY with the key from step 1.

Claude Code

Add .mcp.json to your project root:

.mcp.json

{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "YOUR_M_NOTES_URL/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Or use the CLI one-liner:

bash

claude mcp add m-notes --transport http \
  --url YOUR_M_NOTES_URL/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/)

claude_desktop_config.json

{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "YOUR_M_NOTES_URL/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Add .cursor/mcp.json to your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "YOUR_M_NOTES_URL/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

mcp_config.json

{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "YOUR_M_NOTES_URL/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code Copilot

Add .vscode/mcp.json to your project root. Note: VS Code uses servers (not mcpServers) and requires "type": "http".

.vscode/mcp.json

{
  "servers": {
    "m-notes": {
      "type": "http",
      "url": "YOUR_M_NOTES_URL/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3. Tool Reference

m-notes exposes 18 MCP tools grouped by category. All tools are scoped to the authenticated user's data.

CRUD

Tool	Description	Parameters
`create_note`	Create a new note	title (required, max 500), content (optional, max 100k), folderId (optional)
`update_note`	Update an existing note	id (required), title / content / folderId (all optional, folderId: null unsets)
`delete_note`	Delete a note by ID	id (required)
`list_notes`	List all notes, optionally filtered by folder or type	folderId (optional), type (optional)
`get_note`	Get a single note by ID with full content	id (required)
`get_note_by_title`	Find note by title (case-insensitive, partial match)	title (required)
`get_notes`	Batch-fetch by IDs (max 10) or paginate all notes	ids (optional), cursor (optional)

Search

Tool	Description	Parameters
`search_notes`	Fulltext, semantic, or hybrid search with relevance scoring	query (required), mode (hybrid/fulltext/semantic), limit (1-20), tags, folderId, type
`search_by_tags`	Find notes matching tags (any or all)	tags (required), match (any/all), limit (1-100)
`get_recent_notes`	Notes modified since a given timestamp	since (ISO 8601, required), limit (1-100)

Organization

Tool	Description	Parameters
`manage_tags`	Add or remove tags on a note (YAML frontmatter)	id (required), add (optional), remove (optional)
`list_folders`	List all folders with hierarchy and note counts	(none)
`manage_folders`	Create, rename, or delete a folder	action (create/rename/delete), id, name, parentId

Metadata

Tool	Description	Parameters
`get_note_frontmatter`	Parse YAML frontmatter from a note as JSON	id (required)
`set_note_frontmatter`	Merge key-value pairs into frontmatter (null removes key)	id (required), fields (required)

Navigation

Tool	Description	Parameters
`get_note_links`	Get outgoing wikilinks and backlinks for a note	noteId (required)
`get_workspace_summary`	Workspace overview: totals, folder tree, recent activity, top tags, type counts	(none)

Content

Tool	Description	Parameters
`append_to_note`	Append content to end of note with newline separator	id (required), content (required, max 100k)

NoteType enum: note, prompt, template, reference, log, memory, spec, plan

4. Workflow Recipes

Orient your AI agent

Start every session with get_workspace_summary to understand the workspace, then search_notes for task-specific context, and get_note_links to follow wikilinks.

Store project decisions

Use create_note with a descriptive title, then set_note_frontmatter with { "type": "memory" }, and manage_tags to add #decision.

Build a running journal

Create a note once, then use append_to_note to add entries over time. Content is appended with a newline separator automatically.

Find related context

Use search_notes with mode: "hybrid" for best results, then get_note_links to discover connected notes through wikilinks and backlinks.

Tag-based knowledge retrieval

Use search_by_tags with tags like #decision, #spec, #architecture, #learning, #prompt. Set match: "all" to require every tag, or match: "any" (default) for at least one.

CLAUDE.md snippet

Add this to your project's CLAUDE.md to instruct Claude Code to automatically use m-notes as a knowledge base:

CLAUDE.md

## Knowledge Base (m-notes)

This project uses m-notes as its knowledge base via MCP.

**Before starting work on any task:**
1. Call `get_workspace_summary` to orient yourself
2. Call `search_notes` with task-related keywords

**When making decisions:**
- Record with `create_note` (type: memory, tag: #decision)
- Append progress to log notes with `append_to_note`

**When completing work:**
- Update relevant spec/plan notes if implementation diverged
- Add learnings with `create_note` (type: memory, tag: #learning)

Troubleshooting

Connection refused: Make sure m-notes is running and the URL in your config matches your server address and port. Test with curl YOUR_M_NOTES_URL/api/health.
401 Unauthorized: Verify the Authorization header is Bearer YOUR_API_KEY (not just the key). Check the key has not been revoked in Settings > API Keys.
Tool not found: Ensure you are connecting to /api/mcp (not /api/mcp/sse). Restart your MCP client after config changes. Check tool names match exactly (e.g., search_notes not searchNotes).
Transport compatibility: m-notes uses Streamable HTTP transport (not SSE, not stdio). All major MCP clients support this natively. If your client only supports SSE or stdio, you will need a transport bridge.