Using MCP tools

FolderSpan provides 36 MCP tools for files, bookmarks, favorites, recent items, file tasks, devices, network locations, and sync tasks. After connecting Codex or Claude Code, describe your goal in natural language. The AI chooses folderspan_ tools allowed by the token and turns structured results into an answer; you do not need to write tool arguments manually.

This page covers prompts and returned information for each tool group.

What to include in a prompt

A clear request usually specifies:

1. Source: this device, another device, a share, or a network location.
2. Location: source name and absolute path, or a known stable ID.
3. Operation: list, read, write, rename, copy, move, delete, share, or run sync.
4. Conflict handling: error, skip, overwrite, or rename for copies and moves.
5. Confirmation: for writes, overwrites, moves, deletions, sharing, or connections, ask the AI to show its plan and wait for confirmation.
6. Response format: request IDs, paths, states, times, and error codes when you need original details rather than only a summary.

Use this template:

Use FolderSpan MCP tools for the following task:
- Source: <Local, Device, Share, or Network, and the source name>
- Path: <absolute path>
- Destination: <source and absolute path; remove this line if unused>
- Operation: <what to do>
- Conflict policy: <error, skip, overwrite, or rename; remove if unused>
- Execution: read metadata first and restate the source, destination, and impact. Wait for my confirmation before making changes.
- Response: return actual tools used, item IDs, full paths, execution states, and failure reasons.

tip

If you do not know a device, network, sync-task, or file-task ID, give its name and ask the AI to “list candidates first; do not guess IDs.” It can use the returned IDs for the next step.

Describe file locations

All file tools locate items through protocol, sourceId, and path. Calling a tool does not change the directory currently displayed in FolderSpan.

Source	How to describe it	sourceId	path
Local	“This device” or “local”	Empty string	Absolute path on this device
Device	“The device named Office PC”	Stable ID of a connected device	Absolute path used by that device
Share	“The share named …” or its ID	Stable ID of an available share	Absolute path used by that share
Network	“The network location named Backup drive”	Stable ID of a connected network location	Absolute path used by the remote endpoint

Examples:

List the direct children of `/Documents` on this device. Return full paths, types, sizes, and update times. Do not modify files.

List configured network locations, find Backup drive, and tell me its ID and connection state. Do not connect yet.

Device, Share, and Network sources must be currently available; otherwise, tools return not_connected or not_found. Paths must be absolute paths accepted by that endpoint and cannot contain traversal segments such as . or ...

Understand the AI's answer

FolderSpan returns both JSON text and structured results. AI clients usually turn fields into prose instead of displaying all JSON. To inspect details, ask:

Do not omit returned fields. Show IDs, protocol, sourceId, path, states, times, and nextCursor.

Common response rules:

• Lists: items and nextCursor. A nonempty cursor means another page is available; ask the AI to keep reading pages until finished.
• Pagination: limit defaults to 50, with a range of 1–200. The opaque cursor must not be edited manually.
• Times: fields such as createdAt, updatedAt, lastAccessed, and expiresAt contain timestamps. You can request local date/time conversions too.
• Changes: successful create, edit, write, and connect operations generally return the complete updated object. Deletions return a boolean or count.
• Asynchronous file tasks: copy, move, and delete return only taskId; query the task for progress and failures.
• Errors: code and message. The AI should explain failures rather than describing them as success.

Browse and read files

Example prompts

List direct children of local `/Documents`, grouped into directories, documents, and other files. Show each full path, size, update time, and allowed operations. Continue through all pages.

Read local `/Documents/report.txt`. Return its size and update time first, then read the whole file in chunks and summarize it. Do not modify it.

Tools and responses

Tool	Permission	Purpose	Response
folderspan_files_list	files.read	List a directory's direct children	items, nextCursor; entries include name, path, directory flag, MIME type, size, creation/update times, source, permissions, hidden/symlink flags, and sensitive-item information
folderspan_file_info	files.read	Inspect a file or directory	Complete metadata with the same fields as a directory entry
folderspan_file_read	files.read	Read or summarize a file	totalSize, offset, returnedLength, hasMore, encoding, data

Entry permissions indicate whether the endpoint permits read, write, rename, delete, and share. endpoint identifies the actual protocol and sourceId.

Reading defaults to offset=0 and 262144 bytes, with 1–4194304 bytes allowed per call. Text uses utf8; binary content uses base64. When hasMore is true, continue with an updated offset.

An AI may present the result as:

Read Local `/Documents/report.txt`:
- Total size: <totalSize> bytes
- This range: <returnedLength> bytes from <offset>
- More content available: <hasMore>
- Summary: <summary generated from data>

Write, create directories, and rename

Example prompts

Read the size and update time of local `/Notes/todo.txt`. If the file has not changed, append “Backup complete” and return the actual bytes written and new file information.

