MCP Server Backblaze B2 — S3-compatible API tools, application keys, and /health/b2

SDK setup and B2 application key authentication

B2 distinguishes between the master key (full account access) and application keys (scoped access). Never use the master key in MCP server code — create a dedicated application key restricted to the bucket your server needs.

import { S3Client } from '@aws-sdk/client-s3';

// STEP 1: Find your bucket's region in the B2 dashboard.
// It's shown in Bucket Settings as something like "us-west-004" or "eu-central-003"
const B2_REGION = process.env.B2_REGION!;           // e.g., "us-west-004"
const BUCKET_NAME = process.env.B2_BUCKET_NAME!;

if (!B2_REGION || !BUCKET_NAME) {
  throw new Error('B2_REGION and B2_BUCKET_NAME are required');
}

// B2 S3-compatible endpoint format: https://s3.{region}.backblazeb2.com
const b2 = new S3Client({
  region: B2_REGION,  // Must match the bucket's actual region
  endpoint: `https://s3.${B2_REGION}.backblazeb2.com`,
  credentials: {
    // Application Key ID — starts with a long numeric string
    accessKeyId: process.env.B2_APPLICATION_KEY_ID!,
    // Application Key — the secret portion (shown once at creation)
    secretAccessKey: process.env.B2_APPLICATION_KEY!,
  },
  // B2 supports virtual-hosted-style URLs — forcePathStyle is NOT required
  maxAttempts: 3
});

export { b2, BUCKET_NAME, B2_REGION };

B2 application key permission types:

Create the application key in the B2 dashboard under App Keys → Add a New Application Key. Set "Restrict to Bucket" to the specific bucket name. Set "Type of Access" to "Read and Write". Copy the applicationKey value immediately — it's only shown once. The keyID (which maps to accessKeyId) is always retrievable from the dashboard.

Core B2 tool patterns

import {
  GetObjectCommand,
  PutObjectCommand,
  DeleteObjectCommand,
  ListObjectsV2Command,
  HeadObjectCommand
} from '@aws-sdk/client-s3';
import { z } from 'zod';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
import { b2, BUCKET_NAME } from './b2-client.js';

function validateKey(key: string): void {
  if (!key || key.includes('..') || key.startsWith('/') || /[\0\r\n]/.test(key)) {
    throw new McpError(ErrorCode.InvalidParams, `Invalid B2 key: ${key}`);
  }
}

async function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
  const chunks: Buffer[] = [];
  for await (const chunk of stream) {
    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
  }
  return Buffer.concat(chunks);
}

// ---- list_objects ----
server.tool(
  'list_objects',
  {
    prefix: z.string().default(''),
    max_keys: z.number().int().min(1).max(1000).default(100),
    continuation_token: z.string().optional()
  },
  async ({ prefix, max_keys, continuation_token }) => {
    const response = await b2.send(new ListObjectsV2Command({
      Bucket: BUCKET_NAME,
      Prefix: prefix,
      MaxKeys: max_keys,
      ContinuationToken: continuation_token
    }));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          objects: (response.Contents ?? []).map(obj => ({
            key: obj.Key,
            size: obj.Size,
            last_modified: obj.LastModified?.toISOString(),
            etag: obj.ETag
          })),
          is_truncated: response.IsTruncated,
          next_continuation_token: response.NextContinuationToken,
          count: response.KeyCount
        }, null, 2)
      }]
    };
  }
);

// ---- get_object ----
server.tool(
  'get_object',
  {
    key: z.string().min(1).max(1024),
    encoding: z.enum(['utf-8', 'base64']).default('utf-8')
  },
  async ({ key, encoding }) => {
    validateKey(key);
    try {
      const response = await b2.send(new GetObjectCommand({ Bucket: BUCKET_NAME, Key: key }));

      if (!response.Body) {
        throw new McpError(ErrorCode.InternalError, 'Empty response from B2');
      }

      const buffer = await streamToBuffer(response.Body as NodeJS.ReadableStream);
      const content = encoding === 'base64'
        ? buffer.toString('base64')
        : buffer.toString('utf-8');

      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            key,
            content,
            encoding,
            content_type: response.ContentType,
            content_length: response.ContentLength,
            last_modified: response.LastModified?.toISOString(),
            etag: response.ETag
          })
        }]
      };
    } catch (err: any) {
      if (err.name === 'NoSuchKey' || err.$metadata?.httpStatusCode === 404) {
        throw new McpError(ErrorCode.InvalidParams, `Object not found: ${key}`);
      }
      throw err;
    }
  }
);

