Skip to main content

Connect FolderSpan to Codex

Codex CLI, the Codex IDE extension, and the ChatGPT desktop application can use FolderSpan MCP tools through Streamable HTTP. They share MCP configuration on the same Codex host.

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. Keep it in a local environment variable or password manager, not project files, command history, or chat. See Using MCP tools for prompts, responses, and permissions.

Add the connection with Codex CLI​

Set the token in the same environment that launches Codex:

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

Add the server, replacing the URL with the actual address shown by FolderSpan:

codex mcp add folderspan \
  --url 'https://127.0.0.1:52137/mcp' \
  --bearer-token-env-var FOLDERSPAN_MCP_TOKEN

This saves the connection to ~/.codex/config.toml, without saving the token value there. Equivalent configuration:

[mcp_servers.folderspan]
url = "https://127.0.0.1:52137/mcp"
bearer_token_env_var = "FOLDERSPAN_MCP_TOKEN"

When launching from a desktop icon, ensure that application's process can read FOLDERSPAN_MCP_TOKEN. Exporting it in a terminal does not update an already-running desktop application.

Verify the connection​

Inspect saved MCP servers:

codex mcp get folderspan
codex mcp list

After saving, restart the desktop application or IDE extension, or start a new Codex CLI session. In the TUI, /mcp shows 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​

Check that FOLDERSPAN_MCP_TOKEN contains the complete token and is readable by the process launching Codex. Disabled, regenerated, or deleted tokens require updating the variable and restarting Codex.

HTTPS certificate validation fails​

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

Only on a trusted, isolated LAN, you can temporarily use the HTTP address shown by FolderSpan:

codex mcp remove folderspan
codex mcp add folderspan \
  --url 'http://127.0.0.1:52137/mcp' \
  --bearer-token-env-var FOLDERSPAN_MCP_TOKEN

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

FolderSpan tools are missing​

  • Restart the client or start a new Codex session after adding MCP. Existing sessions do not dynamically load new tools.
  • Run codex mcp get folderspan and check that the server is enabled and its URL is correct.
  • Check token permissions. FolderSpan's tools/list returns only tools authorized for that token.
  • Check that firewalls and guest-network isolation allow access to the MCP port.

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 the permissions or connection in FolderSpan, then ask Codex to retry.

Remove the connection​

codex mcp remove folderspan

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

See the official OpenAI MCP documentation for more configuration options.