ObjectStore MCP

Multi-Backend Object Storage | MCP Server

The object-storage connector for the agent-connector-sdk fleet: one MCP tool surface over S3 and S3-compatible stores (MinIO, Cloudflare R2), Google Cloud Storage, Azure Blob Storage, and a zero-infra local-filesystem backend.

Version: 2.3.0

Documentation — Installation, deployment, and usage across the API, CLI, and MCP interfaces are maintained in docs/.

Table of Contents

• Overview
• What it provides
• Backend × capability matrix
• Installation
• Configuration (environment)
• Usage
• MCP config
• Docker deployment
• Development
• License

Overview

objectstore-mcp wraps heterogeneous object stores behind one typed, (objectstore-agent). Safety caps, explicit buckets, and dry-run-by-default batch deletes are enforced uniformly in the tool layer, in either case of backend.

What it provides

• A multi-backend store abstraction (objectstore_mcp.api, CONCEPT:OB-OS.governance.every-provider-implements-same) — every provider implements the same ObjectStoreBackend protocol, validated by a single conformance test suite that runs for real against the filesystem backend.

• Three consolidated, action-routed MCP tools (objectstore-mcp console script):

  Tool	Actions	Description
  objects	list (prefix/delimiter pagination), head, get (text/base64, size-capped), put (text/base64, size-capped), copy, move, delete, delete_batch (capped, dry-run by default), presign, metadata_get, metadata_set	Single-object lifecycle and listing on any store
  buckets	list, create, delete (empty-only, opt-in), exists, info, stores	Bucket/container admin and store registry introspection
  transfer	upload, download, upload_dir, download_prefix (all size/batch-capped)	Local-filesystem ⇄ object-store transfer, single or by prefix

  The whole tool set toggles with OBJECTSTORETOOL.

• Named multi-store routing — OBJECTSTORE_STORES JSON maps store names to {backend, bucket?, endpoint?, profile?, ...}; every tool takes an optional store argument. A zero-infra local filesystem store always exists, so the server works with no cloud credentials at all.

• A safety governor — size caps on get/put/transfer, list/batch key caps, deletes that demand an explicit bucket+key (no wildcards), batch deletes that are prefix-scoped, capped, and dry-run by default, and bucket deletes that are empty-only and disabled unless explicitly enabled.

Available MCP Tools

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

3 action-routed tool(s) (default) · 15 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (condensed default · verbose 1:1 · both). Auto-generated — do not edit.

Backend × capability matrix

Installation

Pick the extra that matches what the operator want to run (provider extras are additive):

pip install objectstore-mcp            # core: local filesystem backend only
pip install objectstore-mcp[mcp]       # connector-focused MCP server (FastMCP/FastAPI)
pip install objectstore-mcp[mcp,s3]    # + boto3 (S3, MinIO, R2)
pip install objectstore-mcp[mcp,gcs]   # + google-cloud-storage
pip install objectstore-mcp[mcp,azure] # + azure-storage-blob
pip install objectstore-mcp[all]       # everything (MCP + agent + all providers)

Container images (:mcp)

One multi-stage docker/Dockerfile builds the MCP-only image (--target mcp):

docker build --target mcp   -t example/objectstore-mcp:mcp    docker/   # connector-focused MCP server

Or pull a prebuilt image:

docker pull example/objectstore-mcp:mcp      # connector-focused MCP server
docker pull example/objectstore-mcp@sha256:<digest>   # agent runtime (default)

The :mcp tag is the MCP-serving image (built from docker/Dockerfile --target mcp, installing objectstore-mcp[mcp]). The default which also bundles the Pydantic AI agent and the epistemic-graph engine — use it when the operator run objectstore-agent (the agent), not just the MCP server.

Knowledge-graph database (epistemic-graph)

Agent Connector SDK core dependency (epistemic-graph[full]). The [mcp] extra keeps deployments can use the bundled engine. For production or shared state, run epistemic-graph as a dedicated database service and configure the runtime to use it. Deployment recipes (single-node + Raft HA), connection configuration, and architecture diagrams are documented in the epistemic-graph deployment guide.

Configuration (environment)

Provider credentials resolve through each SDK's own chain — boto3's resolution order for S3 (env keys, ~/.aws profiles via the store's profile, SSO, instance metadata), GOOGLE_APPLICATION_CREDENTIALS / Application Default Credentials for GCS, and AZURE_STORAGE_CONNECTION_STRING for Azure Blob.

Example store registry

{
  "media":   {"backend": "s3", "bucket": "media-prod", "profile": "prod", "region": "us-east-1"},
  "minio":   {"backend": "s3", "endpoint": "http://minio.example.invalid:9000"},
  "r2":      {"backend": "s3", "endpoint": "https://<account>.r2.cloudflarestorage.com"},
  "reports": {"backend": "gcs", "bucket": "acme-reports"},
  "archive": {"backend": "azure", "bucket": "archive"},
  "scratch": {"backend": "filesystem", "root": "~/scratch-store"}
}

Usage

objectstore-mcp                                   # stdio
objectstore-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Example tool calls (any MCP client):

// Write then read a text object on the zero-infra local store
{"tool": "buckets",  "arguments": {"action": "create", "params_json": "{\"bucket\": \"notes\"}"}}
{"tool": "objects",  "arguments": {"action": "put",    "params_json": "{\"bucket\": \"notes\", \"key\": \"todo.md\", \"text\": \"- ship it\"}"}}
{"tool": "objects",  "arguments": {"action": "get",    "params_json": "{\"bucket\": \"notes\", \"key\": \"todo.md\"}"}}

// Preview then execute a prefix-scoped batch delete on a named S3 store
{"tool": "objects", "arguments": {"store": "media", "action": "delete_batch", "params_json": "{\"bucket\": \"media-prod\", \"prefix\": \"tmp/\"}"}}
{"tool": "objects", "arguments": {"store": "media", "action": "delete_batch", "params_json": "{\"bucket\": \"media-prod\", \"prefix\": \"tmp/\", \"dry_run\": false}"}}

MCP config

Install the connector-focused [mcp] extra. Examples use objectstore-mcp[mcp] to add FastMCP / FastAPI through agent-connector-sdk; the required Agent Connector SDK core enables model orchestration. Combine it with the storage-provider extras needed by the deployment.

{
  "mcpServers": {
    "objectstore-mcp": {
      "command": "uvx",
      "args": ["--from", "objectstore-mcp[mcp]", "objectstore-mcp"],
      "env": {
        "OBJECTSTORE_STORES": "{\"minio\": {\"backend\": \"s3\", \"endpoint\": \"http://minio.example.invalid:9000\"}}",
        "OBJECTSTORE_DEFAULT_STORE": "local"
      }
    }
  }
}

objectstore-agent --mcp-url http://localhost:8000/mcp --host 0.0.0.0 --port 9001

Additional Deployment Options

objectstore-mcp can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

• Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
• Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

Docker deployment

docker compose -f docker/mcp.compose.yml up -d      # MCP server only
curl -s http://localhost:8000/health                 # {"status":"OK"}

Both services read configuration from ../.env (copy .env.example); see docs/deployment.md.

Development

pip install -e .[test]
pytest                       # full suite (cloud SDKs not required)
pip install -e .[test-s3]    # adds boto3+moto integration tests
pre-commit run --all-files

See docs/ for architecture, concepts, and deployment details.

License

MIT — see LICENSE.

Environment Variables

Package environment variables

Inherited agent-connector-sdk variables (apply to every connector)

27 package + 15 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.