docs(mcp-server): clarify hosted vs local uploads

Author: kvz

packages/mcp-server/README.md

@@ -87,6 +87,14 @@ the request body stays small and no extra MCP/LLM token budget is consumed.
 - If instructions already contain an `/http/import` step, the MCP server sets/overrides its `url`.
   - If multiple URLs and a single `/http/import` step exists, it supplies a `url` array.
 
+## Local vs hosted file access
+
+- `path` inputs only work when the MCP server can read the same filesystem (local/stdio).
+- Hosted MCP cannot access your disk. Use `url`/`base64` for small files, or upload locally with:
+  `npx @transloadit/node upload ./file.ext <tus_url> --assembly <assembly_url> --field :original`
+- For remote flows, create the Assembly with `expected_uploads` so it stays open for out‑of‑band
+  tus uploads.
+
 ## Resume behavior
 
 If `assembly_url` is provided, the MCP server resumes uploads using Assembly status

packages/mcp-server/src/server.ts

@@ -341,6 +341,9 @@ const createLiveClient = (
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null
 
+const isErrnoException = (value: unknown): value is NodeJS.ErrnoException =>
+  isRecord(value) && typeof value.code === 'string'
+
 const getAssemblyIdFromUrl = (assemblyUrl: string): string => {
   const match = assemblyUrl.match(/\/assemblies\/([^/?#]+)/)
   if (!match) {
@@ -551,28 +554,38 @@ export const createTransloaditMcpServer = (
         const uploadConcurrency = upload_concurrency
         const chunkSize = upload_chunk_size
 
-        const assembly = assembly_url
-          ? await client.resumeAssemblyUploads({
-              assemblyUrl: assembly_url,
-              files: filesMap,
-              uploads: uploadsMap,
-              waitForCompletion,
-              timeout,
-              uploadConcurrency,
-              chunkSize,
-              uploadBehavior,
-            })
-          : await client.createAssembly({
-              params,
-              files: filesMap,
-              uploads: uploadsMap,
-              waitForCompletion,
-              timeout,
-              uploadConcurrency,
-              chunkSize,
-              uploadBehavior,
-              expectedUploads: expected_uploads,
+        let assembly: Awaited<ReturnType<typeof client.createAssembly>>
+        try {
+          assembly = assembly_url
+            ? await client.resumeAssemblyUploads({
+                assemblyUrl: assembly_url,
+                files: filesMap,
+                uploads: uploadsMap,
+                waitForCompletion,
+                timeout,
+                uploadConcurrency,
+                chunkSize,
+                uploadBehavior,
+              })
+            : await client.createAssembly({
+                params,
+                files: filesMap,
+                uploads: uploadsMap,
+                waitForCompletion,
+                timeout,
+                uploadConcurrency,
+                chunkSize,
+                uploadBehavior,
+                expectedUploads: expected_uploads,
+              })
+        } catch (error) {
+          if (isErrnoException(error) && error.code === 'ENOENT') {
+            return buildToolError('mcp_file_not_found', error.message, {
+              hint: 'Path inputs only work when the MCP server can read local files. For hosted MCP, use url/base64 or upload via `npx @transloadit/node upload`.',
             })
+          }
+          throw error
+        }
 
         if (assembly_url) {
           uploadSummary.resumed = true