@vectros-ai/mcp-server 0.6.0 → 0.9.0

package/dist/index.mjs

@@ -650,6 +650,10 @@ var ReadAccessLogResponse;
 })(ReadAccessLogResponse || (ReadAccessLogResponse = {}));
 var RecordRequest;
 ((RecordRequest2) => {
+  RecordRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
   RecordRequest2.IndexMode = {
     Hybrid: "HYBRID",
     Semantic: "SEMANTIC",
@@ -659,6 +663,10 @@ var RecordRequest;
 })(RecordRequest || (RecordRequest = {}));
 var RecordResponse;
 ((RecordResponse2) => {
+  RecordResponse2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
   RecordResponse2.IndexStatus = {
     PendingIndex: "PENDING_INDEX",
     Indexed: "INDEXED",
@@ -3133,7 +3141,7 @@ var AuthClient = class {
    *             roleId: "engineering-member",
    *             name: "Engineering Team Member",
    *             scopes: [{
-   *                     allowed_actions: ["read", "write"]
+   *                     allowed_actions: ["records:cru", "search:r"]
    *                 }]
    *         }
    *     })
@@ -3681,7 +3689,7 @@ var AuthClient = class {
    *             roleId: "engineering-member",
    *             name: "Engineering Team Member",
    *             scopes: [{
-   *                     allowed_actions: ["read", "write"]
+   *                     allowed_actions: ["records:cru", "search:r"]
    *                 }]
    *         }
    *     })
@@ -4584,7 +4592,7 @@ var DocumentsClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Returns a paginated list of your documents, optionally filtered by folder (`folderId`) and/or owner (`userId`, `orgId`, or `clientId`). The response is a `{data, nextCursor}` envelope; pass `nextCursor` back as `startFrom` to fetch the next page. Requires the `documents:r` scope.
+   * Returns a paginated list of your documents, optionally filtered by folder (`folderId`) and/or owner (`userId`, `orgId`, `clientId`, or `scope`). The response is a `{data, nextCursor}` envelope; pass `nextCursor` back as `startFrom` to fetch the next page. Requires the `documents:r` scope.
    *
    * @param {Vectros.ListDocumentsRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4594,6 +4602,7 @@ var DocumentsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         orgId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         clientId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+   *         scope: "group:eng-team",
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         startFrom: "doc_prev123"
    *     })
@@ -4602,11 +4611,12 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__listDocuments(request, requestOptions));
   }
   async __listDocuments(request = {}, requestOptions) {
-    const { userId, orgId, clientId, folderId, startFrom, limit } = request;
+    const { userId, orgId, clientId, scope, folderId, startFrom, limit } = request;
     const _queryParams = {
       userId,
       orgId,
       clientId,
+      scope,
       folderId,
       startFrom,
       limit
@@ -4664,9 +4674,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__ingestDocument(request, requestOptions));
   }
   async __ingestDocument(request, requestOptions) {
-    const { upsert, body: _body } = request;
+    const { upsert, allowClear, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      allowClear
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -4790,7 +4801,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__updateDocument(request, requestOptions));
   }
   async __updateDocument(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, allowClear, body: _body } = request;
+    const _queryParams = {
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -4805,7 +4819,7 @@ var DocumentsClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -4896,7 +4910,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "DELETE", "/v1/documents/{id}");
   }
   /**
-   * Partially updates a document using an RFC 7386 JSON Merge Patch. The `payload` object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to `null` is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (`title`, `storeText`, `folderId`, `schemaId`, ownership) are set when present and left unchanged when omitted; sending a top-level field as `null` is rejected. Supplying `text` re-ingests the document body (same as PUT). `indexMode` and `externalId` are immutable and rejected if present. The merged result is validated against the bound schema. Pass `expectedVersion` for optimistic concurrency (409 on conflict). Requires the `documents:u` scope.
+   * Partially updates a document using an RFC 7386 JSON Merge Patch. The `payload` object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to `null` is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (`title`, `folderId`, `schemaId`, ownership) are set when present and left unchanged when omitted; sending a top-level field as `null` is rejected. Supplying `text` re-ingests the document body (same as PUT). `indexMode`, `externalId`, and `storeText` (text retention is fixed at ingest) are immutable and rejected if present. The merged result is validated against the bound schema. Pass `expectedVersion` for optimistic concurrency (409 on conflict). Requires the `documents:u` scope.
    *
    * @param {Vectros.PatchDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5148,7 +5162,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/download");
   }
   /**
-   * Returns the full extracted or ingested text body for documents that were stored with `storeText=true`. Returns 404 when the document does not exist or when no text is available (because `storeText` was false, or extraction has not yet completed). Requires the `documents:r` scope.
+   * Returns the document's full text body when it is retained: always available for text-ingested documents, and for file-uploaded documents unless they were uploaded with `storeText=false` (which discards the extracted text once indexing completes — the original file remains available via `GET /{id}/download`). Returns 404 when the document does not exist, its text was not retained, or extraction has not yet completed. Requires the `documents:r` scope.
    *
    * @param {Vectros.GetDocumentTextRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7541,7 +7555,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/records/batch");
   }
   /**
-   * Returns a paginated list of records in your account as a `{data, nextCursor}` page. Supply exactly one of `type`, `folderId`, or `recent=true` to choose the mode: `type` lists all records of a single type; `folderId` lists all records in a folder (any type); and `recent=true` returns the account-wide recently-updated feed across all types, newest first. You may combine `type` with `folderId` to list a single type within a folder. The owner filters (`userId`, `orgId`, `clientId`) further narrow the type and folder modes; the `recent` feed is standalone and ignores all filters. Each token only sees the record types it is scoped to read. Requires the `records:r` scope. By default the response returns the indexed projection of each record; set `includePayload=true` to include full payloads.
+   * Returns a paginated list of records in your account as a `{data, nextCursor}` page. Supply exactly one of `type`, `folderId`, or `recent=true` to choose the mode: `type` lists all records of a single type; `folderId` lists all records in a folder (any type); and `recent=true` returns the account-wide recently-updated feed across all types, newest first. You may combine `type` with `folderId` to list a single type within a folder. The owner filters (`userId`, `orgId`, `clientId`, `scope`) further narrow the type and folder modes; the `recent` feed is standalone and ignores all filters. Each token only sees the record types it is scoped to read. Requires the `records:r` scope. By default the response returns the indexed projection of each record; set `includePayload=true` to include full payloads.
    *
    * @param {Vectros.ListRecordsRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7553,6 +7567,7 @@ var RecordsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         orgId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         clientId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+   *         scope: "group:eng-team",
    *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
    *     })
    */
