How to Connect MinIO S3 Storage to AI Agents via MCP Server

Pointing an AI agent directly at an S3 bucket with unrestricted list and get permissions usually ends in context exhaustion before the agent finishes its second step. Object storage was engineered for high-throughput application backends, not LLM context windows. When an agent attempts to inspect an unfamiliar bucket, naive tool calls pull thousands of raw object keys, dump multi-megabyte payloads directly into prompt memory, and burn context on binary blobs. Without a structured protocol boundary, developers spend days writing custom glue scripts, managing brittle IAM credentials, and debugging truncated tool responses.

A MinIO MCP server is a middleware service that implements the Model Context Protocol over MinIO S3-compatible object storage, giving AI agents structured tools to search and retrieve bucket objects. Instead of granting an LLM arbitrary script execution or giving it raw AWS CLI privileges, the MCP server acts as an intentional broker. It exposes specific tools for bucket discovery, metadata inspection, and streaming retrieval that align with how language models process context.

Most generic S3 tutorials assume public AWS infrastructure with standard cloud-hosted IAM roles, public DNS, and centralized billing. Self-hosted object storage introduces a completely different set of operational constraints. Teams running MinIO on bare metal, Kubernetes clusters, or local development machines must handle private IP endpoints, internal hostnames, and custom TLS certificate authorities. When an AI client like Cursor or Claude Desktop attempts to connect, self-signed certificates or network bridge misconfigurations can silently fail without clear diagnostics.

Furthermore, raw object downloads present a massive context penalty. In typical cloud automation, downloading an entire large document or a log archive to extract a single configuration key is standard practice. For an agent operating under token constraints, dumping that file into the context window either truncates the conversation or drives inference costs higher. Connecting through a dedicated MinIO MCP server implementation introduces filtering boundaries, presigned URLs, and targeted metadata lookups that protect the agent's memory.

• How to Connect Wasabi Hot Cloud Storage to AI Agents via MCP ServerConnecting to a Wasabi MCP server gives AI agents structured tool access to cloud storage buckets without exposing...
• How to Connect AI Agents to Azure Blob Storage via MCPAn Azure Blob Storage MCP server exposes cloud containers and object storage to AI agents using standard Model Context...
• How to Connect Google Gemini to Box via MCPA Gemini Box MCP integration exposes Box enterprise folder hierarchies and file contents to Google Gemini agents...
• How to Use the Google Cloud Storage MCP Server with AI AgentsConnecting autonomous AI agents to Google Cloud Storage buckets allows language models to inspect and retrieve...
• OneDrive MCP Server: How to Connect Microsoft OneDrive to AI AgentsNo official Microsoft MCP server exists for OneDrive, leaving teams to bridge the gap between their enterprise files...
• How to Set Up a Remote MCP Server for AI AgentsA remote MCP server allows AI agents running locally to securely access tools and datasets hosted on a different...

More on this subject: MCP and Model Context Protocol (214 guides)

The Model Context Protocol establishes a client-host-server topology that separates the model environment from the underlying data store. In this architecture, the agent client (such as Cursor, Claude Desktop, or an autonomous orchestration loop) acts as the MCP host. The MinIO MCP server runs as a lightweight process or container alongside the client or inside the private network. The host communicates with the server via standard input/output (stdio) or HTTP with Server-Sent Events, while the MCP server issues authenticated S3 API calls to the MinIO cluster.

According to the MinIO engineering team, their MCP server provides more than 25 commonly used actions for object storage management, making exploring and using bucket data practical for AI assistants. These tools fall into two distinct operational groups: discovery tools and modification tools.

Discovery and Inspection Tools

Discovery tools allow the agent to explore storage hierarchy and inspect properties without pulling object payloads into context:

• list_buckets: Queries the MinIO cluster and returns an array of accessible bucket names, creation dates, and basic state.
• list_bucket_contents: Lists object keys, prefixes, sizes, and modification timestamps within a specified bucket, supporting prefix filtering to avoid unbounded list responses.
• get_object_metadata: Retrieves HTTP headers, content types, and user-defined metadata tags for a specific object key without reading its body.
• get_object_presigned_url: Generates a time-limited presigned URL that allows the agent or an external viewer to fetch an object directly over HTTP, keeping large binary payloads out of the prompt.

Modification and Management Tools

When granted appropriate privileges, the server exposes tools to write and reorganize bucket objects:

• upload_object: Writes text or binary data directly to a targeted bucket key.
• set_object_tags: Applies key-value metadata tags to an existing object, enabling downstream classification and indexing.
• text_to_object: Streamlines saving agent thoughts, summaries, or structured JSON responses directly into storage.
• move_object: Relocates or renames an object key within a bucket without re-uploading data from the client.

