MCP Integration

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

The MCP endpoint exposes the same reflective-memory contract as the local MCP server, running over Streamable HTTP with your API key for authentication. It speaks MCP 2026-07-28 and retains the 2025-11-25 handshake for existing clients.

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 kn_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	may mutate, may be destructive, not generally 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. Tool calls include human-readable content and typed structuredContent. A failed flow is returned as an MCP tool error (isError: true) instead of a successful string beginning with Error:.

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 (admin keys only)

Common state docs:

State	Purpose	Key params
`query-resolve`	Search with multi-step refinement	`query`, `tags`, `bias`, `since`, `until`
`get`	Retrieve a note with similar/meta/versions/edges context	`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 notes	`id` or `items`, `tags`
`delete`	Remove a note	`id`
`move`	Move versions between notes	`name`, `source`, `tags`
`stats`	Store profiling for query planning	`top_k`

Write keys can invoke the documented public state docs above. System-note targets (IDs beginning with .), inline YAML flows, custom stored state docs, and resumes of mutating cursors require an admin key. These checks apply equally to REST and MCP, including move source/target and bulk tag inputs.

keep_prompt

name:           "reflect"                  # prompt name (omit to list available)
text:           "auth flow"                # optional search context
id:             "now"                      # note 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.

Resources and prompts

Read-only note resources are available alongside the tools:

keep://now — current working note
keep://{id} — any note ID, percent-encoded when it contains URI punctuation

Prompt notes tagged with mcp_prompt are also exposed through native MCP prompts/list and prompts/get. This is the same store-driven catalog used by the local server.

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 pre-provisioned API keys as the REST API. Pass your key in the Authorization header as shown above. These keys are configured out of band; the hosted service does not currently advertise the optional MCP OAuth authorization profile or Protected Resource Metadata.

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.