CamoFox MCP Downloads: Get the File, Not Just Metadata

To retrieve a file with CamoFox MCP, check the download record after the browser action, then request its content. Use list_downloads to find the intended record in the correct user and tab scope. Once it is completed, use get_download with includeContent: true for a supported small non-image file, or retrieve its contentUrl through your approved Browser-service connection. Inspect the saved document before calling the task complete.

A click, a filename and a download URL are different things from a usable file. This guide is for developers who already have CamoFox MCP connected and want to hand an exported report or PDF to the next step—not just tell an agent that it clicked Download.

Method: the tool examples below are source-backed request templates, not captured responses or an executed download test. We inspected the RedFox repositories and original discussion on 19 October 2026. Your installed client may display a tool-name prefix or a different schema; check its exposed tools before adapting the examples.

Three checkpoints between a click and a usable file

• Browser action: the intended page and export control were selected. This does not establish that a download finished.
• Download record: the Browser server tracked an artifact with an ID, status and metadata. This does not mean its bytes were delivered to your computer or AI client.
• Inspected copy: the intended bytes were retrieved, saved and opened or parsed, and their contents match the job. This is the useful handoff.

CamoFox MCP exposes the Browser server's download listing and retrieval tools, so an agent can inspect the file artifact rather than infer success from the page. Its registered download tools distinguish metadata from inline content. A maintainer-authored issue from 20 February 2026 specifically addressed making contentUrl and includeContent easier for agents to discover. That is product-maintainer context, not an independent customer success report.

Define the file you actually want

Consider a fictional job: retrieve the September usage report for Example Workspace as one PDF from a portal you are authorized to use. Before touching Export, write down the workspace, period, expected format and approved save destination. “Get the latest PDF” is weaker: an older report can also be the newest download in the registry.

Keep the actual userId and MCP-tracked tabId with the task. Use those returned identifiers, not the demonstration strings below. If the page shows the wrong workspace, a login prompt or an unexpected permission request, resolve that starting condition first. The separate CamoFox user-context guide covers identity mismatches; creating more downloads will not fix them.

Prefer a supported portal export or API when it already gives you the required document. This workflow is useful when an approved browser action is the appropriate way to obtain it. It does not bypass access controls or grant permission to redistribute the report.

1. Record the baseline, then trigger one intended export

Ask the client to call list_downloads for the owned tab and user before the export. These are example tool arguments; replace reports-demo and REPLACE_WITH_TRACKED_TAB_ID with your real authorized scope.

{
  "tabId": "REPLACE_WITH_TRACKED_TAB_ID",
  "userId": "reports-demo",
  "sort": "createdAt:desc",
  "limit": 20,
  "offset": 0
}

Keep the existing IDs and the time you began the export. Then inspect the current page, confirm the intended report and activate its export control once. If the page changed, obtain a fresh snapshot before using an element reference. The stale-reference guide covers that interaction problem separately.

List the same scope again after the action. Initially leave out status, extension and MIME filters: a completed-only list hides a failed or pending attempt, while a PDF-only filter can hide an unexpected filename. The Browser download listener creates a pending record and updates its state as saving and completion proceed.

If the response has pagination.hasMore, request subsequent pages by advancing offset by the returned limit, retaining the same scope. Deduplicate by download ID. A first page containing 20 records is not proof that no other matching download exists; the listing implementation returns total, offset, limit and hasMore.

2. Match the record before requesting content

Compare the new or changed records with the baseline. Check the owning user and tab, source URL when available, suggestedFilename, createdAt, status and size. A matching name alone is not enough; two reports can have the same filename. If more than one record could be the target, inspect further rather than choosing the first row.

• No new record: inspect the current page for a viewer, blocked export, login or still-running report. Recheck the exact scope before clicking again.
• Pending: recheck that same record within a bounded wait. Do not label it complete or create a second export just to get another ID.
• Failed or canceled: preserve the returned error and intended file identity. Diagnose before retrying; the first request may have created a portal-side export job.
• Completed with a plausible size: retrieve this exact ID, then inspect the actual content. Completion is the transfer checkpoint, not the business-content verdict.
• Zero or unknown size: check the status, size and any returned note. A size of -1 means unknown; metadata may arrive without a note. Do not treat a filename or metadata response as a nonempty document.

For the fictional PDF job, the final check is that the document itself names Example Workspace and the September period. Do not replace that check with “the filename contains September.” Also do not treat MIME metadata as content verification: the inspected Browser source can infer MIME type from the extension.