Create local `/Documents/Archive`. If it already exists, return the existing directory's information. Do not delete or overwrite anything.

Tools and responses

Tool	Permission	Purpose	Response
folderspan_file_write	files.write	Create, overwrite, or append file content	entry, bytesWritten, mode; entry is the complete post-write metadata
folderspan_directory_create	files.write	Create one directory level	Complete new-directory metadata, or the existing directory if already present
folderspan_file_rename	files.write	Rename a file or directory	Complete renamed-item metadata

Write modes are overwrite and append, defaulting to overwrite. Decoded content cannot exceed 524288 bytes per call. To avoid overwriting a file changed by another program, first call folderspan_file_info, then pass its size and updatedAt as expectedSize and expectedUpdatedAt. Mismatched preconditions return conflict without writing.

Copy, move, delete, and file tasks

Example prompts

Copy local `/Documents/report.pdf` to `/Reports` on Backup drive, using `rename` for conflicts. Inspect both locations and show a plan first. Wait for confirmation, then create the task and keep checking until it finishes. Summarize progress and failures.

Prepare to delete local `/Downloads/old.zip`. Show its full path, size, and update time first. Wait for confirmation before deleting, then query the final task state.

Create tasks

Tool	Permission	Purpose	Initial response
folderspan_files_copy	files.write	Copy files to a destination directory	taskId
folderspan_files_move	files.write	Move files to a destination directory	taskId
folderspan_files_delete	files.write	Delete files or directories	taskId

Copy and move support error, skip, overwrite, and rename. A move deletes each source item only after its destination copy completes. If source deletion fails, retrying does not copy it again.

Query and control tasks

Tool	Permission	Follow-up	Response
folderspan_tasks_list	tasks.read	List recent file tasks and progress	Paginated tasks
folderspan_tasks_get	tasks.read	Query a task ID's current state	Task details
folderspan_tasks_pause	tasks.control	Pause a task ID	Updated task details
folderspan_tasks_resume	tasks.control	Resume a task ID	Updated task details
folderspan_tasks_cancel	tasks.control	Cancel a task ID	Updated task details
folderspan_tasks_delete	tasks.control	Delete a finished task record	deleted

Task details include:

• id, type, status: identifier, type, and current state.
• protocol, sourceId, values: source and task parameters without tokens or passwords.
• progressCurrent, progressTotal: current and total progress.
• failureCount, failurePath, failureMessage: failure count and most recent failure path and reason.
• availableActions: currently allowed pause, resume, cancel, or delete actions.

Running and paused tasks cannot be deleted directly. Ask the AI to use availableActions rather than blindly trying disallowed operations.

Bookmarks

Example prompts

List local bookmarks with IDs, names, types, paths, sort values, and source availability.

Create a local bookmark named Work documents, with type `document` and path `/Documents/Work`. Return its ID and full information.

Tools and responses

Tool	Permission	Operation	Response
folderspan_bookmarks_list	bookmarks.read	List bookmarks under a protocol and sourceId	items, nextCursor
folderspan_bookmarks_create	bookmarks.write	Create a bookmark	Complete new bookmark
folderspan_bookmarks_update	bookmarks.write	Update name, type, path, icon, or sorting by ID	Complete updated bookmark
folderspan_bookmarks_delete	bookmarks.write	Delete by bookmark ID	deleted

Bookmarks include id, protocol, sourceId, name, type, path, icon, sort, createdAt, updatedAt, and sourceAvailable. Types are home, image, audio, video, document, download, and custom.

Favorites and recent items

Example prompts

List all favorites with pinned entries first. Return each ID, file location, type, size, and update time.

Favorite local `/Documents/manual.pdf`. Read its information first and return the favorite ID after success. If already saved, return only the existing record.

Favorite tools

Tool	Permissions	Operation	Response
folderspan_favorites_list	favorites.read	List favorites	items, nextCursor
folderspan_favorites_add	favorites.write, files.read	Add by file location	Complete new or existing favorite
folderspan_favorites_remove	favorites.write, files.read	Remove by file location	removed
folderspan_favorites_pin	favorites.write	Pin or unpin by favorite ID	Complete updated favorite

Favorites include id, locator, name, isDirectory, mimeType, size, createdAt, updatedAt, and pinned. The locator contains the source endpoint and full path.

Recent-item tools

Tool	Permission	Purpose	Response
folderspan_recents_list	recents.read	List recent history	items, nextCursor; entries include ID, location, name, type, size, creation/update times, and lastAccessed
folderspan_recents_delete	recents.write	Delete specified history IDs	deletedCount
folderspan_recents_clear	recents.write	Clear all recent history	deletedCount

These tools manage existing history and do not create artificial visits. Clearing affects every record; ask the AI to return the count and wait for confirmation first.

