The endpoint
- URL:
POST https://api.loreindex.ca/mcp - Transport: streamable HTTP, stateless — every request is self-contained, so there is no session to establish or keep alive.
- Auth: an interactive OAuth 2.1 flow for agents that can open a browser, or a bearer API key for headless use — see Authentication below.
Authentication
Interactive agents (Claude Code, Claude Desktop, Cursor, …) authenticate over OAuth 2.1. Point the agent at the endpoint URL and run its authenticate command; a browser opens the Lore Index consent screen, where you sign in and pick exactly which capabilities the agent may use — the scope picker offers read, propose, and write, and the token is granted only the scopes you tick. There is no key to copy or store, and you can revoke access at any time.
Headless environments (CI, server-side agents that can't do an interactive sign-in) use a bearer API key: Authorization: Bearer <api-key>. Generate keys on the Connect page; each key carries read / propose / write scopes. Either way, lore_propose over MCP always routes to human review, regardless of the granted scope.
The five tools
Lore Index exposes five tools for your agent.
| Tool | What it does |
|---|---|
lore_bootstrap | Loads your compiled guidance pack — the active MUST and SHOULD rules for your scopes, as markdown. Call it once at session start. |
lore_search | Full-text search over active entries in your scopes. Returns dense id | priority | title | snippet lines, ranked by relevance with a priority boost. Accepts query, optional tags/type, and a limit — 5 by default, up to 50 per call. Want more than five? Raise limit (max 50) or refine the query; there is no cursor pagination, so an agent widens the limit or searches again rather than paging. |
lore_get | Fetches one entry by id — full body plus a provenance line (source, status) so the agent can judge how current and trustworthy it is. |
lore_propose | Submits a new entry. Over MCP it always lands as pending_review for a human to approve — regardless of the key's scope — and returns the new id plus a review URL. |
lore_whoami | Reports the identity the key acts as and what the credential may do: name, teams, roles, account access level, the key/token's effective capabilities (read/propose/write), and the scopes it may write to. |
The bootstrap pack
lore_bootstrap returns a compact markdown pack: the active, non-expired MUST and SHOULD entries in the caller's scopes, grouped by type (instructions, preferences, facts, contacts, glossary) with each line ending in its (id:…). context-priority entries are never in the pack.
The pack is capped at ~1,500 tokens, estimated as characters ÷ 4. Entries are selected narrow-scope-first with MUST before SHOULD, and once the budget is reached the lower-priority tail is dropped — so the most specific, most binding guidance always survives the cap. The pack is compiled once and cached server-side; it is marked stale (and recompiled on next call) whenever an entry or membership changes. Treat it as a point-in-time snapshot: rely on it for standing context, but run a fresh lore_search for any specific question.
The pack closes with a ## Tags line — the distinct tags across the lore in the caller's scopes. It is a compact map of which topics the workspace has governed knowledge about, so an agent can tell when a task touches one and run a lore_search before acting on it. The tag line is budgeted inside the same ~1,500-token cap and truncated last, so it never displaces a MUST (or any) entry.
REST parity
MCP is not a separate implementation. Every tool calls the same services under apps/api/src/services that power the REST /v1/* routes, so scoping, ranking, authorization, and audit behave identically through either door. The one deliberate difference: over MCP, lore_propose always routes to human review, whereas a write-scoped key on the REST API can create an active entry directly.
The agent skill
SKILL.md is a teachable guide that turns the five tools into a working habit for an agent. It teaches when to reach for Lore Index (any organization-specific question — policies, conventions, contacts, glossary, “how we do X here”) and how to use the tools well:
- Call
lore_bootstraponce at session start and keep the pack as standing context. - Run a fresh
lore_searchbefore answering org-specific questions, thenlore_getthe entries you need in full. - Treat MUST entries as binding constraints; SHOULD entries as strong defaults.
- Cite the entry ids you relied on so decisions stay auditable.
- Never assume write access —
lore_proposedurable knowledge for human review.
Where to install it
Download SKILL.md with the button above, then put it where your agent looks for skills. Every client below has a first-class skill mechanism: a per-skill folder holding the file, where the folder name (lore) becomes the skill's name — matching the name: lore in the file's frontmatter.
Drop the file at this path — the folder name (lore) becomes the skill's name and it loads automatically. Use the project path to commit it to a repo, or the ~ path to make it available everywhere.
.claude/skills/lore/SKILL.md # project, committed with the repo
~/.claude/skills/lore/SKILL.md # user-wide, all projects