@@ -7560,13 +7575,25 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__listRecords(request, requestOptions));
   }
   async __listRecords(request = {}, requestOptions) {
-    const { type: type_, folderId, userId, orgId, clientId, startFrom, limit, includePayload, recent } = request;
+    const {
+      type: type_,
+      folderId,
+      userId,
+      orgId,
+      clientId,
+      scope,
+      startFrom,
+      limit,
+      includePayload,
+      recent
+    } = request;
     const _queryParams = {
       type: type_,
       folderId,
       userId,
       orgId,
       clientId,
+      scope,
       startFrom,
       limit,
       includePayload,
@@ -7631,9 +7658,10 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__createRecord(request, requestOptions));
   }
   async __createRecord(request, requestOptions) {
-    const { upsert, body: _body } = request;
+    const { upsert, allowClear, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      allowClear
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -7755,7 +7783,10 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__updateRecord(request, requestOptions));
   }
   async __updateRecord(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, allowClear, body: _body } = request;
+    const _queryParams = {
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -7770,7 +7801,7 @@ var RecordsClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -8762,8 +8793,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.6.0" : "dev",
-  sdk: true ? "0.32.0" : "dev"
+  mcpServer: true ? "0.9.0" : "dev",
+  sdk: true ? "0.34.0" : "dev"
 };
 
 // src/log.ts
@@ -8999,7 +9030,7 @@ ${detail}${pointer}`
 
 // src/tools/hybrid_search.ts
 var MCP_DEFAULT_LIMIT = 3;
-var MCP_MAX_LIMIT = 10;
+var MCP_MAX_LIMIT = 50;
 var MCP_RESPONSE_CHAR_BUDGET = 24e3;
 var SNIPPET_MAX_CHARS = 160;
 var INTERNAL_METADATA_KEYS = /* @__PURE__ */ new Set(["tenantId", "owner_id", "model_type", "rootFolderId", "folderId"]);
@@ -9033,9 +9064,9 @@ var inputSchema = {
     "Keyword-match precision for the BM25 leg (TEXT/HYBRID modes). OR = any term (broad recall), AND = all terms (higher precision), PHRASE = contiguous phrase. Default: PHRASE (slop 3) in HYBRID, OR in TEXT. (The advanced raw-query COMPLEX mode is intentionally not exposed here.)"
   ),
   limit: z.number().int().min(1).max(MCP_MAX_LIMIT).optional().describe(
-    `Max hits to return. MCP-specific cap of ${MCP_MAX_LIMIT} (vs API max of 50) to protect the agent context window. Default 3. Use offset for pagination.`
+    `Max hits per page. Defaults to a low ${MCP_DEFAULT_LIMIT} to protect the agent context window; raise up to ${MCP_MAX_LIMIT} (the most a single search returns) in one call when you can accept the larger result, or page with \`offset\` instead.`
   ),
-  offset: z.number().int().min(0).optional().describe("Skip the first N hits \u2014 for pagination."),
+  offset: z.number().int().min(0).max(200).optional().describe("Skip the first N hits \u2014 for pagination (0\u2013200)."),
   folderId: z.string().optional().describe("Scope to content in this EXACT folder (Vectros folder id)."),
   rootFolderId: z.string().optional().describe("Scope to content under this folder AND all its descendants (subtree-root folder id)."),
   // Content narrowing.