The server enforces a secure-by-default posture. By default, it operates in a strict read-only mode. Write, delete, and administrative operations are disabled unless an operator explicitly passes execution flags such as --allow-write, --allow-delete, and --allow-admin during startup.

This architectural separation ensures that even if an agent attempts an unexpected bulk deletion or unauthorized bucket creation, the containerized runtime blocks the call before it reaches the MinIO S3 API.

Running the MinIO MCP server inside a container isolates its runtime dependencies and provides clean credential injection. The official image is hosted on Quay.io at quay.io/minio/aistor/mcp-server-aistor:latest. You can run this image using Docker or Podman on the same workstation as your AI agent, or host it on an internal server accessible over your private network.

The container relies on four core environment variables to authenticate with your MinIO cluster:

• MINIO_ENDPOINT: The network address and port of your MinIO instance. For an internal cluster, this looks like minio.internal:9000 or an IP address like 192.168.1.150:9000. Do not include the http:// or https:// protocol prefix in this variable.
• MINIO_ACCESS_KEY: The access key or service account credential generated in the MinIO Console or via the mc command-line client.
• MINIO_SECRET_KEY: The corresponding secret key for the service account.
• MINIO_USE_SSL: Set to true if your MinIO cluster listens with TLS encryption, or false if you are testing over unencrypted HTTP.

To verify your connection from a terminal before attaching an AI client, launch the container interactively:

docker run -i --rm \
  -e MINIO_ENDPOINT="minio.internal:9000" \
  -e MINIO_ACCESS_KEY="minioadmin" \
  -e MINIO_SECRET_KEY="minioadminsecret" \
  -e MINIO_USE_SSL="false" \
  quay.io/minio/aistor/mcp-server-aistor:latest \
  --allow-write

When testing locally on macOS or Windows where MinIO runs directly on the host machine outside Docker, the container cannot reach localhost:9000. Instead, configure MINIO_ENDPOINT as host.docker.internal:9000. This special DNS name resolves to the host's internal network interface, allowing the containerized MCP process to route requests back to your local MinIO daemon.

If your self-hosted MinIO deployment uses TLS backed by an internal corporate certificate authority or a self-signed certificate, Docker containers will reject the TLS handshake by default. To resolve this, mount your root CA certificate into the container's trusted certificate store:

docker run -i --rm \
  -v /etc/ssl/certs/internal-ca.crt:/etc/ssl/certs/internal-ca.crt:ro \
  -e MINIO_ENDPOINT="minio.internal:9000" \
  -e MINIO_ACCESS_KEY="minioadmin" \
  -e MINIO_SECRET_KEY="minioadminsecret" \
  -e MINIO_USE_SSL="true" \
  quay.io/minio/aistor/mcp-server-aistor:latest \
  --allow-write

Mounting the certificate allows the Go-based MCP server binary inside the container to validate your internal domain without disabling TLS verification or compromising transport security.

Once the containerized server is verified, you can register it with your primary AI development tools. Both Cursor and Claude Desktop support the Model Context Protocol over standard input and output (stdio), launching the Docker command as a child process when the client starts.

Configuring Cursor

Cursor manages MCP server configurations either globally or on a per-project basis. To configure MinIO access for a specific repository, create or edit the .cursor/mcp.json file in the root of your workspace:

{
  "mcpServers": {
    "minio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MINIO_ENDPOINT=minio.internal:9000",
        "-e", "MINIO_ACCESS_KEY=your-access-key",
        "-e", "MINIO_SECRET_KEY=your-secret-key",
        "-e", "MINIO_USE_SSL=false",
        "quay.io/minio/aistor/mcp-server-aistor:latest",
        "--allow-write"
      ]
    }
  }
}

After saving .cursor/mcp.json, open Cursor's Settings, navigate to the MCP section, and confirm that the minio server appears with a green status indicator. If the indicator stays orange or displays an error, open the MCP logs in Cursor to verify that Docker is running and that your endpoint is reachable.

Configuring Claude Desktop

Claude Desktop uses a central configuration file stored in your user profile:

• On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the MinIO server configuration to the mcpServers object in that file:

{
  "mcpServers": {
    "minio-storage": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MINIO_ENDPOINT=minio.internal:9000",
        "-e", "MINIO_ACCESS_KEY=your-access-key",
        "-e", "MINIO_SECRET_KEY=your-secret-key",
        "-e", "MINIO_USE_SSL=false",
        "quay.io/minio/aistor/mcp-server-aistor:latest",
        "--allow-write"
      ]
    }
  }
}

