Blixt Documentation v2.11

AI agents reach BlixtFS through the Model Context Protocol (MCP). An agent sees the same tree as a mount: one directory per cloud provider, with each bucket inside it. MCP is only available in the Enterprise or High Performance editions.

The MCP server default port is 8090. Example usage with Claude Code:

# Claude Code
claude mcp add --transport http blixtfs http://blixt.example.com:8090 \
  --header "Authorization: Bearer $MCP_TOKEN"

Reaching the MCP server from another machine

By default the MCP server listens on loopback interfaces only, so only agents on the same host can use it. To reach it over the network, or through a container’s published port:

  1. Set MCP_TOKEN on the server to a random hex string of 32 to 128 characters, for example the output of openssl rand -hex 32.
  2. Set protocol.mcp.public: true. A public MCP server refuses to start without MCP_TOKEN.
  3. Publish port 8090.

The connection is not encrypted, including the token. Public MCP Blixt servers should only run on a network that you trust.

Starting the MCP server from the agent

An agent can also start the MCP server itself and talk to it over standard input and output, as many agents do for local tools. Nothing then listens on the network, and MCP_TOKEN is not needed. The agent’s host needs the mcp_server binary, the address of the BlixtFS config service, and the BlixtFS auth token:

# Claude Code
claude mcp add blixtfs -e AUTH_TOKEN="$BLIXT_AUTH_TOKEN" \
  -- mcp_server --config_service=blixt.example.com

The audit log records the agent as the user that started it, or as the name given with --mcp_client_name. The connection to the config service is not encrypted, so run this on the BlixtFS server itself or on a network you trust.

What agents can do

Tool What it does
list_directory Lists a directory.
stat Reports a file’s type, size, modification time and version, and its ETag, MD5, content type and user metadata.
read_file Reads a file, or part of one.
glob Finds files by name pattern.
search Finds text in files.
write_file Writes a whole file, replacing any file of that name.
move Moves or renames a file or directory within one bucket. Directories of up to 1,000 objects.
delete Deletes a file or an empty directory.

Agents can also read files as MCP resources, and subscribe to a file or directory to hear about changes. BlixtFS checks subscribed paths for changes regularly; nothing is pushed to it.

Agents can only read by default. To let them change files, set protocol.mcp.read_only: false and list the tools they may use in protocol.mcp.write_tools, for example [write_file, move]. A read-only bucket stays read-only either way.

Every tool call is written to an audit log, one JSON line each, at protocol.mcp.audit_path (standard error by default). The log records who called which tool on which path, and the result, but no file content. Each caller is limited per bucket, by default to 20 requests and 50 MB of reads per second, and to 256 KiB per read_file call.