Skip to main content

Connect FolderSpan to Claude Code

Claude Code can use FolderSpan MCP tools through Streamable HTTP. This guide saves the connection in user-level configuration so it is available across that user's projects.

Prepare connection information​

  1. Open Toolbox > MCP in FolderSpan and start the service.
  2. Create a token. Start with View only and add permissions after verifying the connection.
  3. Copy the recommended address and complete token. The address ends in /mcp, for example:
https://127.0.0.1:52137/mcp

The complete token is shown only once. Save it in a password manager, not project files, public configuration, or chat. See Using MCP tools for prompts, responses, and permissions.

Add an MCP connection​

Read the complete token into the current terminal using hidden input:

read -rsp 'FolderSpan MCP Token: ' FOLDERSPAN_MCP_TOKEN
printf '\n'

Add a user-level server:

claude mcp add --transport http --scope user \
  folderspan 'https://127.0.0.1:52137/mcp' \
  --header "Authorization: Bearer ${FOLDERSPAN_MCP_TOKEN}"
unset FOLDERSPAN_MCP_TOKEN

This keeps the complete token out of shell history, but Claude Code saves the header in the current user's private configuration. Do not copy or commit that configuration file.

Verify the connection​

Inspect server details and state:

claude mcp get folderspan
claude mcp list

A working connection shows folderspan as Connected. In a Claude Code session, /mcp also displays connection states and loaded tools.

Start with a read-only check:

Use FolderSpan MCP to list currently online devices. Do not make any changes.

With files.read, specify a source and absolute path:

Use FolderSpan MCP to list direct children of /Documents in the Local source. Return only names, types, and sizes.

Troubleshooting​

HTTP 401​

The header's token is incomplete, disabled, regenerated, or deleted. Remove the folderspan connection and add it again with the new complete token.

HTTPS certificate validation fails​

FolderSpan protects HTTPS with a device certificate. If Claude Code does not trust it, prefer adding it to the operating system's trust store or the CA chain used by Claude Code. Do not disable TLS validation globally.

Only on a trusted, isolated LAN, you can remove the connection and add it again with this URL:

http://127.0.0.1:52137/mcp

HTTP sends tokens, file paths, and tool parameters in clear text. Do not use it over public or untrusted networks.

Failed to connect​

  • Confirm the FolderSpan MCP service is enabled and still uses port 52137.
  • Run claude mcp get folderspan and check the URL and header.
  • Check that firewalls allow access to FolderSpan's MCP port.
  • Reopen the Claude Code session after changing the server or token, then check /mcp again.

FolderSpan tools are missing​

  • Check token permissions. FolderSpan's tools/list returns only tools authorized for that token.
  • In Claude Code, open /mcp and confirm folderspan is enabled and connected.
  • If using project-level .mcp.json, first approve the server in an interactive Claude Code session.

A tool returns permission_denied or not_connected​

permission_denied means token permissions, sensitive-path rules, or device path authorization disallow the operation. not_connected means the device, share, or network location is unavailable. Correct permissions or connections in FolderSpan, then ask Claude Code to retry.

Remove the connection​

claude mcp remove --scope user folderspan

Disable or delete its token on FolderSpan's MCP page when this client is no longer used.

See the official Anthropic MCP documentation for more configuration options.