MCP
Connect AI agents to BlixtFS using the Model Context Protocol.
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:
- Set
MCP_TOKENon the server to a random hex string of 32 to 128 characters, for example the output ofopenssl rand -hex 32. - Set
protocol.mcp.public: true. A public MCP server refuses to start withoutMCP_TOKEN. - 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.