HTTP and WebRTC devices

Example prompt

List currently discovered HTTP devices, grouped as connected, connecting, awaiting peer approval, and discovered. Show IDs, names, addresses, platforms, and states. Do not connect yet.

Discovery and connection tools

Tool	Permission	Operation	Response
folderspan_devices_list	devices.read	View online HTTP devices	Devices grouped by connection state
folderspan_device_connect	devices.connect	Connect to an HTTP device by ID	Connected-device details
folderspan_webrtc_devices_list	devices.read	View discovered WebRTC devices	Devices grouped by connection state
folderspan_webrtc_device_connect	devices.connect	Connect to a WebRTC device by ID	Connected-device details

Device tools use online devices already discovered by FolderSpan; they do not actively scan network ranges. Groups are connected, connecting, approvalRequired, and discovered. Entries include id, name, host, port, platform, transport, and status. Connection tools do not bypass certificate checks or peer approval.

Network locations

Example prompts

List configured network locations with IDs, names, protocols, hosts, stable source IDs, connection states, and whether they are saved. Do not return credentials.

Find the unique network location named Backup drive. Show its ID and state first. Wait for confirmation before testing and connecting.

Tool	Permission	Operation	Response
folderspan_networks_list	networks.read	List configured network locations	items, nextCursor
folderspan_network_connect	networks.connect	Validate the root and connect by ID	Connected network-location details

Entries include id, sourceId, name, protocol, host, connected, and persisted. Saved usernames, passwords, private keys, and other credentials are not returned. Connection failures return not_connected.

Sync tasks

Example prompts

List sync tasks and find Document backup. Return its ID, enabled state, endpoints, latest state, last run time, and next run time. Do not run it yet.

Run Document backup. First verify the name uniquely identifies one task and tell me its source and destination. Wait for confirmation, then run it and return the state after triggering.

Tool	Permission	Operation	Response
folderspan_sync_list	sync.read	List sync tasks	items, nextCursor
folderspan_sync_run	sync.run	Run an idle task now	Task details after triggering

Details include id, name, enabled, sourceType, sourceRef, sourcePath, targetType, targetRef, targetPath, lastStatus, lastRunAt, and nextRunAt. Running returns immediately without waiting for completion. A queued or running task returns conflict.

Share files

Example prompts

Create a time-limited LAN share link for local `/Public/manual.pdf`, hiding hidden files and disabling uploads. Return all addresses, the expiration time, and the HTTPS fingerprint.

List connected HTTP devices first. Find the unique device named Tablet and share local `/Public/manual.pdf` with it, excluding hidden files. Return the operation ID and receiving state.

Tool	Permissions	Operation	Response
folderspan_files_share_link	files.share, files.read	Create a time-limited LAN link	urls, expiresAt, allowHidden, allowUpload, fileCount, tlsFingerprintSha256
folderspan_files_share_device	files.share, files.read	Share to a connected HTTP device	operationId, deviceId, status, fileCount

Enabling uploads also requires files.write, and the FolderSpan host must already allow uploads. Symbolic links and items whose endpoints prohibit sharing are rejected. Device sharing accepts only online, connected HTTP devices.

Errors and follow-ups

Failures return code and message. Common codes:

Code	Meaning	Suggested follow-up
invalid_argument	Invalid arguments, paths, encoding, read range, or port	Identify the invalid argument and retry with real values from a list result.
not_found	Missing file, record, task, tool, or source	List candidates again with IDs and paths; do not guess.
permission_denied	Insufficient token permissions or endpoint, path, or sensitive-item restrictions	Explain the missing permission; do not bypass restrictions.
conflict	Destination exists, write preconditions changed, or sync is already running	Read the current state and explain the conflict; do not overwrite.
invalid_state	Task state disallows the requested control action	Return availableActions and suggest only allowed actions.
not_connected	Device, share, or network source is disconnected	List states and identify the correct source before asking whether to connect.
unsupported	Endpoint or platform lacks the capability	Identify the unsupported endpoint and available alternatives.
io_error	Endpoint file read/write error	Preserve the failure path and message; stop further changes.
cancelled	Operation was cancelled	Return progress before cancellation and remaining actions.
internal_error	Internal service operation failed	Preserve the code and operation context; do not repeat destructive actions.

Safe use

• Configure the token in the MCP client, never in a chat prompt.
• Start with View only. Verify sources, paths, and responses before adding change or control permissions.
• Before deletion, overwrite, move, sharing, or connection, ask the AI to restate targets, scope, and conflict policy and wait for confirmation.
• Obtain actual IDs from list tools. Do not guess source, device, task, or network IDs from names.
• If a tool is missing, check its token permissions, then refresh the client's tool list.
• Read large files in chunks. When hasMore is true, continue using the returned offset information rather than exceeding request limits.