// ---- put_object ----
server.tool(
  'put_object',
  {
    key: z.string().min(1).max(1024),
    content: z.string(),
    content_type: z.string().default('text/plain; charset=utf-8'),
    encoding: z.enum(['utf-8', 'base64']).default('utf-8')
  },
  async ({ key, content, content_type, encoding }) => {
    validateKey(key);
    const body = encoding === 'base64'
      ? Buffer.from(content, 'base64')
      : Buffer.from(content, 'utf-8');

    const response = await b2.send(new PutObjectCommand({
      Bucket: BUCKET_NAME,
      Key: key,
      Body: body,
      ContentType: content_type,
      ContentLength: body.length
    }));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ key, etag: response.ETag, bytes: body.length })
      }]
    };
  }
);

// ---- delete_object ----
server.tool(
  'delete_object',
  {
    key: z.string().min(1).max(1024),
    confirm: z.literal(true)
  },
  async ({ key }) => {
    validateKey(key);
    // B2 versioning note: if the bucket has versioning enabled,
    // DeleteObject creates a delete marker (hides the file but keeps history).
    // Use ListObjectVersions + DeleteObjects to permanently remove all versions.
    await b2.send(new DeleteObjectCommand({ Bucket: BUCKET_NAME, Key: key }));
    return {
      content: [{ type: 'text', text: JSON.stringify({ deleted: key }) }]
    };
  }
);

B2's per-transaction pricing model differs from S3's Class A/B distinction but maps similarly in practice: Class A operations (bucket creation, listing, uploads, deletes) are charged per 1,000 calls; Class B operations (downloads) are free for the first 1 GB/day and then charged per GB. Unlike S3 where egress is charged separately, B2 bundles download bandwidth into Class B pricing. For MCP servers that primarily serve reads, B2's bandwidth-included pricing for Class B is a significant cost difference from S3.

Download URLs: presigned S3 URLs vs B2 friendly URLs

B2 supports two download URL formats: S3-compatible presigned URLs (generated with the AWS SDK) and B2 native "friendly" URLs for public buckets. Use presigned URLs for private buckets; friendly URLs for public access.

import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

// ---- generate_download_url (presigned, works for private buckets) ----
server.tool(
  'generate_download_url',
  {
    key: z.string().min(1).max(1024),
    expires_in_seconds: z.number().int().min(60).max(604800).default(3600)
  },
  async ({ key, expires_in_seconds }) => {
    validateKey(key);

    // Verify object exists
    try {
      await b2.send(new HeadObjectCommand({ Bucket: BUCKET_NAME, Key: key }));
    } catch (err: any) {
      if (err.$metadata?.httpStatusCode === 404) {
        throw new McpError(ErrorCode.InvalidParams, `Object not found: ${key}`);
      }
      throw err;
    }

    const command = new GetObjectCommand({ Bucket: BUCKET_NAME, Key: key });
    const url = await getSignedUrl(b2, command, { expiresIn: expires_in_seconds });

    const expiresAt = new Date(Date.now() + expires_in_seconds * 1000);

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ url, key, expires_at: expiresAt.toISOString(), expires_in_seconds })
      }]
    };
  }
);

B2 friendly URL format for public buckets (no presigning needed):

// Public bucket: objects downloadable without presigning
// B2 friendly URL: https://{bucket}.s3.{region}.backblazeb2.com/{key}
// OR:              https://f{clusterNum}.backblazeb2.com/file/{bucket}/{key}

function getPublicDownloadUrl(key: string): string {
  // S3-compatible public URL (works if bucket is set to "Public")
  return `https://${BUCKET_NAME}.s3.${B2_REGION}.backblazeb2.com/${encodeURIComponent(key)}`;
}

