MCP Integration

Connect AI assistants to your KeepNotes memory via the Model Context Protocol.

The MCP endpoint exposes 9 reflective-memory tools — the same tools available in the local MCP server, running over streamable-http with your API key for authentication.

Client configuration

Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "keepnotes": {
      "url": "https://api.keepnotes.ai/mcp/",
      "headers": {
        "Authorization": "Bearer knk_your_api_key_here"
      }
    }
  }
}

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Tools

9 tools, all prefixed keep_ to avoid collision with other MCP servers:

Tool	Description	Annotations
`keep_put`	Store text, URL, or document in memory	idempotent
`keep_find`	Search by natural language query	read-only
`keep_get`	Retrieve item with full context (similar items, parts, versions)	read-only
`keep_now`	Update current working context	idempotent
`keep_tag`	Add, update, or remove tags on an item	idempotent
`keep_delete`	Permanently delete an item	destructive
`keep_list`	List recent items with optional filters	read-only
`keep_move`	Move versions between items	—
`keep_prompt`	Render an agent prompt with context injected	read-only

All tools return human-readable strings. Errors are returned as strings (never raised to the protocol layer).

keep_put

content:  "Text to store" or "https://example.com/doc"
id:       optional custom ID
summary:  optional (skips auto-summarization)
tags:     {"topic": "auth", "project": "myapp"}
analyze:  true to decompose into searchable parts

URIs (http://, https://, file://) are fetched and indexed automatically.

keep_find

query:  "natural language search"
tags:   {"project": "myapp"}       # filter (all must match)
limit:  10                          # max results
since:  "P3D" or "2026-01-15"     # time filter
until:  "P1D" or "2026-02-01"

keep_get

id:  "now"         # current working context
id:  "%a1b2c3"    # specific item

Returns YAML frontmatter with similar items, meta sections, parts manifest, and version history.

keep_now

content:  "Current state, goals, decisions"
tags:     {"project": "myapp"}

To read current context, use keep_get with id="now".

keep_tag

id:    "%a1b2c3"
tags:  {"topic": "new-value", "old-tag": ""}   # empty string deletes

keep_delete

id:  "%a1b2c3"

keep_list

prefix:  ".tag/*"                  # ID prefix or glob
tags:    {"project": "myapp"}
since:   "P7D"
until:   "2026-02-01"
limit:   10

keep_move

name:          "my-topic"          # target (created if new)
source_id:     "now"               # default
tags:          {"topic": "auth"}   # filter which versions to move
only_current:  true                # just the tip, not history

keep_prompt

name:   "reflect"                  # prompt name (omit to list available)
text:   "auth flow"                # optional search context
id:     "now"                      # item for context injection
tags:   {"project": "myapp"}       # filter search results
since:  "P7D"
until:  "2026-02-01"
limit:  5

Returns the rendered prompt with {get} and {find} placeholders expanded with live context. See KEEP-PROMPT.md for details.

Agent workflow

An MCP agent's session looks like this:

Start: keep_prompt("session-start") — get current context and open commitments
Work: Use keep_find, keep_get, keep_put, keep_now, keep_tag as needed
Reflect: keep_prompt("reflect") — structured review of actions and outcomes
Update: keep_now with new intentions, keep_put for learnings, keep_move to organize

The prompt tools provide the when and why; the other tools provide the how.

Authentication

The MCP endpoint uses the same API keys as the REST API. Pass your key in the Authorization header as shown above.

Rate limits, usage tracking, and project scoping all work identically to the REST API.

Example usage

Once configured, your AI assistant can use keepnotes tools directly:

"Search my notes for anything about the Q3 budget review"

The assistant calls keep_find with {"query": "Q3 budget review"} and gets back semantically matched notes.

"Remember that Kate prefers aisle seats"

The assistant calls keep_put with {"content": "Kate prefers aisle seats"}.

Local MCP server

For local-only usage without an API key, see keep mcp (local) — the same 9 tools running as an stdio server. Use one or the other, not both — the tools share the same names, so installing both would give the agent duplicate tools and unpredictable routing.