@vectros-ai/mcp-server 0.16.1 → 0.17.1

package/CHANGELOG.md

@@ -3,6 +3,246 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.17.1 — 2026-09-17
+
+### Security
+
+- **README no longer instructs committing a live API key.** Both "Configure manually" examples
+  (Claude Desktop and Claude Code) led with a JSON snippet embedding a real `ssk_live_...` value,
+  and the Claude Code section explicitly said to commit the resulting `.mcp.json` "to share the
+  server with the repo" — on the page that renders as this package's npm landing page. Both
+  sections now lead with the keyring-based config (no `env` block, no secret in the file — the
+  server resolves the key from the local `vectros` CLI keyring, same as before) and explicitly warn
+  against committing a config that does carry a real key.
+
+### Added
+
+- **All 23 tools now declare MCP annotations** (`readOnlyHint`/`destructiveHint`/`idempotentHint`)
+  in the actual `tools/list` response, not just their own source — a host previously had nothing
+  to gate a confirmation prompt on, so every tool looked alike including the deletes and the
+  batch-write. Annotated per tool against what its handler actually calls, not its name:
+  - Reads with no real-money leg (`hybrid_search`, `record_get`/`_query`/`_batch_get`,
+    `document_get`/`_query`, `folder_query`, `list_schemas`, `current_identity`,
+    `lookup_principal`, `version_history`) are `readOnlyHint: true`.
+  - `rag_ask` and `document_ask` are **not** read-only: both reserve an atomic hold against the
+    caller's prepaid inference balance before generation and debit it on completion, which can
+    trigger a configured auto-recharge against a payment method on file. Also not idempotent —
+    every repeat charges again, and generation is non-deterministic.
+  - `record_create`, `document_ingest`, and `record_batch_write` each dedupe by an OPTIONAL
+    `externalId` — supplying it makes a retry converge, omitting it does not — so all three are
+    annotated for that less-safe default (`idempotentHint: false`), not the safer opt-in;
+    `document_ingest` and `record_batch_write` are additionally flagged destructive because their
+    `upsert:true` paths overwrite existing content.
+  - `folder_create` is idempotent **only when the caller supplies `slug` explicitly** — an omitted
+    slug is derived through a collision-probing suffix loop that returns only a value already
+    proved free, so a retry with no `slug` creates a new sibling folder rather than converging.
+    Annotated `idempotentHint: false` for that default, the same standard as the optional-key
+    create tools above.
+  - The three `*_update` tools (JSON Merge Patch) and the three `*_delete` tools are all flagged
+    destructive.
+
+  Verified against the real, over-the-wire `tools/list` response from the compiled binary, not the
+  source that builds it.
+
+### Fixed
+
+- **`document_ingest` in file mode now works against an API that makes presigned upload URLs
+  single-use.** Such an API bakes a conditional-write header into the upload URL's signature and
+  names it in the upload response (`requiredHeaderName` / `requiredHeaderValue`); the tool's PUT
+  omitted it, so storage rejected the upload with a 403 and the tool reported the document as
+  created but incomplete. The tool now sends whatever header the response names, and no extra
+  header when the response names none, so it works against API versions on either side of the
+  change.
+
+- **A failed startup could abort the whole process with a native Windows crash instead of the
+  server's own exit code.** Both entry points (`vectros-mcp-server`, `vectros-mcp-server-http`)
+  end EVERY startup failure path — a missing/invalid credential, a bad `--` env config, a rejected
+  `GET /v1/ping` check (enabled by default; `VECTROS_MCP_SKIP_PING_VALIDATION` to opt out) — with a
+  raw `process.exit()`. On Windows, an async operation still settling (a `fetch` for the ping check;
+  an `execFile` spawn out to the local CLI keyring helper for credential resolution) when
+  `process.exit()` runs can race libuv and abort the process, printing an `Assertion failed` line
+  and replacing the real exit code with `127` — the same class of defect fixed in `@vectros-ai/cli`
+  around the same time. Every startup-failure exit in both files now sets `process.exitCode` and
+  lets the event loop drain naturally, instead of hard-exiting.
+
+  This needed one adjustment `@vectros-ai/cli`'s equivalent fix didn't: both entry points register
+  `SIGINT`/`SIGTERM` handlers for graceful shutdown, and Node keeps a process alive for as long as
+  either signal has a registered listener. Registering them before the connect attempt would mean a
+  failed connect never actually exits under the new idiom — it hangs forever instead, waiting for a
+  signal that will never come. Both files register those handlers only after a successful connect,
+  so a failed startup still exits promptly; the alternative (register early, make the shutdown
+  handler itself exit-code-safe too) doesn't work here, because the ping check's underlying fetch
+  has no timeout and no cancellation — that path trades the crash for a possible silent hang on a
+  stuck connection instead of fixing it.
+
+- **Two integration tests carried an internal issue number and internal review-process wording**
+  (a bare tracker reference in two test names/comments describing the exit-code fix above, and one
+  comment describing a defect an earlier internal review pass had caught). This package's GitHub
+  source mirror ships `tests/` verbatim, so both leaked into the public repo. Reworded to
+  self-contained descriptive text; no behavioral change.
+
+- **Four more source comments carried an internal workstream/finding code**, on the base-URL
+  SSRF/credential-exfil guard in `cli.ts`, `cli-http.ts`, `server.ts`, and its test — found on a
+  later sweep with a wider scan pattern. The substantive rationale was already self-contained in
+  each comment; only the bare internal code was dropped. No behavioral change.
+
+- **One more source comment on that same base-URL guard named a sibling package's file by
+  monorepo-relative path** (`base-url.ts`'s own doc comment, describing that the same guard is
+  ported into another package's CLI) — found by a post-merge audit. Reworded to describe the
+  sibling generically. No behavioral change.
+
+- **One source comment named an internal backend class by name** (`record_query.ts`, describing
+  how a composite field's identity is joined on the backend). Reworded to describe the mechanism
+  without the class name. No behavioral change.
+
+### Docs
+
+- **`current_identity`'s capability-gap list now includes `trigger-control-plane-grant`**, the
+  sixth named `granted_capabilities` value, alongside the five it already tracked. **`document_get`'s
+  `downloadUrl` description now notes the platform always forces `attachment` disposition** on
+  download, so a caller expecting inline rendering of a safe type knows to expect a save prompt
+  instead. No behavior changed — both were description-only gaps.
+
+### Changed
+
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.44.0`.
+
+## 0.17.0 — 2026-09-07
+
+### Added
+
+- **`record_batch_write`** — create or upsert up to 50 structured records in one call,
+  wrapping `POST /v1/records/batch` (API 0.43.0: previously a `501` stub, now live).
+  Use it instead of N `record_create` round-trips when you hold several records.
+  Items may mix types, and each one goes through the same schema validation,
+  `externalId` idempotency, unique-field enforcement and `records:c:<type>` scope
+  check as a single create, applied per item against that item's own type — a batch
+  is not a way to write a type your credential could not write one at a time.
+  `atomicity: "all_or_nothing"` commits every item in one transaction and writes
+  nothing at all if any item fails, which is a better failure shape for an agent than
+  a loop of creates that half-succeeds; the default `best_effort` writes each item
+  independently. The item vocabulary deliberately mirrors `record_create` (`type` +
+  `fields`), so nothing new has to be learned to use it.
+
+  **The call reports success whenever the batch was *processed* — including when
+  every item failed.** That is the endpoint's own contract, so the tool does not
+  fake an error result; read the per-item `results` (matched to what you sent by
+  `index`) and the `succeeded`/`failed` counts. Per-item `status` carries two values
+  beyond the ordinary outcomes, and they call for different remedies:
+  `forbidden` (your credential lacked the scope or ownership that item needed — fix
+  the credential, not the item) and `not_committed` (this item was fine, but an
+  `all_or_nothing` batch was aborted by a different one).
+
+- **`record_query` can list by `folderId`, and serve the account-wide `recent` feed.**
+  Two list-mode selectors the API has carried on `GET /v1/records` for many releases
+  but this tool never exposed: `folderId` lists every record filed in a folder
+  regardless of type (combine with `type` for one type within one folder), and
+  `recent: true` returns the recently-updated feed across all types — the only way to
+  read records without naming a type. `record_create` has always accepted `folderId`,
+  so until now a record could be filed into a folder and never listed back out of it.
+
+  This matters more from 0.43.0 on, because `folder_delete` now refuses a folder that
+  still holds records and the supported way to find them is exactly this call.
+  `type` is consequently optional now: a lookup (`field`) still requires it, a list
+  with no selector at all is refused, and `recent` is refused alongside
+  `type`/`folderId`/`userId`/`scope` rather than silently ignoring them the way the
+  API does.
+
+- **`scopeFilters` on `hybrid_search` and `rag_ask`** — narrow a search or a RAG
+  retrieval by more than one ownership dimension at once, e.g.
+  `["org:<id>", "client:<id>"]` for one specific client within one specific org.
+  Something `scope` alone could not express, for a credential whose access spans
+  several dimensions. Mutually exclusive with `scope`; passing both is refused
+  locally with a message naming both fields, rather than spending a round trip on
+  the API's own rejection.
+
+### Changed
+
+- **`folder_delete` now states its emptiness precondition** — the folder must contain
+  no documents, **no records**, and no sub-folders, and the description says how to clear
+  each: a document can be moved out or deleted, a record can only be deleted (nothing on
+  this surface moves one), and a sub-folder cannot be re-parented, so nesting must be
+  cleared innermost-first. The description previously named only protected folders, so
+  the most common way this call fails read as impossible.
+
+  **API 0.43.0 widened the refusal, and it lands harder on this server than on most
+  callers.** The old guard saw sub-folders and *file-backed* documents only — it was blind
+  to *text-ingested* documents and to records, and a delete that hit one of those returned
+  success while orphaning the contents behind a folder id that no longer resolved.
+  Text-inline ingest is `document_ingest`'s default path, so folders this server filled are
+  precisely the ones whose deletes used to succeed and now do not.
+
+  One consequence worth planning for: the emptiness check counts **everything** in the
+  folder, including items the calling credential cannot read. A scoped credential can be
+  refused by content it has no way to enumerate, so a refusal that contradicts your own
+  listing is expected rather than a bug.
+- **`rag_ask`'s `truncationWarning` now carries `truncatedCount` and `noContentCount`**,
+  and its `reason` can be `no_groundable_content` or `context_window_budget_and_no_content`
+  as well as `context_window_budget`. Results can be dropped before the prompt is built
+  for two independent reasons — not fitting the context window, or having no groundable
+  text at all — and these separate them. Inherited from the API with no code change here;
+  noted because it is new data an agent sees.
+- **`hybrid_search`'s ARCHIVED note now covers records, and stops claiming an absolute.**
+  It said ARCHIVED *documents* never appear in results, which read as an asymmetry implying
+  archived records still match — they do not, and have refused to index since API 0.35.
+  API 0.43.0 additionally fixed two document write paths that could silently re-index an
+  already-archived document. But it deliberately does **not** sweep items already stranded
+  in that state: they stay searchable until written to again. So "never appear" was a false
+  absolute, and the description now names the repair — re-send `status: "ARCHIVED"` on the
+  item — instead of implying the case cannot arise.
+- **A search hit's returned `createdAt` is documented as the INDEX timestamp.** It is the moment
+  the item entered the search index — the same moment it was created in the common case, but later
+  for anything re-indexed since — so it should not be reported to a user as the creation time; fetch
+  the item with `document_get`/`record_get` for that. The `createdAfter`/`createdBefore` FILTERS are a
+  separate thing and are unchanged: they filter on the item's true creation time, which does not move
+  when it is re-indexed, with a bounded allowance that lets an item matched on its FIRST index be
+  checked against its index time instead (clock skew between creating and indexing).
+- **`folder_delete` no longer implies a record cannot be moved.** It said a record must be deleted
+  because it cannot be re-filed. The API supports re-filing one (`folderId` is patchable); it is
+  *this server* that does not expose it — `record_update` has no `folderId` argument. As written, an
+  agent clearing a folder could have deleted partner data where a move was available, then reported
+  that a move was impossible. It now names the gap as this server's and says to move the record
+  through the API/SDK rather than deleting it here.
+- **`record_batch_write` no longer claims duplicate `externalId`s within one batch are refused.**
+  That holds under `atomicity: "all_or_nothing"` only. Under the default `best_effort` each item is
+  written independently, so a second item carrying the same `externalId` matches what the first just
+  wrote and reports `updated` — a duplicated key silently collapses two rows into one, counted as a
+  success. Both modes are now described.
+- **`record_create` / `record_batch_write`: `scopes` is bounded by `data_scope`, not by identity.**
+  Both said the values "must come from the credential's own identity". The platform states the
+  opposite: identity supplies the DEFAULT when you state none and does not limit which value you may
+  state; each entry must fall inside the `data_scope` of a granting clause. The old wording would
+  stop an agent setting a scope it was entitled to set.
+- **`record_query` rejects `folderId`/`recent` on a lookup** instead of ignoring them, matching the
+  existing guard for lookup arguments passed without `field`.
+- **Bundled `@vectros-ai/sdk` repinned to the 0.43.0 line.**
+
+### Notes
+
+- **A root `sk_*` key can no longer file into a non-`default` app context.** As of API
+  0.43.0, a `folderId` / `parentFolderId` — or a document's `schemaId` — belonging to
+  another context is refused with a uniform `400`, on `document_ingest`,
+  `document_update`, `record_create`, `record_update` and `folder_create`. Those calls
+  previously succeeded, but never coherently: a root key's writes are stamped
+  `default`, so the row landed in `default` while its folder or schema lived elsewhere.
+  Existing rows are unaffected. Use a scoped key bound to the target context — the
+  credential this server recommends anyway. See README § Recommended credential.
+- **A `filters` clause on `status` means something different for records now.** Records
+  no longer publish their lifecycle `status` into the search index (API 0.43.0), so on
+  `hybrid_search` / `rag_ask` a `status` filter matches a schema's own `status` field
+  where one is declared, and nothing where none is — it no longer collides with the
+  platform's lifecycle value. Record schemas can now use `status` as a filterable field
+  of their own.
+- **0.43.0 capabilities this server deliberately does not expose:** stored scripts and
+  synchronous script execution, trigger rules, trigger-failure history, and usage
+  reporting. The reasoning is in README § What this server deliberately doesn't expose
+  — briefly: authoring stored code is a design-time act rather than a data-plane one;
+  declaring a trigger rule grants live authority; trigger-failure and usage reporting
+  are operational questions for a person, not mid-task tool calls; and synchronous
+  script execution has a failure surface (an undetermined-outcome run, and an
+  idempotency key a tool call has no natural identity for) that needs a deliberate
+  design rather than a thin wrapper.
+
 ## 0.16.1 — 2026-08-27
 
 ### Fixed

package/README.md

@@ -123,6 +123,29 @@ Precision is the pitch — what this server deliberately does *not* do:
 
 ## Configure manually (Claude Desktop or any MCP client)
 
+If `@vectros-ai/cli` is installed **globally** (`npm install -g @vectros-ai/cli`,
+not a one-off `npx` run — the server needs `vectros` to still be on `PATH`
+later, when IT runs, not just while bootstrap ran) and you've run
+`vectros bootstrap` with it, omit the `env` block entirely — the server
+resolves your key from the local `vectros` CLI keyring automatically (see
+[Credential resolution](#credential-resolution) below). `vectros login` alone
+does **not** do this — it stores a separate sign-in session, not this key —
+so `bootstrap` is the step that actually has to have run:
+
+```json
+{
+  "mcpServers": {
+    "vectros": {
+      "command": "npx",
+      "args": ["-y", "@vectros-ai/mcp-server"]
+    }
+  }
+}
+```
+
+No CLI installed, or a machine you can't log in on? Set the key directly
+instead:
+
 ```json
 {
   "mcpServers": {
@@ -137,34 +160,53 @@ Precision is the pitch — what this server deliberately does *not* do:
 }
 ```
 
+This file lives under Claude Desktop's own per-user app-support directory,
+not a shared repo — but a real key pasted into it is still a live secret at
+rest: don't paste it into a chat, ticket, or screenshot with the value
+intact, and prefer the keyring form above whenever you can.
+
 Restart Claude Desktop. The agent now sees the Vectros tools and
 two resources as callable surfaces.
 
 ## Configure manually (Claude Code)
 
-Claude Code reads a project-scoped `.mcp.json` with the same shape — drop this
-at your project root (commit it to share the server with the repo):
+Claude Code reads a project-scoped `.mcp.json` with the same shape.
+**Never commit a real key into it** — `.mcp.json` is exactly the kind of file
+teams check in to share a project's tooling, and a live `ssk_*`/`sk_*` value
+inside it is a credential leak the moment it lands in git history, not just
+if the repo is public.
+
+The way to share this config safely: commit the entry with **no `env` block
+at all**, and let each developer's own `vectros` CLI keyring supply the key
+(see [Credential resolution](#credential-resolution) below — this is the
+same delegation `git credential` / `docker-credential-*` use). This needs
+each teammate to have `@vectros-ai/cli` installed **globally** and to have
+run `vectros bootstrap` with it — `npx`-ing the CLI once, or running
+`vectros login` alone (a separate sign-in session, not this key), leaves
+nothing on `PATH` or in the keyring for the server to find later:
 
 ```json
 {
   "mcpServers": {
     "vectros": {
       "command": "npx",
-      "args": ["-y", "@vectros-ai/mcp-server"],
-      "env": {
-        "VECTROS_API_KEY": "ssk_live_..."
-      }
+      "args": ["-y", "@vectros-ai/mcp-server"]
     }
   }
 }
 ```
 
-Or let Claude Code's CLI write it for you:
+Or let Claude Code's CLI write that keyring-based entry for you:
 
 ```bash
-claude mcp add vectros -e VECTROS_API_KEY=ssk_live_... -- npx -y @vectros-ai/mcp-server
+claude mcp add vectros -- npx -y @vectros-ai/mcp-server
 ```
 
+If a machine genuinely has no `vectros` CLI installed, you can pass the key
+directly with `-e VECTROS_API_KEY=ssk_live_...` — but then keep that config
+**local**: add `.mcp.json` to `.gitignore` first, rather than committing it
+with the key inside.
+
 Add `-e VECTROS_API_BASE_URL=https://api.staging.vectros.ai` for a non-production
 environment.
 
@@ -184,14 +226,14 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 > for a plain `npx` run, or pin an explicit version (`npx -y
 > @vectros-ai/mcp-server@<version>`) known to work.
 
-## Tools (22 tools)
+## Tools (23 tools)
 
 **Search & RAG**
 
 | Tool | What it does |
 |---|---|
-| `hybrid_search` | Hybrid BM25 + dense search across the tenant's indexed content (records + documents). Narrow by ownership, folder, type, metadata filters, a created date window, and keyword-precision (`textMode`) / relevance floors. Returns the indexed projection of each hit. |
-| `rag_ask` | Ask a question grounded against the indexed corpus. Scope retrieval (ownership / folder / type / metadata filters / date window) and steer generation (`instructions` / `temperature`). Streaming generation aggregated; progress notifications keep the call alive for the generation window. |
+| `hybrid_search` | Hybrid BM25 + dense search across the tenant's indexed content (records + documents). Narrow by ownership (`scope` for one dimension, `scopeFilters` for several at once — e.g. one client within one org), folder, type, metadata filters, a created date window, and keyword-precision (`textMode`) / relevance floors. Returns the indexed projection of each hit. |
+| `rag_ask` | Ask a question grounded against the indexed corpus. Scope retrieval (ownership — `scope` or multi-dimension `scopeFilters` — / folder / type / metadata filters / date window) and steer generation (`instructions` / `temperature`). Streaming generation aggregated; progress notifications keep the call alive for the generation window. |
 | `document_ask` | Ask a question grounded against a single document. Same aggregation + progress-notification shape as `rag_ask`. |
 
 **Records** (structured, schema-validated data)
@@ -199,10 +241,11 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 | Tool | What it does |
 |---|---|
 | `list_schemas` | List the record-schema catalog the credential can see (filter by `surface` or resolve one by `recordType`). Makes `record_query` / `record_create` discoverable. |
-| `record_query` | Query records by lookup field — equality (`value`), range, or prefix, with `asc`/`desc` ordering and an optional `sortFrom`/`sortTo` window — or list mode (filter by ownership + type). Also supports composite equality across 2-3 fields (`values`), but only against a lookup the *schema* declares over those fields together (see `list_schemas`) — not any two fields you pick. |
+| `record_query` | Query records by lookup field — equality (`value`), range, or prefix, with `asc`/`desc` ordering and an optional `sortFrom`/`sortTo` window — or list mode, choosing one of `type`, `folderId` (every record in a folder, any type — combine with `type` to narrow), or `recent` (the account-wide recently-updated feed across all types), then optionally filtering the first two by ownership. Also supports composite equality across 2-3 fields (`values`), but only against a lookup the *schema* declares over those fields together (see `list_schemas`) — not any two fields you pick. |
 | `record_get` | Fetch one record by id, including its full payload (large payloads truncated to protect the agent context window). |
 | `record_batch_get` | Fetch several records by id (1-100) in one call, each with its full payload. Returns `missingIds` for any requested id you can't access, since the API silently omits them. |
 | `record_create` | Create a record of a given type; idempotent by `externalId`; optional per-record `indexMode`. |
+| `record_batch_write` | Create or upsert up to 50 records in one call, instead of N `record_create` round-trips. Items may mix types and are validated and scope-checked individually. `atomicity: all_or_nothing` commits them as one transaction (nothing is written if any item fails); the default `best_effort` writes each independently. Reports success whenever the batch was *processed* — read the per-item `results`, not just the absence of an error. |
 | `record_update` | Patch a record's payload (deep-merged; `null` deletes a key); optimistic concurrency via `expectedVersion`. |
 | `record_delete` | Permanently delete a record by id (leaves a tombstone). |
 
@@ -212,7 +255,7 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 |---|---|
 | `document_ingest` | Create a document — inline text body OR local file upload (file mode is stdio-transport only). Idempotent by `externalId`; optional `schemaId` + `payload` for a typed, lookup-queryable document. |
 | `document_query` | Query documents by lookup field (equality / range / prefix, with `asc`/`desc` ordering) or list mode (filter by ownership + type). |
-| `document_get` | Fetch a document by id (metadata incl. lifecycle `status` + processing `indexStatus`; optional text truncated at ~8K tokens; optional presigned `downloadUrl` for file-backed documents). |
+| `document_get` | Fetch a document by id (metadata incl. lifecycle `status` + processing `indexStatus`; optional text truncated at ~8K tokens; optional presigned `downloadUrl` for file-backed documents — always forces a download, never inline rendering, regardless of file type). |
 | `document_update` | Patch a document's metadata / typed payload (deep-merged); archive/restore via `status` (`ARCHIVED` soft-retracts from search, `ACTIVE` restores); optimistic concurrency via `expectedVersion`. |
 | `document_delete` | Permanently delete a document by id (removes it and its indexed content). |
 
@@ -223,17 +266,17 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 | `folder_query` | Get a folder by id, or list folders (a parent's children for tree navigation, or a flat tenant list; paginated via `nextCursor`). |
 | `folder_create` | Create a folder. |
 | `folder_update` | Update a folder's name / description / ownership (merge-patch; optimistic concurrency via `expectedVersion`; folders cannot be re-parented). |
-| `folder_delete` | Delete a folder. |
+| `folder_delete` | Delete a folder. It must be empty first — no documents, no records, and no sub-folders — and a context root is protected outright. |
 
 **Identity & history**
 
 | Tool | What it does |
 |---|---|
-| `current_identity` | Describe the credential: tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope. Does **not** yet include `granted_capabilities` (`member-lifecycle` / `forensic-read` / `context-directory-read` / `delegate-mint`, as of API 0.40.0, joined by `delegate-principal-stamp` in 0.42.0) — a separate reach dimension a scope clause can carry that `/v1/ping` doesn't report yet, so allowedActions + dataScope may understate a credential's true reach. Also reports this server's own version and the bundled SDK version (`mcpServerVersion`, `sdkVersion`). |
+| `current_identity` | Describe the credential: tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope. Does **not** yet include `granted_capabilities` (`member-lifecycle` / `forensic-read` / `context-directory-read` / `delegate-mint`, as of API 0.40.0, joined by `delegate-principal-stamp` in 0.42.0 and `trigger-control-plane-grant` in 0.44.0) — a separate reach dimension a scope clause can carry that `/v1/ping` doesn't report yet, so allowedActions + dataScope may understate a credential's true reach. Also reports this server's own version and the bundled SDK version (`mcpServerVersion`, `sdkVersion`). |
 | `lookup_principal` | Resolve a user, or an identity entity in a namespace (`org`/`client`/any namespace you registered), by your own `externalId` (→ its Vectros UUID, for the ownership filters) or by a schema lookup field. Pass `contextId` to target a specific app context for a context-owned namespace. Read-only. |
 | `version_history` | Read the audit/version trail (CREATE/UPDATE/DELETE, with actor + diff) for one record or document. Read-only. |
 
-All 22 tools wrap published Vectros HTTP API endpoints. JSON
+All 23 tools wrap published Vectros HTTP API endpoints. JSON
 responses are what the agent sees as tool output. Per-call cost
 surfaces via the `usage` field on inference responses.
 
@@ -275,6 +318,20 @@ AccessProfile for MCP") for least-privilege credential setup — the
 `vectros bootstrap` flow provisions a scoped `ssk_*` key and its AccessProfile
 in one command.
 
+> **A root `sk_*` can no longer file into another app context, as of API 0.43.0.**
+> If you run this server on a root key and a tool call names a `folderId` /
+> `parentFolderId` — or a `schemaId` on a document — belonging to a context other
+> than `default`, it is now refused with a uniform `400 "Folder not found"` /
+> `"Schema not found"`. This affects `document_ingest`, `document_update`,
+> `record_create`, `record_update` and `folder_create`, and it is a change in
+> outcome: those calls used to succeed. They never did what they appeared to,
+> though — a root key's writes are always stamped `default`, so the row landed in
+> `default` while its folder or schema lived elsewhere, permanently invisible to
+> the context that owned them. Existing rows written the old way are untouched and
+> still readable, updatable and deletable. The fix is the same scoped key
+> recommended above: one bound to the target context can file into it and always
+> could.
+
 ## Credential resolution
 
 The server resolves its API key from the first source that yields one:
@@ -378,6 +435,49 @@ const server = new VectrosMCPServer({
 await server.connect(createStdioTransport());
 ```
 
+## What this server deliberately doesn't expose
+
+This is a decision, not a backlog. An MCP server is a tool surface handed to an
+autonomous caller, so a capability the API offers is not automatically a tool —
+each one has to earn its place on an agent's surface.
+
+The line is the **data plane**: records, documents, folders and search are here in
+full. Anything that grants or administers authority is not, and neither is the
+design-time layer that defines the data model.
+
+- **Stored scripts** (`/v1/scripts` — push, list, fetch, delete). A stored script is
+  code, not data. Authoring it is a design-time act, the same reason schema mutation
+  lives in the CLI rather than here: an agent that can write the code that later runs
+  under your credential is a different proposition from one that can write records.
+- **Synchronous script execution** (`POST /v1/scripts/execute`, the `scripts:x` scope).
+  The closer call of the two, and excluded on operational grounds rather than reach —
+  a `scripts:x:<name>` grant is a deliberately narrow, per-script permission, and an
+  ordinary scoped key can hold it. What an agent handles badly is the failure surface:
+  a run whose outcome cannot be determined returns `500 EXECUTION_OUTCOME_UNKNOWN` with
+  writes that may or may not have committed, which is not something a caller resolves
+  by retrying — it has to go and look. Getting a retry right also means reusing an
+  `Idempotency-Key` across attempts, and a tool call has no natural retry identity, so
+  an agent re-invoking after a timeout would silently run the script a second time.
+  Exposing this well needs a deliberate design for those two things, not a thin wrapper.
+  Until then, run scripts from a caller that can handle them — the API, the SDK, or the
+  CLI.
+- **Trigger rules** (`/v1/triggers`). Declaring a rule grants authority — a rule's
+  `scopes`/`roleIds` are live, and declaring one is scope-monotonicity-checked like
+  any other authority-granting surface. Minting authority is not an agent action.
+- **Trigger failure history** (`GET /v1/trigger-failures`) and **usage/billing**
+  (`GET /v1/usage`). Both are read-only, and both are operational rather than
+  data-plane — they describe how your automation and your account are behaving, not
+  what your content says. That is a question for the developer portal or the CLI,
+  where a person is looking at it, rather than a tool an agent reaches for mid-task.
+- **Identity, access and credential administration** — users, access profiles,
+  roles, app contexts, issuer registrations, and scoped-key minting. Unchanged
+  since launch: identity CRUD stays off the agent tool surface by design.
+  `lookup_principal` resolves an identifier to an id and does nothing else.
+- **Compliance operations** (erasure, export). Same reason.
+
+If one of these belongs on your agent's surface, that's worth telling us — the
+line is drawn on purpose and can be redrawn with a reason.
+
 ## What this server doesn't do (yet)
 
 - **No prompts capability** — `/rag` and `/ingest_pdf` slash-command