# Connecting AI Agents to Backblaze B2 with MCP: Setup and Architecture Connecting AI agents to Backblaze B2 with the Model Context Protocol gives language models direct access to cloud buckets, archives, and object lifecycles. While raw object storage provides cost-effective persistence for bulk artifacts, production workflows require passage-level indexing to prevent token saturation. This guide covers setting up the Backblaze B2 MCP server and integrating indexed workspaces for agent retrieval. Source: https://fast.io/resources/backblaze-b2-mcp/ Author: [Tom Langridge](https://fast.io/authors/tom-langridge/) Last reviewed: 2026-10-17 ## How the Model Context Protocol Connects AI Agents to Object Storage Giving an AI agent direct access to an object storage bucket solves file persistence, but it introduces an immediate context challenge: unindexed object retrieval forces the agent to download entire files into memory just to answer a question about a single paragraph. A dense operational log or an extensive documentation archive consumes massive context before the model even begins its reasoning. Connecting agents to cloud storage through the Model Context Protocol requires separating bulk byte archival from active, indexed context retrieval. A Backblaze B2 MCP server is a Model Context Protocol endpoint that exposes Backblaze B2 cloud buckets and objects directly to AI assistants as searchable tools. The Model Context Protocol (MCP), created by Anthropic and adopted across developer tools such as Claude Desktop, Cursor, and Cline, provides a universal standard for models to discover and execute external tools. Rather than writing custom API wrappers or ad-hoc scripts for every model, developers expose storage primitives as structured tools. The AI assistant queries bucket contents, requests file metadata, and executes file transfers using its native tool-calling loop. Backblaze B2 charges $6.95 per terabyte per month for object storage. Backblaze B2 offers S3-compatible cloud storage at one-fifth the cost of traditional hyperscalers, with free egress up to three times average monthly storage. For teams running autonomous code agents, data extraction pipelines, or media processing jobs, these economics make B2 an appealing destination for cold datasets, training checkpoints, and system backups. Without hyperscaler egress markups or complex pricing tiers, agents can stage and persist large artifacts reliably. Raw object storage operates on bucket and key primitives. Buckets store unstructured binary blobs, leaving content indexing, text extraction, and semantic search to external software. When an agent needs to retrieve a specific answer from stored files, raw bucket access provides no native search beyond prefix matching on filenames. The agent must read the entire object payload over the network, parse the raw text, and load the entire content into its context window. Understanding how to structure MCP connections around both raw storage and indexed workspaces is essential for production deployments. ## Why Security Boundaries Matter for Backblaze B2 MCP The official open-source Backblaze B2 MCP server runs as a local or remote process that translates Model Context Protocol tool requests into Backblaze B2 Native API and S3-compatible API calls. In desktop environments like Claude Desktop or Cursor, the server runs over standard input and output (stdio) as a child process. The AI client communicates with the server via structured JSON-RPC messages, discovering available storage tools during session initialization. The server exposes operations across bucket management, file handling, and storage analytics: - **Bucket management**: Creating private buckets, updating lifecycle rules, and configuring object retention or legal holds. - **File operations**: Uploading files, generating pre-signed download URLs, hiding or deleting specific file versions, and listing objects by prefix. - **Multipart uploads**: Coordinating large-file multipart transfers so that multi-gigabyte files can be uploaded without timeouts. - **Storage analytics**: Inspecting bucket storage consumption, identifying unfinished multipart uploads, and surfacing large files. Security in the Backblaze B2 MCP server begins at the credential boundary. The server does not maintain an independent authentication layer or grant blanket administrative rights to the language model. Every tool call executed by the agent operates strictly within the permissions of the connected Backblaze B2 application key. If an application key is scoped to a single bucket with read-only permissions, the MCP server restricts the agent to reading objects in that specific bucket. Any request to write files, modify bucket settings, or access unlisted buckets fails immediately at the storage API layer. Autonomous agents can make errors when interpreting user intent. To prevent data loss, the B2 MCP server includes configurable policies for destructive actions like deleting files, removing buckets, or disabling object retention. Local stdio deployments default to requiring explicit user confirmation before executing a deletion, while hosted HTTP deployments can be configured to reject destructive operations entirely. By pairing narrow application keys with server-level confirmation rules, teams prevent unintended deletions. A common failure in early agent integrations was passing raw file payloads through the language model prompt. Shoveling megabytes of binary data through an LLM context window exhausts token limits and increases API latency. The Backblaze B2 MCP server resolves this by coordinating transfers via short-lived URLs. When an agent prepares an export or needs to download a large artifact, the server generates a pre-signed URL. Bulk bytes flow directly between the client system and Backblaze B2 storage, keeping payload data out of the conversation history while leaving the agent in control of the orchestration. ## How to Set Up the Backblaze B2 MCP Server in Claude Desktop and Cursor Connecting your AI assistant to Backblaze B2 requires three components: 1. A supported Node.js runtime (version 22 LTS or higher installed on your machine). 2. A Backblaze B2 account with an application key. 3. An MCP-compatible client, such as Claude Desktop or Cursor. Log in to the Backblaze admin console, open Application Keys, and select Add a New Application Key. Never use your Master Application Key for AI agent connections. Name the key with a clear identifier such as `agent-b2-storage`, select the target bucket, and assign only the necessary capabilities. For read-heavy workflows, grant `readFiles` and `listBuckets`. For agents that generate outputs, add `writeFiles`. Save the generated `keyID` and `applicationKey` securely. Claude Desktop discovers MCP servers through its local configuration file. On macOS, this file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, it is located at `%APPDATA%\Claude\claude_desktop_config.json`. Add the server entry under the `mcpServers` object: ```json { "mcpServers": { "backblaze-b2": { "command": "npx", "args": ["-y", "@backblaze-labs/b2-mcp"], "env": { "B2_APPLICATION_KEY_ID": "your-application-key-id", "B2_APPLICATION_KEY": "your-application-key-secret" } } } } ``` Restart Claude Desktop after saving the configuration file. The hammer icon in the prompt input will display the connected Backblaze tools. For Cursor, open Cursor Settings, select Features, open MCP Servers, and select Add New MCP Server. Alternatively, add the configuration to your configuration file at `~/.cursor/mcp.json`: ```json { "mcpServers": { "backblaze-b2": { "command": "npx", "args": ["-y", "@backblaze-labs/b2-mcp"], "env": { "B2_APPLICATION_KEY_ID": "your-application-key-id", "B2_APPLICATION_KEY": "your-application-key-secret" } } } } ``` Cursor starts the server process automatically and exposes the B2 storage tools to its composer and chat agents. ### Verifying the Connection and Running Initial Storage Queries Test the setup by opening a new chat session and issuing an inspection prompt: "List the Backblaze B2 buckets available to this key." The assistant invokes the storage tools and returns the bucket names and types. You can then request file listings or upload a test document: "Upload test-summary.txt to bucket dataset-archive with content: Pipeline run completed." Check the Backblaze B2 web console to confirm the object appeared with the expected metadata. ### Troubleshooting Connection and Authorization Errors If the agent reports that no tools are available, check your local Node.js installation by running `node --version` in your terminal. Ensure `npx` can download packages without corporate proxy interference. If tool calls return unauthorized errors, verify that your application key has not expired and that the bucket name matches the key's allowed bucket ID. Remember never to paste your raw application key directly into the chat prompt, as credentials should remain strictly within client configuration files or environment variables. ## Comparing Raw Object Storage with Indexed Workspace Storage Most tutorials on AI storage stop after demonstrating a basic read or write script. While uploading a generated file to an S3 or B2 bucket works for basic persistence, this raw approach creates operational hurdles when teams attempt to build autonomous workflows. Treating object storage as a simple file dump overlooks three major challenges: token overhead, unstructured retrieval, and team permission boundaries. Language models do not read files the way humans do. When an agent interacts with raw object storage through basic MCP tools, it must download the entire object payload into memory to answer any substantive question. If your bucket holds a dense document containing financial statements, technical specifications, or compliance standards, the agent must fetch the entire file, convert the document to text, and ingest the entire corpus into its context window. A single query can consume thousands of prompt tokens, driving up inference costs and rapidly approaching model context limits. The following table contrasts raw object storage MCP access with indexed workspace storage: | Dimension | Raw Backblaze B2 MCP | Fast.io Indexed Workspace MCP | | --- | --- | --- | | **Storage Architecture** | Flat object buckets with key prefixes | Structured workspaces, folders, and shared portals | | **Retrieval Mechanism** | Full object download via pre-signed URL | Passage-level semantic search and hybrid text matching | | **Context Token Usage** | High (entire file payload loaded into context) | Low (only relevant, cited passages injected) | | **Search Capability** | Exact filename and prefix filtering | Full-text, semantic meaning, and metadata value search | | **Access Control** | Infrastructure API keys per bucket or prefix | Organization, workspace, and share member roles | | **Human Collaboration** | Cloud console, CLI tools, or custom portals | Web interface, inline previews, comments, and notes | | **Document Extraction** | Custom external parsing and OCR scripts | Native Metadata Views for structured schema extraction | Raw object storage is designed for machine-to-machine infrastructure, not cross-functional human teams. Handing raw B2 application keys to non-technical collaborators or client stakeholders introduces substantial risk. If a marketing team, legal counsel, or client needs to review agent deliverables, they cannot easily browse raw bucket consoles or parse JSON metadata. Production agent systems require a collaboration layer where agents and humans share the same versioned workspace, review files with inline previews, and share deliverables securely without exposing infrastructure credentials. ### Token Overhead and Context Window Saturation When an agent downloads a comprehensive operational manual from raw storage, it consumes memory that could otherwise hold reasoning steps, conversation history, and tool definitions. This token overhead compounds when an agent evaluates multiple candidate files to find an answer. Indexed workspaces eliminate this bottleneck by chunking, vectorizing, and indexing documents upon arrival. When the agent issues a search query, the workspace returns only the most relevant paragraphs with exact document and page citations. The agent gets the precise factual ground it needs using a fraction of the tokens required for a full-file download. ## How to Build a Two-Tier Architecture with Backblaze B2 and Fast.io Instead of choosing between raw cloud object storage and collaborative workspaces, high-performing engineering teams implement a two-tier storage architecture. In this model, Backblaze B2 is the cold, bulk persistence layer, while Fast.io provides the active, indexed collaboration substrate. The two tiers divide storage responsibilities according to access frequency and collaboration requirements: **Tier 1: Cold and Bulk Persistence in Backblaze B2** Large media assets, raw sensor logs, model weight checkpoints, database dumps, and long-term customer archives reside in Backblaze B2 buckets. With low base storage rates, B2 provides economical long-term retention without egress penalties. Agents use the B2 MCP server to push finished batch exports or archive completed projects directly into B2 buckets. **Tier 2: Active Context and Human Collaboration in Fast.io** Active documents, project briefs, client contracts, and shared specifications live in Fast.io workspaces. Fast.io is an intelligent workspace platform designed for agentic teams, where files are automatically indexed for semantic search, summarization, and citation-backed Q&A when Intelligence is enabled. Many teams already maintain active project files across corporate cloud storage providers like Google Drive, Dropbox, Box, or OneDrive. Fast.io Cloud Sync connects Google Drive, Dropbox, Box and OneDrive folders directly to a workspace, one-way or two-way, on a schedule or on demand. It is never continuous, live or real-time. SharePoint document libraries can also be synchronized through the OneDrive for Business connector. Active files synchronize into the workspace without moving your organization's entire storage infrastructure. Agents connect to Fast.io through its remote MCP server over Streamable HTTP. Interactive clients like Claude Desktop and Claude Cowork connect with OAuth at `https://mcp.fast.io/mcp/tools`. Coding agents like Claude Code, Cursor, VS Code, and Cline connect at `https://mcp.fast.io/mcp/code`. Setup instructions are documented at [Fast.io MCP Setup](https://mcp.fast.io/docs) and tool details at [Fast.io Skill Guide](https://mcp.fast.io/skill.md). Instead of downloading raw files, the agent queries Fast.io's consolidated MCP toolset to perform hybrid search across documents, retrieving only relevant passages with document and page citations. When agents need structured information from stored documents, Fast.io's [Metadata Views](/product/document-data-extraction/) convert files into queryable spreadsheets. Users or agents describe the required columns in plain English, and the system extracts typed fields (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time) from PDFs, Word docs, spreadsheets, and scanned records. Agents query these extracted values directly through MCP, eliminating the need to write custom OCR or document parsing pipelines. Connecting agents through dedicated workspace connectors delivers measurable speed and cost advantages over unindexed retrieval. In connector evaluations published at [Fast.io Benchmarks](https://fast.io/benchmarks/), Fastio was measured the fastest and the lowest cost of the providers tested. By retrieving only the specific passages required for a prompt rather than hauling whole files across the wire, agents minimize latency and keep inference costs predictable. Governance remains transparent across both human and agent actions. Fast.io maintains a detailed activity log of storage changes, including uploads, edits, moves, and deletions, as well as membership and permission updates. It does not record read-only events such as views or downloads. Every file maintains full version history, allowing teams to inspect concurrent agent modifications and restore prior versions whenever needed. Agents can also autonomously build workspaces and shares, and then initiate an ownership transfer to hand control back to human administrators while retaining operational access. When agent outputs are finalized, teams distribute deliverables using Fast.io's purpose-built shares. Send, Receive, and Exchange shares can be configured with expiration dates, access controls, and custom branding. External clients open shared portals in their browser without creating an account or logging into cloud infrastructure consoles. Downloads can be disabled on sensitive shares, and clients can upload requested materials directly into a secure Receive share without relying on insecure email attachments. Fast.io organizations operate on tiered subscription plans (Starter, Business, and Enterprise) with monthly or annual billing options. Monthly plans begin with a 14-day trial that requires a credit card, ending early if trial credits are exhausted. Each plan includes dedicated workspace allocations and monthly credits for AI operations, while additional storage and bandwidth are billed separately in money. ## Frequently asked questions ### Can AI agents connect directly to Backblaze B2? Yes. Using the open-source Backblaze B2 MCP server, AI agents running in MCP-compatible clients such as Claude Desktop, Cursor, or Cline can execute bucket and object operations directly. Connections use standard Backblaze B2 application keys, allowing agents to list buckets, upload generated files, and manage object lifecycles. ### How do I set up an MCP server for Backblaze B2? You need Node.js 22 or higher, a Backblaze B2 account, and an MCP client. Generate a scoped application key in the Backblaze admin console, then add the server configuration to your client's settings file (such as claude_desktop_config.json or ~/.cursor/mcp.json) using npx to launch the @backblaze-labs/b2-mcp package with your key ID and application key environment variables. ### What is the difference between raw object storage MCP and indexed workspace storage? Raw object storage MCP provides direct bucket and object manipulation, but requires the agent to download entire files to inspect their contents. Indexed workspace storage, such as Fast.io with Intelligence enabled, pre-indexes documents upon upload, allowing agents to perform semantic search, retrieve cited passages, and query structured metadata without downloading whole files or saturating context windows. ### How do permissions differ between B2 application keys and workspace roles? Backblaze B2 permissions rely on application keys configured with specific API capabilities (such as readFiles or writeFiles) and optional bucket or prefix restrictions. Fast.io permissions are organized by member roles assigned at the organization, workspace, and share levels, allowing teams to collaborate and invite outside clients through branded shares without distributing infrastructure API keys. ### How does a two-tier storage setup reduce AI token consumption? A two-tier setup keeps heavy raw files, dataset backups, and media exports in low-cost Backblaze B2 storage, while keeping active documents and project context in an indexed Fast.io workspace. When an agent needs information, it queries the indexed workspace using semantic search, retrieving only relevant paragraphs rather than ingesting entire multi-megabyte files into its context window. ### Can AI agents generate branded client sharing links directly from storage? Raw Backblaze B2 storage only generates pre-signed URLs directly pointing to raw storage objects. Fast.io allows agents and humans to create branded Send, Receive, and Exchange shares with customizable logos, expiration dates, and access controls, enabling clients to view and download deliverables in a browser without technical tooling. ## Sources - [Backblaze B2 Pricing](https://www.backblaze.com/cloud-storage/pricing): Backblaze B2 charges $6.95 per terabyte per month for object storage. ## About Fast.io Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.