Docs

Kept's local API and MCP server

Other apps and AI tools on the Mac that runs Kept can ask Kept questions, search its sources and list them. It's read-only: nothing can add, change or delete documents this way.

Off by default. Turn it on in Kept → Settings → Sharing.
This Mac only. Kept listens on 127.0.0.1:47822. Other computers can't reach it.
Keys. Every request needs Authorization: Bearer kept_…. Make one key per tool or person in Settings → Sharing. Each key is shown once; Kept stores only its SHA-256. Revoking a key stops it at once.
Limits. 120 requests a minute per key, 20 of them questions (a question runs the local model).
Licence. After the trial or subscription ends, ask and search return 402; listing still works.
Privacy. A tool that uses a cloud AI sends what Kept returns (answers and the passages they quote) to that AI's servers. Use a tool with a local model to keep everything on the Mac.

Set up a tool

Claude Code:

claude mcp add --transport http kept http://127.0.0.1:47822/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Cursor (.cursor/mcp.json) and other tools that take an mcpServers file:

{
  "mcpServers": {
    "kept": {
      "url": "http://127.0.0.1:47822/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

MCP

Endpoint: http://127.0.0.1:47822/mcp. Streamable HTTP with JSON responses, stateless: no event stream and no session IDs. Kept speaks both protocol eras:

2026-07-28 (stateless): send _meta["io.modelcontextprotocol/protocolVersion"] with every request, plus the MCP-Protocol-Version, Mcp-Method and, for tools/call, Mcp-Name headers. server/discover returns the supported versions, capabilities, server info and instructions. A header that doesn't match is -32020; an unsupported version is -32022 (both HTTP 400).
2025-03-26 to 2025-11-25: initialize, then notifications/initialized (202), then requests.

Tools

Tool	Input	Returns
`ask`	`question` (string, up to 2,000 characters)	`kind` (`grounded` or `notFound`), `answer` with `[n]` markers, optional `notice`, and `citations` (`number`, `source`, `category`, `pageStart`, `pageEnd`, `quote`)
`search`	`query`, optional `limit` 1–20 (default 6)	`passages` (`source`, `category`, pages, `heading`, `text`, `relevance` 0–1), best first
`list_sources`	none	`sources` (`id`, `name`, `type`, `category`, `status`, `pages`, `addedAt`)

All three are read-only and return structuredContent matching their outputSchema. Problems a model can act on (an empty question, an ended licence, the AI engine not running, the rate limit) come back as tool results with isError: true. An unknown tool is -32602.

HTTP API

Base URL http://127.0.0.1:47822/v1. JSON in and out; errors are {"error": "…"} with a status code.

Request	Body	Response
`GET /v1/status`		`app`, `version`, `business`, `sources`, `chatModel`, `license`, `canAsk`
`GET /v1/sources`		`{"sources": […]}`, as in `list_sources`
`POST /v1/search`	`{"query": "…", "limit": 6}`	`{"passages": […]}`, as in `search`
`POST /v1/ask`	`{"question": "…"}`	As in `ask`

curl http://127.0.0.1:47822/v1/ask \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How do I request leave?"}'

Status codes: 400 bad input, 401 missing or unknown key, 402 licence ended, 403 turned off, wrong Host or a website's Origin, 405 wrong method, 429 rate limit, 503 Kept's AI isn't set up or its engine isn't running. Questions asked through the API aren't added to Kept's own history.

Security notes

Host must be 127.0.0.1, localhost or [::1], which stops DNS rebinding. Any Origin must be a loopback http:// origin, so websites can't use the API; they also can't send Authorization without a CORS preflight, which Kept never approves.
Bodies over 64 KB are refused unread.