@@ -9050,6 +9081,9 @@ var inputSchema = {
   userId: z.string().optional().describe("Restrict to content owned by this user (Vectros UUID)."),
   orgId: z.string().optional().describe("Restrict to content belonging to this org (Vectros UUID)."),
   clientId: z.string().optional().describe("Restrict to content associated with this client (Vectros UUID)."),
+  scope: z.string().optional().describe(
+    'Restrict to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+  ),
   // Date window.
   createdAfter: z.string().optional().describe("Restrict to content created at/after this ISO 8601 UTC timestamp."),
   createdBefore: z.string().optional().describe("Restrict to content created at/before this ISO 8601 UTC timestamp."),
@@ -9067,7 +9101,7 @@ var inputSchema = {
 var hybridSearch = ({ client, log }) => ({
   name: "hybrid_search",
   title: "Hybrid search",
-  description: `Search the partner tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to 10 results (default 3) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller's scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:"OR".`,
+  description: "Search your tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller's scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:\"OR\".",
   inputSchema,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
@@ -9087,6 +9121,7 @@ var hybridSearch = ({ client, log }) => ({
         userId: args.userId,
         orgId: args.orgId,
         clientId: args.clientId,
+        scope: args.scope,
         createdAfter: args.createdAfter,
         createdBefore: args.createdBefore,
         minSimilarity: args.minSimilarity,
@@ -9113,6 +9148,12 @@ var hybridSearch = ({ client, log }) => ({
         envelope.returnedResults = shaped.length;
         text = JSON.stringify(envelope, null, 2);
       }
+      const offset = args.offset ?? 0;
+      const totalResults = result.totalResults;
+      if (typeof totalResults === "number" && offset + shaped.length < totalResults) {
+        envelope.hasMore = true;
+        text = JSON.stringify(envelope, null, 2);
+      }
       log.debug(
         { tool: "hybrid_search", mode, limit, returned: shaped.length, textLegEmpty },
         "hybrid_search ok"
@@ -9148,7 +9189,7 @@ async function drainPages(fetchPage) {
 
 // src/tools/record_query.ts
 var MCP_DEFAULT_LIMIT2 = 3;
-var MCP_MAX_LIMIT2 = 10;
+var MCP_MAX_LIMIT2 = 100;
 var inputSchema2 = {
   type: z2.string().min(1, "type (record type) is required").describe('Record type / schema name (e.g. "patient", "clinical_note").'),
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
@@ -9166,14 +9207,18 @@ var inputSchema2 = {
   userId: z2.string().optional().describe("List mode: scope to records owned by this user."),
   orgId: z2.string().optional().describe("List mode: scope to records owned by this org."),
   clientId: z2.string().optional().describe("List mode: scope to records associated with this client."),
+  scope: z2.string().optional().describe(
+    'List mode: filter to records carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+  ),
+  startFrom: z2.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
   limit: z2.number().int().min(1).max(MCP_MAX_LIMIT2).optional().describe(
-    `Max records to return. MCP-specific cap of ${MCP_MAX_LIMIT2} (vs API max of 100) to protect the agent context window. Default 3.`
+    `Max records per page. Defaults to a low ${MCP_DEFAULT_LIMIT2} to protect the agent context window; raise up to ${MCP_MAX_LIMIT2} (the records API max) in one call when you can accept the larger payload, or page with \`startFrom\` instead.`
   )
 };
 var recordQuery = ({ client, log }) => ({
   name: "record_query",
   title: "Record query (list or lookup)",
-  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields too.\n  \u2022 List by type: omit `field`; optionally filter by `userId`/`orgId`/`clientId`.\nReturns up to 10 records (default 3). Mode is auto-detected from the arguments present.",
+  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields too.\n  \u2022 List by type: omit `field`; optionally filter by `userId`/`orgId`/`clientId`.\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected from the arguments present.",
   inputSchema: inputSchema2,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT2;
@@ -9183,8 +9228,9 @@ var recordQuery = ({ client, log }) => ({
     const from = args.from;
     const to = args.to;
     const prefix = args.prefix;
+    const startFrom = args.startFrom;
     try {
-      let records;
+      let page;
       if (field) {
         const hasEquality = value !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
@@ -9207,7 +9253,7 @@ var recordQuery = ({ client, log }) => ({
         if (hasRange && !(from !== void 0 && to !== void 0)) {
           return toolError("record_query", new Error("range lookup requires both 'from' and 'to'."));
         }
-        const page = await client.records.lookupRecordsByBody({
+        page = await client.records.lookupRecordsByBody({
           type,
           field,
           value,
@@ -9215,29 +9261,32 @@ var recordQuery = ({ client, log }) => ({
           to,
           prefix,
           order: args.order,
+          startFrom,
           limit
         });
-        records = pageItems(page);
         log.debug(
-          { tool: "record_query", mode: "lookup", type, field, returned: records.length },
+          { tool: "record_query", mode: "lookup", type, field, returned: pageItems(page).length },
           "record_query lookup ok"
         );
       } else {
-        const page = await client.records.listRecords({
+        page = await client.records.listRecords({
           type,
           userId: args.userId,
           orgId: args.orgId,
           clientId: args.clientId,
+          scope: args.scope,
+          startFrom,
           limit
         });
-        records = pageItems(page);
         log.debug(
-          { tool: "record_query", mode: "list", type, limit, returned: records.length },
+          { tool: "record_query", mode: "list", type, limit, returned: pageItems(page).length },
           "record_query list ok"
         );
       }
+      const records = pageItems(page);
+      const nextCursor = page.nextCursor ?? null;
       return {
-        content: [{ type: "text", text: JSON.stringify(records, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify({ data: records, nextCursor }, null, 2) }]
       };
     } catch (err) {
       log.warn({ tool: "record_query", err: String(err) }, "record_query failed");
@@ -9360,7 +9409,10 @@ var inputSchema4 = {
   folderId: z4.string().optional().describe("Group this record into a folder."),
   userId: z4.string().optional().describe("Owning user id."),
   orgId: z4.string().optional().describe("Owning organization id."),
-  clientId: z4.string().optional().describe("Associated client id.")
+  clientId: z4.string().optional().describe("Associated client id."),
+  scopes: z4.array(z4.string()).optional().describe(
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). This is the record\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE record owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default. `org:`/`client:` entries are equivalent to the orgId/clientId fields.'
+  )
 };
 var recordCreate = ({ client, log }) => ({
   name: "record_create",
@@ -9380,7 +9432,8 @@ var recordCreate = ({ client, log }) => ({
           folderId: args.folderId,
           userId: args.userId,
           orgId: args.orgId,
-          clientId: args.clientId
+          clientId: args.clientId,
+          scopes: args.scopes
         }
       });
       log.debug({ tool: "record_create", type, id: created.id }, "record_create ok");
@@ -9465,24 +9518,29 @@ var record_delete_default = recordDelete;
 // src/tools/rag_ask.ts
 import { z as z7 } from "zod";
 var SEARCH_MCP_DEFAULT_LIMIT = 5;
-var SEARCH_MCP_MAX_LIMIT = 10;
+var SEARCH_MCP_MAX_LIMIT = 50;
 var inputSchema7 = {
   query: z7.string().min(1, "query must be non-empty").describe("Question to ground against retrieved content."),
   instructions: z7.string().optional().describe(
     'System prompt that overrides the default for the generation step \u2014 e.g. "answer only from the provided context, cite sources, be concise". Default: a generic answer-from-context instruction.'
   ),
   model: z7.string().optional().describe(
-    "Inference model alias (e.g. claude-haiku-4-5, claude-sonnet-4-6, claude-opus-4-8). Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
+    "Inference model alias (e.g. claude-haiku-4-5, claude-sonnet-5, claude-opus-4-8). Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
   ),
   search: z7.object({
     mode: z7.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("Retrieval mode. Default HYBRID."),
-    limit: z7.number().int().min(1).max(SEARCH_MCP_MAX_LIMIT).optional().describe(`Passages to retrieve before generating. Default ${SEARCH_MCP_DEFAULT_LIMIT}, max ${SEARCH_MCP_MAX_LIMIT}.`),
+    limit: z7.number().int().min(1).max(SEARCH_MCP_MAX_LIMIT).optional().describe(
+      `Passages to retrieve before generating (the grounding-corpus size). Default ${SEARCH_MCP_DEFAULT_LIMIT}; raise up to ${SEARCH_MCP_MAX_LIMIT} (the RAG search API max) for a broader corpus when the extra grounding is worth the larger prompt.`
+    ),
     // Retrieval scoping — parity with hybrid_search so an agent can ground the
     // answer on a specific owner / folder / type / metadata subset, not just the
     // whole-tenant corpus.
     userId: z7.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
     orgId: z7.string().optional().describe("Restrict retrieval to content owned by this org (Vectros UUID)."),
     clientId: z7.string().optional().describe("Restrict retrieval to content tagged with this client (Vectros UUID)."),
+    scope: z7.string().optional().describe(
+      'Restrict retrieval to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+    ),
     folderId: z7.string().optional().describe("Restrict retrieval to this exact folder."),
     rootFolderId: z7.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
     typeName: z7.string().optional().describe("Restrict record retrieval to this schema type."),
@@ -9500,7 +9558,7 @@ var inputSchema7 = {
 var ragAsk = ({ client, log }) => ({
   name: "rag_ask",
   title: "RAG ask (corpus-wide)",
-  description: "Ask a question grounded against the partner tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership, folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
+  description: "Ask a question grounded against your tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership, folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
   inputSchema: inputSchema7,
   handler: async (args, extra) => {
     try {
@@ -9511,6 +9569,7 @@ var ragAsk = ({ client, log }) => ({
         userId: searchArg.userId,
         orgId: searchArg.orgId,
         clientId: searchArg.clientId,
+        scope: searchArg.scope,
         folderId: searchArg.folderId,
         rootFolderId: searchArg.rootFolderId,
         typeName: searchArg.typeName,
@@ -9668,7 +9727,7 @@ var inputSchema9 = {
 var listSchemas = ({ client, log }) => ({
   name: "list_schemas",
   title: "List record schemas",
-  description: 'List the structured-record schema catalog for the partner tenant. Each schema describes a record type (e.g. "patient", "clinical_note") \u2014 its fields, lookup-indexed fields, and capabilities. Use this to discover what record types exist before calling `record_query`. Filter with `surface` (record/document/user/org/client \u2014 e.g. only document types), `recordType` (resolve one schema by its type name), or `userId`/`orgId`; default returns everything the credential can see.',
+  description: 'List the structured-record schema catalog for your tenant. Each schema describes a record type (e.g. "patient", "clinical_note") \u2014 its fields, lookup-indexed fields, and capabilities. Use this to discover what record types exist before calling `record_query`. Filter with `surface` (record/document/user/org/client \u2014 e.g. only document types), `recordType` (resolve one schema by its type name), or `userId`/`orgId`; default returns everything the credential can see.',
   inputSchema: inputSchema9,
   handler: async (args) => {
     const userId = args.userId;
@@ -9722,7 +9781,7 @@ function isNotAvailable(err) {
 var documentGet = ({ client, log }) => ({
   name: "document_get",
   title: "Get document metadata (and optionally text)",
-  description: "Fetch metadata for a single document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). If the document was ingested without `storeText: true`, text is unavailable \u2014 `textAvailable: false` flag is set and the agent should use `document_ask` for question-driven extraction instead. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns the full document metadata, including its lifecycle `status` (ACTIVE, or ARCHIVED when soft-retracted from search \u2014 restorable via document_update) and its processing `indexStatus`.",
+  description: "Fetch metadata for a single document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). Text is available for every text-ingested document and for file-ingested documents unless they were uploaded with `storeText: false` (extracted text discarded after indexing) \u2014 then `textAvailable: false` is set; the original file is still retrievable via `includeDownloadUrl`. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns the full document metadata, including its lifecycle `status` (ACTIVE, or ARCHIVED when soft-retracted from search \u2014 restorable via document_update) and its processing `indexStatus`.",
   inputSchema: inputSchema10,
   handler: async (args) => {
     const documentId = args.documentId;
@@ -9746,7 +9805,7 @@ var documentGet = ({ client, log }) => ({
           if (isNotAvailable(textErr)) {
             log.debug(
               { tool: "document_get", id },
-              "document_get text unavailable (ingested without storeText)"
+              "document_get text unavailable (not retained \u2014 storeText:false upload)"
             );
             extra = { ...extra, textAvailable: false };
           } else {
@@ -9790,7 +9849,7 @@ var document_get_default = documentGet;
 // src/tools/document_query.ts
 import { z as z11 } from "zod";
 var MCP_DEFAULT_LIMIT3 = 3;
-var MCP_MAX_LIMIT3 = 10;
+var MCP_MAX_LIMIT3 = 100;
 var inputSchema11 = {
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
   field: z11.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
@@ -9807,14 +9866,18 @@ var inputSchema11 = {
   userId: z11.string().optional().describe("List mode: scope to documents owned by this user."),
   orgId: z11.string().optional().describe("List mode: scope to documents belonging to this org."),
   clientId: z11.string().optional().describe("List mode: scope to documents associated with this client."),
+  scope: z11.string().optional().describe(
+    'List mode: filter to documents carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+  ),
+  startFrom: z11.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
   limit: z11.number().int().min(1).max(MCP_MAX_LIMIT3).optional().describe(
-    `Max documents to return. MCP-specific cap of ${MCP_MAX_LIMIT3} (vs API max of 100) to protect the agent context window. Default 3.`
+    `Max documents per page. Defaults to a low ${MCP_DEFAULT_LIMIT3} to protect the agent context window; raise up to ${MCP_MAX_LIMIT3} (the documents API max) in one call when you can accept the larger payload, or page with \`startFrom\` instead.`
   )
 };
 var documentQuery = ({ client, log }) => ({
   name: "document_query",
   title: "Document query (list or lookup)",
-  description: "Query document metadata. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields (equality only there); range/prefix need a range-enabled field.\n  \u2022 List: omit `field`; optionally filter by `folderId`/`userId`/`orgId`/`clientId`.\nReturns up to 10 documents (default 3) as a bare array. Mode is auto-detected. Use document_get for the full text/download URL of one document.",
+  description: "Query document metadata. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields (equality only there); range/prefix need a range-enabled field.\n  \u2022 List: omit `field`; optionally filter by `folderId`/`userId`/`orgId`/`clientId`/`scope`.\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` documents (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected. Use document_get for the full text/download URL of one document.",
   inputSchema: inputSchema11,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT3;
@@ -9824,8 +9887,9 @@ var documentQuery = ({ client, log }) => ({
     const to = args.to;
     const prefix = args.prefix;
     const type = args.type;
+    const startFrom = args.startFrom;
     try {
-      let documents;
+      let page;
       if (field) {
         const hasEquality = value !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
@@ -9854,7 +9918,7 @@ var documentQuery = ({ client, log }) => ({
             new Error("lookup requires 'type' (the document's bound schema type) alongside 'field'.")
           );
         }
-        const page = await client.documents.lookupDocumentsByBody({
+        page = await client.documents.lookupDocumentsByBody({
           type,
           field,
           value,
@@ -9862,28 +9926,31 @@ var documentQuery = ({ client, log }) => ({
           to,
           prefix,
           order: args.order,
+          startFrom,
           limit
         });
-        documents = pageItems(page);
         log.debug(
-          { tool: "document_query", mode: "lookup", type, field, returned: documents.length },
+          { tool: "document_query", mode: "lookup", type, field, returned: pageItems(page).length },
           "document_query lookup ok"
         );
       } else {
-        const page = await client.documents.listDocuments({
+        page = await client.documents.listDocuments({
           folderId: args.folderId,
           userId: args.userId,
           orgId: args.orgId,
           clientId: args.clientId,
+          scope: args.scope,
+          startFrom,
           limit
         });
-        documents = pageItems(page);
         log.debug(
-          { tool: "document_query", mode: "list", limit, returned: documents.length },
+          { tool: "document_query", mode: "list", limit, returned: pageItems(page).length },
           "document_query list ok"
         );
       }
-      return { content: [{ type: "text", text: JSON.stringify(documents, null, 2) }] };
+      const documents = pageItems(page);
+      const nextCursor = page.nextCursor ?? null;
+      return { content: [{ type: "text", text: JSON.stringify({ data: documents, nextCursor }, null, 2) }] };
     } catch (err) {
       log.warn({ tool: "document_query", err: String(err) }, "document_query failed");
       return toolError("document_query", err);
@@ -9908,7 +9975,6 @@ var inputSchema12 = {
     "New raw text body. Supplying it re-ingests the document body and re-queues it for indexing, so the search index reflects the edit (text-ingested documents only \u2014 not file-backed ones). Omit to leave the stored text unchanged. This is the in-place alternative to re-ingesting with upsert:true."
   ),
   folderId: z12.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
-  storeText: z12.boolean().optional().describe("Whether the raw text is stored + retrievable."),
   status: z12.enum(["ACTIVE", "ARCHIVED"]).optional().describe(
     "Lifecycle status. `ARCHIVED` soft-retracts the document \u2014 it is pulled from search and recall but kept and recoverable; set it back to `ACTIVE` to re-index and restore it. The way to retire superseded content when the credential has no delete authority. Omit to leave unchanged."
   ),
@@ -9932,7 +9998,6 @@ var documentUpdate = ({ client, log }) => ({
     const fields = args.fields;
     const text = args.text;
     const folderId = args.folderId;
-    const storeText = args.storeText;
     const status = args.status;
     const userId = args.userId;
     const orgId = args.orgId;
@@ -9946,7 +10011,6 @@ var documentUpdate = ({ client, log }) => ({
       if (fields !== void 0) body.payload = fields;
       if (text !== void 0) body.text = text;
       if (folderId !== void 0) body.folderId = folderId;
-      if (storeText !== void 0) body.storeText = storeText;
       if (status !== void 0) body.status = status;
       if (userId !== void 0) body.userId = userId;
       if (orgId !== void 0) body.orgId = orgId;
@@ -9995,7 +10059,7 @@ var document_delete_default = documentDelete;
 // src/tools/folder_query.ts
 import { z as z14 } from "zod";
 var MCP_DEFAULT_LIMIT4 = 10;
-var MCP_MAX_LIMIT4 = 50;
+var MCP_MAX_LIMIT4 = 100;
 var inputSchema14 = {
   id: z14.string().optional().describe("Get mode: fetch this single folder by id."),
   parentId: z14.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
@@ -10003,12 +10067,14 @@ var inputSchema14 = {
   orgId: z14.string().optional().describe("List mode: scope to folders belonging to this org."),
   clientId: z14.string().optional().describe("List mode: scope to folders associated with this client."),
   startFrom: z14.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
-  limit: z14.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(`List mode: max folders to return. MCP cap of ${MCP_MAX_LIMIT4} (vs API 100). Default 10.`)
+  limit: z14.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(
+    `List mode: max folders per page. Default 10; raise up to ${MCP_MAX_LIMIT4} (the folders API max) in one call when you can accept the larger page, or page with \`startFrom\`.`
+  )
 };
 var folderQuery = ({ client, log }) => ({
   name: "folder_query",
   title: "Folder query (list or get)",
-  description: "Read folders. Two modes:\n  \u2022 Get: pass `id` \u2192 returns the single folder.\n  \u2022 List: omit `id`; pass `parentId` for a folder's direct children (tree navigation) or omit for a flat tenant list. Optionally filter by `userId`/`orgId`/`clientId`.\nList mode returns `{ data, nextCursor }` (default 10, max 50 per page); pass `nextCursor` back as `startFrom` to page through all folders. Get mode returns the single folder object.",
+  description: "Read folders. Two modes:\n  \u2022 Get: pass `id` \u2192 returns the single folder.\n  \u2022 List: omit `id`; pass `parentId` for a folder's direct children (tree navigation) or omit for a flat tenant list. Optionally filter by `userId`/`orgId`/`clientId`.\nList mode returns `{ data, nextCursor }` (default 10, max 100 per page \u2014 raise it in one call when you can accept the larger page); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page through all folders. Get mode returns the single folder object.",
   inputSchema: inputSchema14,
   handler: async (args) => {
     const id = args.id;
@@ -10048,7 +10114,10 @@ var inputSchema15 = {
   slug: z15.string().optional().describe("Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. Derived from name when omitted."),
   userId: z15.string().optional().describe("Owning user (Vectros UUID)."),
   orgId: z15.string().optional().describe("Owning org (Vectros UUID)."),
-  clientId: z15.string().optional().describe("Associated client (Vectros UUID).")
+  clientId: z15.string().optional().describe("Associated client (Vectros UUID)."),
+  scopes: z15.array(z15.string()).optional().describe(
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). This is the folder\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE folder owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default. `org:`/`client:` entries are equivalent to the orgId/clientId fields.'
+  )
 };
 var folderCreate = ({ client, log }) => ({
   name: "folder_create",
@@ -10065,7 +10134,8 @@ var folderCreate = ({ client, log }) => ({
           slug: args.slug,
           userId: args.userId,
           orgId: args.orgId,
-          clientId: args.clientId
+          clientId: args.clientId,
+          scopes: args.scopes
         }
       });
       log.debug({ tool: "folder_create", id: folder.id, name: folder.name }, "folder_create ok");
@@ -10266,7 +10336,7 @@ var inputSchema19 = {
   // Inline text mode (mutually exclusive with filePath):
   text: z18.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
   storeText: z18.boolean().optional().describe(
-    "If true (default), the text body is stored alongside the index so document_get(includeText:true) can retrieve it later. Set false to index only \u2014 saves storage cost on large corpora but document_get(includeText) will return textAvailable:false."
+    "Whether the document's text is retained after indexing (default true). Applies to BOTH modes and is fixed at ingest time. Text mode: the ingested body is always retained (this flag is effectively always true \u2014 the body is the document). File mode: true keeps the extracted text retrievable via document_get(includeText:true) and usable by document_ask; false discards the extracted text once indexing completes \u2014 search still works and the original file remains downloadable, but includeText returns textAvailable:false and document_ask is unavailable."
   ),
   // File upload mode (mutually exclusive with text; stdio-transport-only):
   filePath: z18.string().min(1).optional().describe(
@@ -10277,12 +10347,15 @@ var inputSchema19 = {
   folderId: z18.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
   userId: z18.string().optional().describe("Owning user ID. Optional."),
   orgId: z18.string().optional().describe("Owning org ID. Optional."),
-  clientId: z18.string().optional().describe("Owning client ID. Optional.")
+  clientId: z18.string().optional().describe("Owning client ID. Optional."),
+  scopes: z18.array(z18.string()).optional().describe(
+    "TEXT MODE ONLY. Scope ownership as `namespace:value` entries, at most 2 (e.g. [\"org:<uuid>\", \"group:eng-team\"]). This is the document's COMPLETE scope declaration and values must come from the credential's own identity. An empty array `[]` creates a PRIVATE document owned by the calling user alone. Omit to stamp the credential's full identity \u2014 the default. `org:`/`client:` entries are equivalent to the orgId/clientId fields. Rejected with `filePath` (file uploads do not accept a scope declaration): a file-uploaded document is stamped with the credential's full identity."
+  )
 };
 var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   name: "document_ingest",
   title: "Ingest a new document (text body or file upload)",
-  description: "Create a new document in your Vectros tenant. Two modes:\n  \u2022 Text mode: pass `text` (string body). Single-call. Use for crawled content, notes, generated text.\n  \u2022 File mode: pass `filePath` (local path on the MCP server's host machine). STDIO-TRANSPORT ONLY \u2014 rejected on HTTP transport. MCP server reads the bytes, requests a presigned upload URL, and PUTs them. Returns when the upload is accepted (indexStatus: PENDING_INDEX); poll with `document_get` until indexStatus is INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate). To UPDATE an existing document instead \u2014 re-index an edited body \u2014 pass `upsert:true` with the same `externalId` (and the same `schemaId`); this is the re-sync primitive for keeping a knowledge base current. Pass `schemaId` + `payload` for a typed, lookup-queryable document (records parity). indexMode defaults to HYBRID for untyped documents (omit to inherit a bound schema's default). storeText defaults to true (set false to skip storing the text body).",
+  description: "Create a new document in your Vectros tenant. Two modes:\n  \u2022 Text mode: pass `text` (string body). Single-call. Use for crawled content, notes, generated text.\n  \u2022 File mode: pass `filePath` (local path on the MCP server's host machine). STDIO-TRANSPORT ONLY \u2014 rejected on HTTP transport. MCP server reads the bytes, requests a presigned upload URL, and PUTs them. Returns when the upload is accepted (indexStatus: PENDING_INDEX); poll with `document_get` until indexStatus is INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate). To UPDATE an existing document instead \u2014 re-index an edited body \u2014 pass `upsert:true` with the same `externalId` (and the same `schemaId`); this is the re-sync primitive for keeping a knowledge base current. Pass `schemaId` + `payload` for a typed, lookup-queryable document (records parity). indexMode defaults to HYBRID for untyped documents (omit to inherit a bound schema's default). storeText defaults to true and is fixed at ingest: in file mode, false discards the extracted text after indexing (search + file download keep working; text retrieval and document_ask do not). Text-mode bodies are always retained.",
   inputSchema: inputSchema19,
   handler: async (args) => {
     const title = args.title;
@@ -10311,6 +10384,14 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
         )
       );
     }
+    if (filePath && args.scopes !== void 0) {
+      return toolError(
+        "document_ingest",
+        new Error(
+          "`scopes` is not supported with `filePath` \u2014 file uploads do not accept a scope declaration, and silently ignoring it could make an intended-private document team-visible. Use `text` mode to declare scopes, or omit `scopes` (the upload is stamped with the credential's full identity)."
+        )
+      );
+    }
     const common = {
       folderId: args.folderId,
       payload: args.payload,
@@ -10322,14 +10403,15 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
     };
     try {
       if (text) {
-        const storeText = args.storeText ?? true;
         const result = await client.documents.ingestDocument({
           upsert,
           body: {
             title,
             text,
             indexMode,
-            storeText,
+            // Scope ownership is a TEXT-mode contract only (the upload-init
+            // endpoint has no scopes field — see the gate above).
+            scopes: args.scopes,
             ...common
           }
         });
@@ -10360,11 +10442,13 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       }
       const fileName = basename(safePath);
       const fileType = args.fileType ?? inferMimeType(safePath);
+      const storeTextFile = args.storeText ?? true;
       const upload = await client.documents.uploadDocument({
         upsert,
         fileName,
         fileType,
         indexMode,
+        storeText: storeTextFile,
         ...common
       });
       const uploadUrl = upload?.uploadUrl;
@@ -10420,7 +10504,7 @@ var document_ingest_default = documentIngest;
 // src/tools/lookup_principal.ts
 import { z as z19 } from "zod";
 var MCP_DEFAULT_LIMIT5 = 10;
-var MCP_MAX_LIMIT5 = 50;
+var MCP_MAX_LIMIT5 = 100;
 var inputSchema20 = {
   kind: z19.enum(["user", "org", "client"]).describe("Which principal to look up: a user, an organization, or a client."),
   externalId: z19.string().optional().describe(
@@ -10434,12 +10518,15 @@ var inputSchema20 = {
   to: z19.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
   prefix: z19.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
   order: z19.enum(["asc", "desc"]).optional().describe("Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc`."),
-  limit: z19.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(`Max principals to return. MCP cap of ${MCP_MAX_LIMIT5} (vs API 100). Default ${MCP_DEFAULT_LIMIT5}.`)
+  startFrom: z19.string().optional().describe("Lookup mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
+  limit: z19.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(
+    `Max principals per page. Defaults to ${MCP_DEFAULT_LIMIT5}; raise up to ${MCP_MAX_LIMIT5} (the principals API max) in one call when you can accept the payload, or page with \`startFrom\`.`
+  )
 };
 var lookupPrincipal = ({ client, log }) => ({
   name: "lookup_principal",
   title: "Look up a user / org / client identity",
-  description: "Resolve a user, org, or client identity. Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) Returns up to 50 principals (default 10) as a bare array. Read-only \u2014 does not create or modify identities.",
+  description: "Resolve a user, org, or client identity. Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) Returns a `{ data, nextCursor }` page (default 10, max 100 \u2014 raise it in one call when you can accept the payload); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom`. Read-only \u2014 does not create or modify identities.",
   inputSchema: inputSchema20,
   handler: async (args) => {
     const kind = args.kind;
@@ -10452,6 +10539,7 @@ var lookupPrincipal = ({ client, log }) => ({
     const to = args.to;
     const prefix = args.prefix;
     const order = args.order;
+    const startFrom = args.startFrom;
     try {
       let page;
       if (externalId !== void 0) {
@@ -10489,7 +10577,7 @@ var lookupPrincipal = ({ client, log }) => ({
             new Error("lookup requires 'type' (the identity schema's record type) alongside 'field'.")
           );
         }
-        const req = { type, field, value, from, to, prefix, order, limit };
+        const req = { type, field, value, from, to, prefix, order, startFrom, limit };
         if (kind === "user") {
           page = await client.identity.lookupUsers(req);
         } else if (kind === "org") {
@@ -10505,7 +10593,8 @@ var lookupPrincipal = ({ client, log }) => ({
         );
       }
       const principals = pageItems(page);
-      return { content: [{ type: "text", text: JSON.stringify(principals, null, 2) }] };
+      const nextCursor = page.nextCursor ?? null;
+      return { content: [{ type: "text", text: JSON.stringify({ data: principals, nextCursor }, null, 2) }] };
     } catch (err) {
       log.warn({ tool: "lookup_principal", kind, err: String(err) }, "lookup_principal failed");
       return toolError("lookup_principal", err);