Concepts
MCP vs REST
Which surface to use for what. The mental model that makes the rest of the docs make sense.
There are two surfaces because agents and automations work differently. An agent picks a tool inside a conversation. An automation runs a predetermined sequence of HTTP calls. The two shapes want different APIs.
The rule of thumb
| You are building | Use |
|---|---|
| A Claude, Cursor, or n8n connector that lets an AI read and add items to a knowledge base | MCP |
| A script that needs to list, organize, move, or delete content | REST API |
| A webhook that ingests a URL when something triggers (Drive upload, Twilio call, and so on) | REST API (POST /api/v1/ingest). The same shape as MCP add_to_knowledge, but easier to wire from plain HTTP. |
| A Zapier or n8n flow that needs full library management | REST API |
Why MCP does not have update or delete
This is deliberate, not an oversight. A tool call has to make sense as something an LLM would invoke in conversation. "Search my notes" works. "Move item 47b3 from folder A to folder B" does not. You would have to tell the AI out loud what to do, which defeats the agent pattern.
Folder and item management is a human and automation operation. It belongs on the REST surface. The split keeps each surface focused:
- The agent has a small, fast tool vocabulary.
- The automation has a complete CRUD interface.
The split table
| Operation | MCP | REST |
|---|---|---|
| Search the knowledge base | yes | no |
| Get one item | yes | yes |
| List recent items | yes | no |
| List items with filters | no | yes |
| Add a URL or text | yes | yes |
| Add audio, video, PDF, or image | no | yes (three-step signed URL) |
| Delete an item | no | yes |
| Add item to folders | no | yes |
| Remove item from folder | no | yes |
| List folders | no | yes |
| Create or delete a folder | no | yes |
What is the same across both
- Auth: the same
lev_…bearer token works on either surface. - Capabilities:
readcovers MCP read tools and REST GETs.writecovers MCPadd_to_knowledgeand REST POSTs and DELETEs. - Scope: a token carries a folder scope, either whole library or a specific list of folders. Both surfaces honor it.
- Rate limits: per-token and per-endpoint. Read endpoints get 1000/hr. Writes get tighter caps.