> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elanotes.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Search and list return handles, provenance, and coverage. Fetch a body only with GET /v1/notes/{note} (line slice) or /raw.
> Read coverage before treating a result set as complete. Zero hits with coverage is a valid answer.
> Follow error hint. Writes need an Idempotency-Key header and agent_id.
> The user creates personal access tokens in web Settings → Access tokens. Read is included; authenticated note mutations require notes.write. Supplying agent_id does not grant permission.
> Reuse an Idempotency-Key only for an identical retry. After VERSION_MOVED, re-read and submit the changed operation with a new key.
> Local MCP is read-only. Authenticated Cloud MCP adds write_note and edit_note only with notes.write and connected write storage; open local mode skips the permission check. Inspect tools/list before calling conditional tools.
> A queued write has not changed the note. Record pending_id. Authenticated GET /v1/writes/{id} also requires notes.review; write-only tokens must hand the ID to a reviewer.
> Leave approval to a human. Agents must not approve their own proposals or request review permission merely to finish a task. The API permits review-scoped personal tokens; this is a workflow rule.
> Cloud paths never return private/ notes. Coverage names the exclusion.
> Production origin is https://api.elanotes.com. baseUrl has no /v1 suffix.

# MCP tools

> MCP tool arguments, local and cloud availability, and HTTP equivalents. Cloud writes require notes.write and connected write storage.

Local MCP is the shared read registry. Cloud MCP mounts that same registry, then adds `write_note` and `edit_note` with connected write storage and `notes.write` in authenticated mode. Open local mode skips the permission check. Inspect `tools/list` before calling conditional tools; valid read-only tokens connect without write tools. Neither server has a folders tool. Folders are HTTP `GET /v1/folders`. Create credentials through [Access tokens](/access-tokens).

A cloud or desktop session **binds `vault_id` and overwrites** a caller-supplied value. Pass the arguments below. Do not rely on naming a different vault.

Config: [MCP local](/mcp-local) (stdio) and [MCP cloud](/mcp-cloud) (`POST /mcp`).

| Tool | Where | Role | Arguments agents set | HTTP |
| - | - | - | - | - |
| `search_notes` | local and cloud | Ranked handles for a topic. No note text. | `query` (required), `limit` (default 20, max 100), `min_seq`, `filter` | `GET /v1/search` (`q` is `query`) |
| `grep_notes` | local and cloud | Line matches for an exact pattern. | `pattern` (required), `path_glob`, `case_insensitive` (default false), `literal` (default false), `limit` (default 20, max 200), `min_seq`, `filter` | `GET /v1/grep` |
| `read_note` | local and cloud | Line-numbered body. The only read tool that returns note text. | `note` (slug or id), `version_id`, `start_line`, `end_line`, `response_format` (`detailed` or `concise`, default `detailed`), `cursor` | `GET /v1/notes/{note}` |
| `get_attachment` | local and cloud | URL and metadata for an embed. Bytes are not inline. | `file_name`, optional `sha256` | `GET /v1/attachments/{file_name}` |
| `list_notes` | local and cloud | Browse by path. | `prefix`, `cursor`, `limit` (default 50, max 500), `exhaustive` (default false), `archived` (default false), `filter` | `GET /v1/notes` |
| `list_tags` | local and cloud | Frontmatter tags and note counts. Body `#hashtags` are not tags. | `filter` | `GET /v1/tags` |
| `query_notes` | local and cloud | Filter, sort, group, and aggregate frontmatter. Does not read bodies. | `filters` (default `[]`), `sort`, `group_by`, `aggregate`, `limit` (default 50, max 200) | `POST /v1/query` |
| `get_links` | local and cloud | Backlinks, forward links, tags, supersessions. | `note`, `direction` (`forward`, `back`, or `both`, default `both`), `depth` (1–3, default 1), `kinds` | `GET /v1/notes/{note}/links` |
| `recent_changes` | MCP only | Newest immutable versions. | `since` (ISO timestamp), `limit` (default 20, max 500) | none |
| `index_status` | local and cloud | Per-layer index progress. No single ready flag. | none | `GET /v1/index/status` |
| `vault_info` | local and cloud | Note count, excluded folders, link-graph health. | none | `GET /v1/vault` |
| `write_note` | cloud, with write storage and `notes.write` (or open mode) | Create or replace a note with full markdown. | `path`, `content`, `agent_id` (default `mcp`), `idempotency_key` | `POST /v1/notes` |
| `edit_note` | cloud, with write storage and `notes.write` (or open mode) | Replace one exact string, pinned to `version_id`. | `note`, `version_id`, `old_string`, `new_string`, `agent_id` (default `mcp`), `idempotency_key` | `POST /v1/notes/{note}:edit` |

`get_attachment` on the cloud returns a presigned URL. On local MCP the URL is a file path. `query_notes` is the structured frontmatter query, the same contract as `POST /v1/query`.

`filter` on `search_notes`, `grep_notes`, `list_notes`, and `list_tags` is the same AIP-160 string as `GET /v1/notes?filter=`. See [API overview](/api/overview).

`min_seq` is a write's `committed_seq`. The tool waits, bounded, for the index to reach it, or answers with `coverage.stale`.

`write_note` and `edit_note` follow write policy and budget. Personal-token writes use actor `pat:<prefix>`, regardless of the supplied `agent_id`. Reuse `idempotency_key` only for an identical retry.

A queued MCP result contains `status` and `pending_id`; it does not include the HTTP `slug`. An applied MCP result includes note/version/hash and sequence fields, but no embedded HTTP `note`. Inspect `status` first.

`status: "queued"` means the note has not changed. Record and report `pending_id`. In authenticated mode, polling `GET /v1/writes/{id}` also requires `notes.review`; a write-only token must hand the ID to a reviewer. Approve and reject stay on HTTP. The API accepts review-scoped personal tokens, but agents must leave approval to a human and must not request review permission merely to finish a proposal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.