Restart Claude Desktop completely to spawn the container process. Click the hammer icon in the prompt input field to verify that tools such as list_buckets and get_object_metadata are active.

Structuring Agent Prompts to Avoid Context Exhaustion

To keep agent interactions efficient and prevent context flooding, teach your agents how to query storage responsibly. When instructing an agent in Cursor or Claude, use specific retrieval rules:

When accessing storage:
1. First call `list_buckets` to confirm available storage targets.
2. When searching for files, call `list_bucket_contents` with an explicit prefix (e.g. `reports/2026/`).
3. Always inspect object size and MIME type with `get_object_metadata` before fetching content.
4. For large files, generate a presigned URL with `get_object_presigned_url` instead of reading the body into context.

Following this pattern keeps the agent focused on metadata indexing and excerpt extraction, preventing multi-megabyte log files or PDF dumps from overwhelming prompt memory.

Connect Your AI Agents to Intelligent Storage

Connect your coding assistants and autonomous agents to shared workspaces with built-in indexing, semantic search, and an official remote MCP server. Start your 14-day free trial.

Start 14-Day Trial

Connecting an AI agent to MinIO S3 storage solves immediate tool access, but raw object storage quickly reveals operational ceilings when scaled across teams. MinIO excels at high-throughput block and object storage, but buckets are passive data repositories. A standard bucket does not index document contents for meaning-based search, extract structured data from unstructured contracts or receipts, or coordinate multiple agents working simultaneously.

When multiple autonomous agents read and write to the same MinIO bucket, they operate without awareness of each other. If Agent A generates a draft report and Agent B begins reviewing it, neither model can determine whether the object is currently being edited. S3 has no native advisory lease or lock mechanism. If two agents write to the same key simultaneously, the last write silently overwrites the first, leading to subtle race conditions and corrupted intermediate states.

This is where purpose-built workspace storage bridges the gap between raw object stores and collaborative AI teams. Fastio provides org-owned workspaces designed for AI agents that treat autonomous assistants and human teammates as first-class collaborators within the same files and folders.

Instead of maintaining local container daemons and wrestling with private network routing, teams connect their agents to Fastio using an official remote MCP server. The server exposes Streamable HTTP at https://mcp.fast.io/mcp and handles authentication through scoped bearer tokens, as documented in the Fastio agent storage guide. The agent needs no local Docker runtime, no custom CA bundle mounts, and no open inbound ports.

Fastio organizes workspace access through a consolidated MCP toolset. The server exposes a single consolidated storage tool driven by an explicit action parameter. Agents call actions such as search, list, details, lock-acquire, lock-status, and lock-release.

To coordinate concurrent writers, Fastio provides advisory per-file locks directly within the workspace storage layer:

• An agent acquires an advisory lease on a file before writing by calling the storage tool with the lock-acquire action.
• The lock records the locker identity, including the specific locker.agent_name, visible to any team member or peer agent querying lock-status.
• If a second agent attempts to acquire the file, the server returns an HTTP conflict status, signaling that another worker is currently updating the document.
• Locks are advisory leases that expire unless renewed by heartbeat, and can be taken over by anyone with write permissions.
• Full per-file version history preserves every version automatically, ensuring that unlocked concurrent writes never result in unrecoverable data loss.

Beyond file coordination, Fastio transforms passive document storage into an active knowledge layer. When Intelligence Mode is enabled on a workspace, incoming documents, spreadsheets, presentations, and collaborative notes are automatically indexed for Hybrid Search. This combines exact full-text matching with semantic retrieval and search-by-metadata-value, returning citation-backed excerpts directly to the model.

For teams handling high volumes of invoices, contracts, or unstructured receipts, Fastio's Metadata Views feature turns files into queryable databases. Users describe columns in natural language, and AI designs a typed schema (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time) that automatically extracts structured fields from PDFs, spreadsheets, and scanned documents without manual OCR templates. Agents can inspect schemas and query extracted rows programmatically via MCP, replacing brittle parsing scripts with clean structured queries.

In head-to-head testing across cloud storage providers, Fastio was measured the fastest and the lowest cost of the providers tested (full methodology and benchmark results are published at https://fast.io/benchmarks/).

Every organization starts with a 14-day free trial, which requires a credit card. Subscriptions are structured across Starter, Business, and Enterprise tiers, giving teams enterprise-grade indexing, advisory coordination, and durable file versioning while keeping existing cloud storage and private MinIO deployments connected. Learn more about plan options on the Fastio pricing page.