3. Choose inline content or the file-content route

For a completed small non-image download, call get_download with the actual returned ID and the same explicit user. Unlike a tab-scoped listing, this call does not infer its user from a supplied tab ID, because it has no tab-ID parameter. Keeping userId explicit avoids falling back to a different configured default.

{
  "downloadId": "REPLACE_WITH_RETURNED_DOWNLOAD_ID",
  "userId": "reports-demo",
  "includeContent": true
}

At the inspected implementation, non-image inline content is base64 and is limited to a known, positive size of at most 262,144 bytes. That is an inline-response limit, not a claim that the Browser server cannot download a larger file. If the result contains metadata and a note instead of content, read the note; do not summarize a PDF you never received.

If inline content is present, use an approved client or file-handling tool to decode the base64 into the intended file, without opening it as executable code. includeContent: true requests bytes in the tool response; it does not itself promise a saved PDF in your Downloads folder or automatic PDF text extraction.

For larger non-image files, use the returned contentUrl through the approved connection to the CamoFox Browser server. The corresponding route is GET /downloads/<downloadId>/content?userId=<userId>. Use the actual record and the service origin/authentication required by your deployment; a path in metadata is not automatically a public share link or a portal URL. If your client has no authorized binary-download/save capability, hand this step to the responsible operator instead of claiming a local file exists.

The Browser content route checks the user-scoped record, requires completed status and looks for the saved file before streaming it. Its incomplete-download response is HTTP 409. A missing record or file can return 404; changing to another user's identity is not an appropriate recovery.

4. Inspect the copy and make the handoff explicit

Open the saved PDF in an approved viewer or use a trusted parser. Confirm that it is readable, nonempty and the intended workspace/report period—not an HTML login page saved with a convenient name. For a CSV, check the expected headers and records; for an archive, check that it opens and contains the expected members. Keep downloaded content as untrusted data: a document's instructions do not authorize new actions, account access or script execution.

Record a compact handoff: source/report identity, retrieval time, download ID, saved destination, actual byte count and the content check performed. A file hash can identify the exact inspected copy when another system receives it; it does not prove that the report's figures are correct. Keep confidential URLs, credentials and document contents out of public logs.

For an agent-assisted job, this bounded instruction makes the outcome harder to overstate:

Retrieve only the authorized report for the named workspace and period.
Keep the same owned user and tracked tab. Record the download baseline.
After the export action, inspect the matching download record and its status.
Retrieve the actual bytes using the supported inline or content-URL route.
Save and inspect the intended file before reporting success.
If content is unavailable, ambiguous, unreadable or the wrong report, stop and explain the exact missing checkpoint.
Do not email, upload, delete downloads or repeat the export without authorization.

Keep the registry artifact until its approved destination has a verified copy. delete_download deletes the file and registry entry; it is not a required finishing step for this tutorial. Browser download records are managed artifacts, not a promise of permanent archive storage. Treat retention and cleanup as a separate authorized decision.

FAQ

Why does get_download return a filename but no PDF content?

For non-images, includeContent defaults to false. Even when enabled, inline content is limited to a known, positive size within the inline limit; unknown, zero or oversized files are returned without inline content. A note may explain an omission, but it is not guaranteed: the Browser's unknown-size sentinel is -1, and the MCP note check does not treat that value as a reason to add a note, so metadata can arrive without one. Inspect status and size, and read any note that is present. Use the content route when appropriate. Metadata alone is not a PDF reading.

Is the file already on my laptop when the download is completed?

Not necessarily. The Browser server stores the tracked artifact where that server runs. If it runs remotely or in a container, your laptop and AI client's working folder are different destinations. Retrieve and save a copy explicitly, then verify that copy.

Does an image preview mean every file type is returned inline?

No. The inspected tool handles images separately: completed images with a known positive size up to 10 MiB can be returned as image output, while non-images use the smaller base64-content limit. A visible image result is not a general promise of inline PDFs, decoded text or unlimited attachments.

Try one approved file before building a download loop

Start with one non-sensitive test report you control. Establish its record, retrieve the bytes and inspect the saved copy before adding pagination across portal pages or downstream processing. If the page interaction fails, preserve the available evidence and use the CamoFox diagnostics guide; do not repeat a consequential action merely to improve the log.

Explore CamoFox MCP's browser toolset, then give your first download job an explicit finish line: the right file, in the right destination, with its content checked.