@@ -0,0 +1,14 @@
+---
+'@objectstack/mcp': patch
+'@objectstack/runtime': patch
+'@objectstack/service-storage': patch
+---
+
+feat(mcp): an agent can read a record's files and attach a file to a record — `read_file` and `create_upload_link` over `/api/v1/mcp`, and the single-use upload link they hand out (#30892)
+
+Clause-②: yes (widening) — two MCP tools join the HTTP surface where the storage service is installed (`read_file` under `data:read`, `create_upload_link` under `data:write`), and two public routes join the storage family: `GET` and `PUT /api/v1/storage/upload-links/:token`. Nothing that answered before answers differently.
+Metadata-protocol: none
+
+- **`read_file`** takes `objectName`, `recordId` and a file field (with `fileId` when the field holds several files) or an `attachmentId`. With neither, it lists the record's files. It answers the file's facts (id, name, type, size, the read cap that applies), a short-lived download link, and the content: a PDF's or Word document's text (extracted on the server, capped in pages and characters), an image as an MCP image block, a text file as text. A file over the cap (10 MiB) answers its facts and the download link, without content. Access follows the record: a record the caller cannot read answers `404 RECORD_NOT_FOUND`, as `get_record` does, and a file the download door would refuse answers that door's `403`.
+- **`create_upload_link`** takes a record the caller may edit plus a file field or `attachments: true`. It answers a link that accepts exactly one upload for ten minutes, bound to that record and that field (or the record's attachments). The upload lands as the caller would land it: the file field is written through the record's own update door, so the field's `accept` and `maxSize`, the record's edit access and the upload size limit (`storage.max_upload_mb`, `413` before the link is spent) all apply. It writes the same `sys_file` row, size recorded, and the same `storage.upload` as any other upload, so whatever a host counts toward quota counts it. A used, expired or unknown link answers the same `404`.
+- **`@objectstack/mcp`** loads `unpdf` (pinned 1.9.1) by dynamic import on the first PDF read, with pdf.js eval off; a Word document is read with `node:zlib` under a bounded inflate.
@@ -244,7 +244,8 @@ decision.
 
 ## What the agent gets
 
-Twelve tools, generated from your metadata:
+Twelve tools, generated from your metadata, and two more for files where the
+storage service is installed:
 
 | Tool | What it does |
 |:---|:---|
@@ -255,6 +256,38 @@ Twelve tools, generated from your metadata:
 | `create_record` / `update_record` / `delete_record` | Write data |
 | `list_actions` / `run_action` | Discover and invoke your business actions by name |
 | `resume_run` | Finish a flow action that paused on a screen, by submitting the screen's values |
+| `read_file` | Read a file a record carries: its text (text files, PDF, Word `.docx`) or the image itself, with its size, the byte cap and a short-lived download link |
+| `create_upload_link` | Hand the user a single-use link that uploads one file onto a record's file field or its attachments |
+
+### Files: `read_file` and `create_upload_link`
+
+Both tools are registered only where the storage service is installed (they
+read and write through it), `read_file` with the `data:read` scope and
+`create_upload_link` with `data:write`. Neither judges access on its own: the
+record is read first, exactly as `get_record` reads it, so **no access to the
+record means no file**, refused with the same `RECORD_NOT_FOUND`.
+
+- **`read_file({ objectName, recordId, field?, fileId?, attachmentId? })`**
+  reads one file: the one a file field holds (`field`, plus `fileId` when the
+  field holds several), or one attachment (`attachmentId`). Send neither to
+  list the record's files with their ids. The file is then judged by the same
+  rule as a download from the Console. The answer carries the file's name,
+  type and size, the byte cap `read_file` reads (10 MiB), a download link that
+  expires after five minutes, and the content: the text of a text file, a PDF
+  or a Word document (cut at 100,000 characters or 200 PDF pages), or the image
+  itself for PNG, JPEG, GIF and WebP up to 5 MiB. A larger file answers its
+  facts and the link only; a damaged PDF or Word file answers a sentence
+  saying so.
+- **`create_upload_link({ objectName, recordId, field? | attachments: true })`**
+  needs a record the caller may edit (and, for a field, a field they may
+  write). It answers a link and its expiry (ten minutes). The user opens the
+  link in a browser, on a phone too, picks one file, and it lands on exactly
+  that record and field, or as an attachment of that record. The link works
+  once: a second use, an expired link and an unknown link all get the same
+  answer. The upload is stored as the user who asked for the link, with their
+  access checked again when the file arrives, and it meets the storage
+  service's maximum upload size before the link is spent. Sending a file's
+  bytes through the MCP protocol itself is not supported yet.
 
 The tools are a fixed ~10-tool **spine** with the object name as a *parameter*
 (`query_records(objectName, …)`), not one tool per object — so the list stays
@@ -403,7 +436,7 @@ call '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":
 # → {"result":{"serverInfo":{"name":"objectstack",...},"capabilities":{"tools":{...},"prompts":{}}},...}
 
 call '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | grep -o '"name":"[a-z_]*"'
-# → the twelve tools, list_objects … resume_run
+# → the twelve tools, list_objects … resume_run (fourteen with read_file and create_upload_link where storage is installed)
 
 call '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_records","arguments":{"objectName":"crm_opportunity","limit":3}}}'
 # → {"result":{"content":[{"type":"text","text":"{ \"object\": \"crm_opportunity\", \"records\": [ ... ], \"total\": 23, \"hasMore\": true }"}]}}
 
@@ -161,6 +161,8 @@ other adapter.
 | GET | `/storage/upload/chunked/:uploadId/progress` | `storage.resumeUpload` | Read session progress (first step of a resume) |
 | GET | `/storage/files/:fileId/url` | `storage.getDownloadUrl` | Resolve a short-lived signed download URL |
 | GET | `/storage/files/:fileId` | — | Stable browser URL; 302s to the same signed URL (what file fields carry) |
+| GET | `/storage/upload-links/:token` | — | The page a single-use upload link opens (minted by the MCP `create_upload_link` tool): a file picker |
+| PUT | `/storage/upload-links/:token` | — | Spend the link on the request body; the file lands on the record and field the link is bound to |
 
 `storage.upload(file)` runs steps 1–3 for you, including the direct-to-storage
 `PUT` in step 2. Step 1 refuses an empty `mimeType` with `400 INVALID_REQUEST`,
 
@@ -44,8 +44,9 @@ import { describe, it, expect, beforeEach } from 'vitest';
 
 import { MCPServerRuntime } from './mcp-server-runtime.js';
 import type { McpActionBridge, McpDataBridge } from './mcp-http-tools.js';
+import type { McpFileBridge } from './file-content.js';
 
-interface StubBridge extends McpDataBridge, McpActionBridge {
+interface StubBridge extends McpDataBridge, McpActionBridge, McpFileBridge {
   calls: any[];
 }
 
@@ -64,6 +65,16 @@ function makeBridge(): StubBridge {
     async listActions() { calls.push(['listActions']); return [{ name: 'complete_task', objectName: 'crm_opportunity' }]; },
     async runAction(name: string, input: any) { calls.push(['runAction', name, input]); return { ok: true }; },
     async resumeRun(runId: string, input: any) { calls.push(['resumeRun', runId, input]); return { ok: true }; },
+    // [#30892] The file pair's members, so `read_file` / `create_upload_link` are swept too.
+    async listRecordFiles(object: string, recordId: string) { calls.push(['listRecordFiles', object, recordId]); return []; },
+    async readRecordFile(object: string, recordId: string, target: any, options: any) {
+      calls.push(['readRecordFile', object, recordId, target, options]);
+      return { fileId: 'f1', name: 'a.txt', mimeType: 'text/plain', size: 1, maxBytes: options.maxBytes, bytes: new Uint8Array([0x61]), download: null };
+    },
+    async createUploadLink(object: string, recordId: string, target: any) {
+      calls.push(['createUploadLink', object, recordId, target]);
+      return { url: 'https://x.test/api/v1/storage/upload-links/t', expiresAt: '2026-11-06T12:10:00.000Z' };
+    },
   };
 }
 
@@ -110,6 +121,8 @@ const VALID_ARGS: Record<string, Record<string, unknown>> = {
   list_actions: {},
   run_action: { actionName: 'complete_task' },
   resume_run: { runId: 'run_1' },
+  read_file: { objectName: 'crm_opportunity', recordId: 'r1', field: 'contract' },
+  create_upload_link: { objectName: 'crm_opportunity', recordId: 'r1', field: 'contract' },
 };
 
 describe('MCP tool arguments — undeclared keys are refused (#16913)', () => {
@@ -213,12 +226,14 @@ describe('MCP tool arguments — undeclared keys are refused (#16913)', () => {
 
   // ── The sweep: every advertised tool holds the same posture ────────────────
 
-  it('advertises the twelve tools this sweep covers', async () => {
+  it('advertises the fourteen tools this sweep covers', async () => {
     const json = await rpc(runtime, bridge, 'tools/list');
     const names = (json.result?.tools ?? []).map((t: any) => t.name).sort();
     expect(names).toEqual(Object.keys(VALID_ARGS).sort());
-    // [#15705] Twelve with `resume_run`, which this stub's bridge implements.
-    expect(names).toHaveLength(12);
+    // [#15705] Twelve with `resume_run`, which this stub's bridge implements;
+    // [#30892] fourteen with `read_file` and `create_upload_link`, which it
+    // implements too.
+    expect(names).toHaveLength(14);
   });
 
   it('every advertised tool ACCEPTS its declared arguments (the sweep control)', async () => {
 
@@ -210,7 +210,7 @@ describe('route ledger ↔ live mount parity (#7526)', () => {
     stack = await bootShowcase({
       // Boot as WIDE as this gate can, so as few rows as possible have to be
       // pinned: every plugin added here converts a pin into a measurement.
-      // `StorageServicePlugin` alone converts ten — the whole storage ledger,
+      // `StorageServicePlugin` alone converts twelve — the whole storage ledger,
       // which the lean default boot leaves entirely unobserved.
       //
       // NOT `automation: true`, and the reason is worth writing down: the