From e537ddcda66b857a27eef12ea48733194891f508 Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Tue, 20 Jan 2026 18:47:24 -0700
Subject: [PATCH] Document file_content parameter for hosted server

- Update table: "URL + base64 upload" for hosted file access
- Add new section with Python/JS/curl examples for document upload
- Document MCP_ALLOW_LOCAL_FILES env var for self-hosting
---
 src/content/docs/how-to/hosted-mcp.mdx | 88 ++++++++++++++++++++++++--
 1 file changed, 84 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/how-to/hosted-mcp.mdx b/src/content/docs/how-to/hosted-mcp.mdx
index 8a0b4fb..d9b411d 100644
--- a/src/content/docs/how-to/hosted-mcp.mdx
+++ b/src/content/docs/how-to/hosted-mcp.mdx
@@ -73,7 +73,7 @@ All 20+ mcwaddams tools are available via the hosted server:
 | Feature | Hosted | Local (uvx) |
 |---------|--------|-------------|
 | Installation | None | `uvx mcwaddams` |
-| File Access | URL only | Local + URL |
+| File Access | URL + base64 upload | Local + URL |
 | Speed | Network latency | Instant |
 | Privacy | Files processed on server | Files stay local |
 | Availability | Requires internet | Works offline |
@@ -82,9 +82,13 @@ All 20+ mcwaddams tools are available via the hosted server:
 When using the hosted server, your documents are transmitted to and processed on our server. For sensitive documents, use the local installation instead.
 </Aside>
 
-## Using with URLs
+## Uploading Documents
 
-The hosted server can process documents from URLs directly:
+The hosted server cannot access files on your local machine. Instead, you have two options:
+
+### Option 1: URL Reference
+
+If your document is already hosted online:
 
 ```python
 # Extract text from a public document
@@ -93,7 +97,77 @@ result = await session.call_tool("extract_text", {
 })
 ```
 
-This is particularly useful for processing documents already hosted online.
+### Option 2: Base64 Upload
+
+For local files, encode them as base64 and pass via `file_content`:
+
+<Tabs>
+  <TabItem label="Python">
+    ```python
+    import base64
+    from pathlib import Path
+
+    # Read and encode your document
+    doc_path = Path("my-report.docx")
+    file_content = base64.b64encode(doc_path.read_bytes()).decode("utf-8")
+
+    # Call the tool with file_content
+    result = await session.call_tool("extract_text", {
+        "file_path": "my-report.docx",  # Used for extension detection
+        "file_content": file_content
+    })
+    ```
+  </TabItem>
+  <TabItem label="JavaScript">
+    ```javascript
+    import { readFileSync } from 'fs';
+
+    // Read and encode your document
+    const docBuffer = readFileSync('my-report.docx');
+    const fileContent = docBuffer.toString('base64');
+
+    // Call the tool with file_content
+    const result = await session.callTool("extract_text", {
+        file_path: "my-report.docx",  // Used for extension detection
+        file_content: fileContent
+    });
+    ```
+  </TabItem>
+  <TabItem label="Bash/curl">
+    ```bash
+    # Encode document to base64
+    FILE_CONTENT=$(base64 -w 0 my-report.docx)
+
+    # Call via HTTP (simplified example)
+    curl -X POST https://mcwaddams.l.supported.systems/mcp \
+      -H "Content-Type: application/json" \
+      -d "{
+        \"method\": \"tools/call\",
+        \"params\": {
+          \"name\": \"extract_text\",
+          \"arguments\": {
+            \"file_path\": \"my-report.docx\",
+            \"file_content\": \"$FILE_CONTENT\"
+          }
+        }
+      }"
+    ```
+  </TabItem>
+</Tabs>
+
+<Aside type="note" title="file_path Still Required">
+When using `file_content`, the `file_path` parameter is still required but only used for extension detection. The server uses the extension to determine the correct processing method.
+</Aside>
+
+### All Tools Support Upload
+
+Every tool that accepts `file_path` also accepts `file_content`:
+
+- `extract_text` - Extract text with base64 upload
+- `extract_images` - Extract images with base64 upload
+- `convert_to_markdown` - Convert Word docs to Markdown
+- `analyze_excel_data` - Analyze uploaded spreadsheets
+- And all other document tools...
 
 ## Self-Hosting
 
@@ -109,10 +183,16 @@ services:
       - MCP_TRANSPORT=streamable-http
       - MCP_HOST=0.0.0.0
       - MCP_PORT=8000
+      # Enable local file access (disabled by default for security)
+      # - MCP_ALLOW_LOCAL_FILES=true
     ports:
       - "8000:8000"
 ```
 
+<Aside type="tip" title="Local File Access">
+By default, hosted servers only accept URLs and `file_content` uploads. If you're self-hosting on a trusted network and want to access local files, set `MCP_ALLOW_LOCAL_FILES=true`.
+</Aside>
+
 ### With Caddy Reverse Proxy
 
 Clone the repo and use our docker-compose with caddy-docker-proxy labels: