MCP tools reference

Korely's MCP server exposes 7 tools. Five are read-only (zero cost on the wallet, safe to call freely from agent loops). Two are write tools (save_note, create_task) that mutate the vault on disk.

Every tool's JSON schema is sent to the client during MCP handshake, so the agent knows the input shape automatically. This page is the human-readable version for when you're crafting prompts or wiring a custom integration.

Read tools

korely_search

Hybrid search across the vault. Combines full-text search (FTS5) with 768D nomic embeddings via Reciprocal Rank Fusion. Returns ranked snippets with source paths.

Input:

{
  "query": "string (required)",
  "limit": "number (default: 15, max: 50)",
  "folder_name": "string (optional, scopes to one folder)",
  "tag": "string (optional, filters by tag)"
}

Output (truncated example):

[
  {
    "id": "rn:0fb1...",
    "title": "Pricing discussion — Sept 2026",
    "snippet": "We decided to anchor Developer at $29...",
    "score": 0.87,
    "path": "Meetings/2026-09-12-pricing.md",
    "modified_at": "2026-09-12T14:23:00Z"
  },
  // ...
]

When to call it:

• User asks an open question that might have an answer somewhere in their vault.
• Before drafting any response that touches the user's past work.
• Default first step in any agentic vault interaction.

korely_read_item

Fetches the full content of a single note by ID. Use this after search when the snippet isn't enough.

Input:

{
  "item_id": "string (required, from search results)"
}

Output:

{
  "id": "rn:0fb1...",
  "title": "Pricing discussion — Sept 2026",
  "content": "# Pricing discussion\n\nFull markdown content here...",
  "folder_name": "Meetings",
  "tags": ["pricing", "decision"],
  "created_at": "2026-09-12T14:00:00Z",
  "modified_at": "2026-09-12T14:23:00Z"
}

korely_list_notes

Paginated browse of notes. Useful when the agent needs to scan a folder rather than search by keyword.

Input:

{
  "folder_name": "string (optional)",
  "tag": "string (optional)",
  "limit": "number (default: 20, max: 50)",
  "offset": "number (default: 0)"
}

Output: array of {id, title, folder_name, modified_at}.

korely_list_folders

Returns the folder structure of the vault. Helps the agent understand the user's organization before navigating.

Input: none.

Output: nested array of folder objects with names and child counts.

korely_get_related

The killer feature. Given an item ID, returns notes connected via shared entities in the auto-built knowledge graph. This is the difference between Korely and a plain vector DB: graph traversal surfaces lateral relationships, not just textual similarity.

Input:

{
  "item_id": "string (required)",
  "limit": "number (default: 10, max: 30)"
}

Output: array of related items with shared-entity counts.

Write tools

korely_save_note

Writes a new note to the vault. Markdown content, optional folder placement. If the folder doesn't exist, it's created.

Input:

{
  "title": "string (required)",
  "content": "string (required, markdown)",
  "folder_name": "string (optional, default: 'Inbox')"
}

Output:

{
  "id": "rn:abc1...",
  "path": "Inbox/2026-05-21-note-title.md",
  "ok": true
}

When to call it:

• User says "save this", "note that", "remember that".
• End of a conversation where the agent learned something worth keeping.
• Auto-summary after a long agent loop.

korely_create_task

Creates a task in the vault's Inbox folder. Tasks are notes with a specific frontmatter shape — they show up in the desktop app's task views (Today, Upcoming, etc.).

Input:

{
  "title": "string (required)",
  "due_date": "string (optional, ISO 8601 date)",
  "priority": "low | normal | high (optional, default: normal)"
}

Output:

{
  "id": "rn:def2...",
  "path": "Inbox/Task — title.md",
  "ok": true
}

Tool philosophy

Korely's tool surface is designed around the Obsidian MCP pattern: fine-grained primitives the agent composes, rather than coarse "do everything" calls.

That means an agent answering "what did we decide last quarter?" runs something like:

1. search("decision Q3") → 5 candidates
2. read_item(top_result) → full text
3. get_related(top_result) → 3 more linked notes
4. read_item(each) → full text
5. Synthesize answer with citations

Five tool calls in ~2 seconds, the agent has all the context, and you didn't pay a single Gemini/Claude inference on the server side (read tools are free — pure DB lookup).

Rate limits

On the Hobby tier (local MCP), there is no rate limit — the server runs as a child process on your machine, calls are sub-millisecond DB lookups.

On Developer ($29/mo) the cloud MCP enforces 10,000 requests/day. On Team ($99/mo) it's 100,000/day per workspace. Exceeded requests get 429 with a Retry-After header that resets at midnight UTC. See pricing for details.

Error responses

All tools return the MCP standard error envelope on failure:

{
  "error": {
    "code": -32602,
    "message": "Invalid params: limit must be 1-50"
  }
}

Common error codes: