MCP Integration

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

The MCP endpoint exposes 3 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

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

Tool	Description	Annotations
`keep_flow`	Run any operation as a state-doc flow	idempotent
`keep_prompt`	Render an agent prompt with context injected	read-only
`keep_help`	Browse keep documentation	read-only

All operations (search, put, get, tag, delete, move, stats) go through keep_flow with named state docs. All tools return human-readable strings. Errors are returned as strings (never raised to the protocol layer).

keep_flow

state:          "query-resolve"                    # state doc name
params:         {query: "auth", bias: {now: 0}}    # flow parameters
budget:         3                                   # max ticks
token_budget:   2000                                # token-budgeted rendering
cursor:         "abc123"                            # resume a stopped flow
state_doc_yaml: "..."                               # inline YAML (custom flows)

Common state docs:

State	Purpose	Key params
`query-resolve`	Search with multi-step refinement	`query`, `tags`, `bias`, `since`, `until`
`get-context`	Retrieve item with similar/meta/versions/edges	`item_id`
`find-deep`	Search with edge traversal	`query`
`put`	Store content or index a URI	`content` or `uri`, `tags`, `id`
`tag`	Apply tags to one or more items	`id` or `items`, `tags`
`delete`	Remove an item	`id`
`move`	Move versions between items	`name`, `source`, `tags`
`stats`	Store profiling for query planning	`top_k`

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"
deep:           true                       # follow tags to discover related items
scope:          "file:///path/to/dir*"     # constrain results to ID glob
token_budget:   3000                       # token budget for search context

Returns the rendered prompt with placeholders expanded. Supports {get}, {find}, {text}, and {binding_name} placeholders (when the prompt doc has a state tag referencing a state doc flow). See KEEP-PROMPT.md for prompt details.

keep_help

topic:  "index"                    # documentation topic (default: index)

Browse keep documentation. Call with topic="index" to see all available topics.

Agent workflow

An MCP agent's session looks like this:

keep_prompt(name="session-start")                                              # 1. Start
keep_flow(state="query-resolve", params={query: "topic"}, token_budget=2000)   # 2. Search
keep_flow(state="put", params={content: "insight", tags: {type: "learning"}})  # 3. Capture
keep_prompt(name="reflect")                                                     # 4. Reflect
keep_flow(state="put", params={content: "next steps", id: "now"})              # 5. Update

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_flow with {state: "query-resolve", params: {query: "Q3 budget review"}} and gets back semantically matched notes.

"Remember that Kate prefers aisle seats"

The assistant calls keep_flow with {state: "put", params: {content: "Kate prefers aisle seats"}}.

Local MCP server

For local-only usage without an API key, see keep mcp (local) — the same 3 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.