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

Alternative: Use a Setup Link

Instead of manually generating an API key and editing config files, you can create a one-time setup link from Settings > MCP Setup Links. Share this link with your AI assistant or open it in your MCP client — it handles authentication automatically without exposing API keys directly.

Each setup link can only be used once and expires after use
Give the link a label (e.g., “Claude Desktop — work laptop”) so you can track and revoke access later
Revoke any setup link from Settings if you need to disconnect a client

2. Configure Your MCP Client (Manual)

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 70+ MCP tools grouped by category. All tools are scoped to the authenticated user's workspace and 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)
`append_to_note`	Append content to end of note with newline separator	id (required), content (required, max 100k)
`split_note`	Split a note into multiple notes at heading boundaries	id (required)

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)
`find_duplicates`	Find potentially duplicate notes using semantic similarity	(none)
`orphan_notes`	Find notes with no wikilinks or backlinks	(none)

Organization

Tool	Description	Parameters
`manage_tags`	Add or remove tags on a note (YAML frontmatter)	id (required), add (optional), remove (optional)
`list_tags`	List all tags in the workspace with usage counts	(none)
`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
`move_folder`	Move a folder to a new parent	id (required), parentId (required, null for root)
`pin_note`	Pin a note to the top of its folder list	id (required)
`unpin_note`	Unpin a previously pinned note	id (required)
`toggle_star`	Toggle the starred status of a note	id (required)
`list_pinned`	List all pinned notes in the workspace	(none)
`list_starred`	List all starred notes in the workspace	(none)

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)
`set_importance`	Set importance score on a note for prioritized retrieval	id (required), score (required)
`set_provenance`	Record the origin/source of a note	id (required), provenance (required)
`get_provenance`	Get the provenance metadata for a note	id (required)

Navigation & Context

Tool	Description	Parameters
`get_note_links`	Get outgoing wikilinks and backlinks for a note	noteId (required)
`get_backlinks`	Get all notes that link to a given note	noteId (required)
`get_workspace_summary`	Workspace overview: totals, folder tree, recent activity, top tags	(none)
`get_kb_stats`	Knowledge base statistics and health metrics	(none)
`context_fetch`	Fetch context from a URL for use in notes	url (required)
`daily_digest`	Get a summary of recent note activity	(none)

Knowledge Graph

Tool	Description	Parameters
`create_node`	Create a knowledge graph node (entity)	label (required), type (required), noteId (optional)
`create_edge`	Create a typed relationship between two nodes	sourceId (required), targetId (required), type (required)
`delete_node`	Delete a knowledge graph node	id (required)
`delete_edge`	Delete a relationship between nodes	id (required)
`get_neighbors`	Get nodes connected to a given node	nodeId (required)
`query_graph`	Search the knowledge graph by type, label, or relationship	type (optional), label (optional), relationship (optional)
`query_note_graph`	Get the subgraph connected to a specific note	noteId (required)
`populate_graph`	Auto-generate graph nodes and edges from a note	noteId (required)
`graph_traverse`	Walk the graph from a starting node with depth control	startNodeId (required), depth (optional)
`find_path`	Find shortest path between two nodes in the graph	sourceId (required), targetId (required)
`extract_entities`	Extract entities from note content using AI	noteId (required)
`knowledge_link`	Create a typed relationship between knowledge entries or notes	sourceId (required), targetId (required), type (required)

Knowledge Management

Tool	Description	Parameters
`knowledge_store`	Store a knowledge entry with embeddings for semantic retrieval	content (required), metadata (optional)
`memory_upsert`	Create or update a memory note by key	key (required), content (required)
`note_summary`	Generate an AI summary of a note	id (required)
`related_notes`	Find semantically related notes	id (required), limit (optional)
`knowledge_ingest`	Bulk ingest content into the knowledge base	entries (required)
`knowledge_decay`	Apply time-based decay to knowledge relevance scores	(none)
`recall_knowledge`	Retrieve knowledge entries by semantic similarity	query (required), limit (optional)
`scan_knowledge_conflicts`	Scan for contradictions across notes	(none)
`get_knowledge_conflicts`	Get previously detected knowledge conflicts	(none)
`synthesize_notes`	Synthesize multiple notes into a single summary	noteIds (required)
`get_clusters`	Get topic clusters from note embeddings	(none)
`generate_moc`	Generate a Map of Content (MOC) note for a topic	topic (required)

AI & Suggestions

Tool	Description	Parameters
`ask_notes`	Ask a question answered from your notes (RAG)	question (required)
`suggest_tags_links`	Get AI-suggested tags and wikilinks for a note	id (required)
`suggest_tags`	Get AI-suggested tags for a note	id (required)

Smart Folders

Tool	Description	Parameters
`list_smart_folders`	List all smart folders with their filter rules	(none)
`create_smart_folder`	Create a dynamic folder with filter rules	name (required), rules (required)
`delete_smart_folder`	Delete a smart folder	id (required)

Object Types

Tool	Description	Parameters
`list_object_types`	List all defined object types with their property schemas	(none)
`set_note_type`	Assign an object type to a note with property values	noteId (required), typeId (required), properties (optional)
`query_by_type`	Find notes of a specific object type	typeId (required)

Workspaces

Tool	Description	Parameters
`list_workspaces`	List all workspaces with note and folder counts	(none)
`create_workspace`	Create a new workspace	name (required), description (optional)
`setup_workspace`	Create a workspace with a template (e.g., remedy-pod)	name (required), template (optional)
`set_active_workspace`	Set the active workspace for the MCP session	id or slug (required)
`get_workspace_context`	Get rich context: metadata, folder tree, recent notes, top tags	(none)
`update_workspace`	Update workspace name, description, or icon	id (required), name / description / icon (optional)
`delete_workspace`	Delete a workspace (notes move to default)	id (required)

Version History

Tool	Description	Parameters
`list_versions`	List all saved versions of a note	noteId (required)
`get_version`	Get the content of a specific version	versionId (required)
`restore_version`	Restore a note to a previous version	versionId (required)

Tasks

Tool	Description	Parameters
`list_tasks`	List markdown tasks (checkboxes) across notes	status (optional: all/done/pending)
`toggle_task`	Toggle a task checkbox in a note	noteId (required), taskIndex (required)

Bulk Operations

Tool	Description	Parameters
`bulk_tag`	Add or remove tags on multiple notes at once	noteIds (required), add (optional), remove (optional)
`bulk_move`	Move multiple notes to a folder	noteIds (required), folderId (required)
`bulk_archive`	Archive multiple notes	noteIds (required)

Recipes & Automation

Tool	Description	Parameters
`list_recipes`	List available automation recipes	(none)
`run_recipe`	Run an automation recipe	recipeId (required), params (optional)

Session & Files

Tool	Description	Parameters
`session_log`	Log a message to the current MCP session trace	message (required)
`save_conversation`	Save a conversation transcript as a note	title (required), messages (required)
`list_sessions`	List recent MCP session traces	limit (optional)
`get_session_replay`	Get full replay of a session trace	sessionId (required)
`upload_file`	Upload a file attachment to a note	noteId (required), file (required)
`list_timeline`	Get timeline of recent activity across notes	limit (optional)

NoteType enum: note, prompt, template, reference, log, memory, spec, plan. Object types extend this with custom schemas.

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.