// Tip: pair a Cloudflare proxy in front of your B2 public bucket:
// - Zero egress from B2 to Cloudflare (Bandwidth Alliance)
// - Use Cloudflare's CDN for caching and DDoS protection
// - Set your Cloudflare domain as a CNAME to the B2 bucket URL

Health endpoint: /health/b2

import express from 'express';
import { HeadBucketCommand } from '@aws-sdk/client-s3';
import { b2, BUCKET_NAME, B2_REGION } from './b2-client.js';

const app = express();

app.get('/health/b2', async (_req, res) => {
  const start = Date.now();
  try {
    await b2.send(new HeadBucketCommand({ Bucket: BUCKET_NAME }));
    const latencyMs = Date.now() - start;

    res.json({
      status: 'ok',
      bucket: BUCKET_NAME,
      region: B2_REGION,
      latency_ms: latencyMs
    });
  } catch (err: any) {
    const latencyMs = Date.now() - start;
    const statusCode = err.$metadata?.httpStatusCode;

    res.status(503).json({
      status: 'error',
      error: err.name ?? err.message,
      http_status: statusCode,
      region: B2_REGION,
      elapsed_ms: latencyMs,
      // Common B2 errors:
      // 403 — application key deleted, wrong key, or bucket-scope mismatch
      // 404 — bucket does not exist (check bucket name and region)
      // ECONNREFUSED / ENOTFOUND — wrong region in endpoint URL
    });
  }
});

app.listen(3001);

The most common B2 misconfiguration is using the wrong region in the endpoint URL. If your bucket is in us-west-004 but you set B2_REGION=us-east-005, requests go to a different B2 cluster. B2 returns a 301 redirect in some cases (which the SDK may follow incorrectly) or a 403. Always verify the region from the B2 dashboard's Bucket Settings tab — it's listed as the "Endpoint" field, e.g., s3.us-west-004.backblazeb2.com. Extract the region from between s3. and .backblazeb2.com.

Object versioning and the Bandwidth Alliance

B2 supports object versioning (keep all versions of each object), which interacts with delete operations differently from S3. When versioning is enabled and you call DeleteObject, B2 creates a delete marker — the object appears deleted but previous versions are retained. To permanently delete all versions, you need to list and delete each version individually using ListObjectVersions and DeleteObjects.

import { ListObjectVersionsCommand, DeleteObjectsCommand } from '@aws-sdk/client-s3';

// Permanently delete all versions of a key (when versioning is enabled)
async function hardDeleteAllVersions(key: string): Promise<void> {
  const response = await b2.send(new ListObjectVersionsCommand({
    Bucket: BUCKET_NAME,
    Prefix: key  // exact key match when prefix is the full key
  }));

  const objectsToDelete = [
    ...(response.Versions ?? []).map(v => ({ Key: v.Key!, VersionId: v.VersionId })),
    ...(response.DeleteMarkers ?? []).map(dm => ({ Key: dm.Key!, VersionId: dm.VersionId }))
  ].filter(o => o.Key === key);  // exact match only

  if (objectsToDelete.length === 0) return;

  await b2.send(new DeleteObjectsCommand({
    Bucket: BUCKET_NAME,
    Delete: { Objects: objectsToDelete, Quiet: true }
  }));
}

The Bandwidth Alliance note for B2: Backblaze and Cloudflare are Bandwidth Alliance partners, which means downloads from B2 to Cloudflare's network are free. If you put a Cloudflare CDN zone in front of your B2 public bucket, all downloads via Cloudflare are zero egress cost — even for high-volume workloads. Configure it by adding a CNAME record pointing your domain to the B2 bucket endpoint and enabling Cloudflare proxy. This is the primary reason teams choose B2 + Cloudflare over S3 + CloudFront — the egress cost difference at scale is substantial.

Frequently asked questions

Further reading

• MCP Server AWS S3 — GetObject, PutObject, presigned URLs, and health monitoring
• MCP Server Cloudflare R2 — S3-compatible storage tools and /health/r2 via HeadBucket
• MCP Server MinIO — S3-compatible self-hosted storage and /minio/health/live probe
• MCP Server GCP Cloud Storage — list, download, upload, signed URLs, and /health/gcs
• MCP Tools for Cloud Storage — SDK choice, auth models, and health probe patterns across GCS, Azure, R2, MinIO, and B2