AIOZ Storage MCP Server Tutorial: Connect AI Agents to S3 Buckets and Vector Search

Introduction

Most MCP servers run locally and read files from your disk. The AIOZ Storage MCP Server is different: it is a remote HTTP server, hosted by AIOZ Network, that gives an MCP-compatible agent 22 tools for working with S3-compatible object storage and a built-in vector database. This tutorial is for developers who want an AI agent to store files, generate upload links, and run semantic vector search without deploying any server code. You will register an AIOZ Storage account, create access grants, connect the SSE endpoint in your MCP client, and drive buckets, objects, and vector indexes through an agent.

Quick answer

Add https://mcp.aiozstorage.network/sse as an HTTP SSE server in your MCP client, then pass S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY as tool arguments. The 22 tools manage S3 buckets and objects plus vector buckets, indexes, and vectors.

Evidence

The numbers below are why this server is worth wiring into an agent instead of building your own S3 wrapper.

First, the tool surface is real and counted. The official MCP Server documentation enumerates 22 tools in five groups: 9 S3 bucket and object tools (list_s3_buckets, create_s3_bucket, delete_s3_bucket, list_s3_objects, get_s3_object, head_s3_object, put_s3_object, copy_s3_object, delete_s3_object), 4 vector bucket tools, 4 vector index tools, and 5 vector tools (put_vectors, get_vectors, list_vectors, query_vectors, delete_vectors). That is a complete CRUD surface for storage plus semantic search, with no glue code to write.

Second, pricing is public and edge-node economics show up in it. As of October 2026, the AIOZ Storage homepage lists $17 per TB per month for storage and $5 per TB for delivery bandwidth, billed pay-as-you-go and payable in the AIOZ token. The same page reports a network of 191,285 edge nodes, 96% less bandwidth cost, and 15 MB/s average download speed. Those figures explain the price point: content is served from a distributed edge network rather than a central region.

Third, the hard limits are documented, not discovered by accident. A single put_vectors call accepts at most 500 vectors, and get_s3_object returns at most 4 GiB through MCP, matching the S3 gateway object size limit. Knowing both numbers up front shapes batching and file-size decisions before you hit them.

AIOZ describes the server plainly, and the description is worth quoting: “AIOZ Storage provides an MCP server that lets MCP-compatible Super Intelligence assistants work with AIOZ Storage vector buckets, indexes, and vectors.” (AIOZ Storage Docs, MCP Server, accessed 17 October 2026.) If you are new to the protocol itself, our MCP server tutorial covers how servers, tools, and clients fit together.

Prerequisites

You need the following before you start:

• An AIOZ Storage account (registration is free; sign up on the AIOZ Storage homepage and click Get Started, which creates a root user; the docs require a minimum 8-character password with letters, numbers, and special characters recommended).
• At least one S3 Access Grant with All Buckets scope, because bucket management tools need it.
• A Vector Access Grant with All Buckets scope, for the vector bucket tools.
• An MCP-compatible client that supports HTTP SSE transport (Claude Desktop, Claude Code, and other SSE-capable clients qualify).
• curl on your machine, for verifying the endpoint and completing presigned uploads.

Step-by-step guide

Step 1: Create your account and access grants

Sign up at aiozstorage.network using the Get Started button, following the create an account guide. Registration creates a root user account.

Next, create credentials. In the AIOZ Storage console, follow the Manage Access Grants tutorial:

1. Choose the grant type S3 Credentials (CLI/API Key also exists).
2. Name the grant, for example agent-s3-full.
3. Select a bucket, or all buckets, and enter the bucket passphrase when prompted. AIOZ does not store or know your encryption passphrases, so keep yours safe.
4. Choose member permissions: All, Read, Write, List, or Delete. Use All Buckets scope with All permissions for the bucket-management tools.
5. Choose an access end date: 24 hours, 1 week, 1 month, 6 months, or 1 year. A short-lived grant is the right choice for an agent you do not fully trust yet.
6. Confirm, then copy the Access Key, Secret Key, and Endpoint (or download them as a file).

Repeat the process for a Vector Access Grant with All Buckets scope, which the vector tools require. Keep the two key pairs labeled separately, because S3 tools reject vector grant keys and vice versa.

Step 2: Verify the MCP endpoint is live

The MCP server speaks HTTP SSE at https://mcp.aiozstorage.network/sse. Confirm it from your terminal before touching your client config:

curl -sN -H "Accept: text/event-stream" \
  https://mcp.aiozstorage.network/sse | head -5

You should see an SSE handshake resembling:

event: endpoint
data: /message?sessionId=3f2a1b4c-9d8e-4f7a-b6c5-123456789abc

An event: endpoint line with a session ID means the server accepted the connection. A 403 or a hang here means a network problem on your side, not a server outage, because the endpoint is reachable from the public internet.

Step 3: Connect the server in your MCP client

The docs’ exact instruction is short: add the AIOZ Storage MCP server to an MCP-compatible client using HTTP SSE transport with the SSE URL above, and the client should then show the AIOZ Storage S3 and vector tools. There is no local package, no command/args stdio entry, and no environment-variable block. This catches people who expect the usual npx config snippet: for this server, the client config contains only the URL. If you have previously set up a local server with our MCP server tutorial, note that nothing from that workflow applies here.

After connecting, open your client’s tool list and look for the list_s3_buckets tool. If it is there, the handshake worked and you can skip straight to calling tools.

Step 4: List buckets with your first tool call

Call list_s3_buckets with your grant credentials passed as tool arguments, exactly as the docs demonstrate:

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key"
}

The call returns your bucket list. Two details from the docs matter for everything that follows. First, authentication is per call, so every one of the 22 tools expects those two fields. Second, an S3 grant scoped to one bucket can read objects in that bucket even when it cannot list every bucket, so a “permission denied” on listing does not necessarily mean your keys are wrong; it may mean the grant scope is narrow by design.

Step 5: Upload an object through a presigned URL

Object uploads use a two-step flow that surprises first-time users. put_s3_object does not upload anything by itself. It returns a presigned URL plus the method, headers, and expiresInSeconds you must use. Call it with the bucket name and object key, then complete the upload yourself with the returned values:

# The tool returns something like:
# {"url": "https://s3.aiozstorage.network/presigned/...",
#  "method": "PUT", "headers": {"x-amz-...": "..."}, "expiresInSeconds": 900}

curl -X PUT \
  -H "x-amz-date: 20261017T000000Z" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=..." \
  --data-binary @report.pdf \
  "https://s3.aiozstorage.network/presigned/..."

Include every header the tool returned, verbatim. The signature covers those headers, so dropping one invalidates the URL. Also note that uploading to an existing key replaces the object, and that opening the presigned URL in a browser tab sends a GET request and uploads nothing, a failure mode the docs call out explicitly.

The default S3 endpoint is https://s3.aiozstorage.network with signing region us-east-1, and SDK clients must use path-style addressing (forcePathStyle: true). A bare GET to that endpoint returns 403, which is normal S3 behavior for an unsigned request, not an error.

Step 6: Build a vector index and run semantic search

Vector work needs your Vector Access Grant credentials in the same argument fields. Create a vector bucket, then an index:

1. Call create_vector_bucket with a name like agent-memory.
2. Call create_index with indexName, vectorBucketName, dimension, and distanceMetric. Supported metrics are cosine, euclidean, and dot (with l2 and ip accepted as aliases). The server always creates float32 indexes. A docs example prompt reads: “Create a cosine vector index named your-vector-index in your-vector-bucket with dimension 1536.”
3. Call put_vectors with the index name, bucket name, and up to 500 vectors per call, each shaped {key, data: {float32: [...]}, metadata?}. The vector length must match the index dimension exactly, and each key must be unique inside the index.
4. Call query_vectors with your query embedding. When topK is omitted or 0, the server returns the top 10 matches. Set returnDistance: true for distance scores and returnMetadata: true to get the stored metadata back.

Metadata filters are expressive: direct key/value matches plus the operators $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, and $not. list_vectors paginates with nextToken, and list_indexes, get_index, and delete_index handle the index lifecycle. If you want a broader grounding in retrieval pipelines first, our n8n vector store tutorial walks through embeddings storage patterns that map directly onto these tools, and our LangChain RAG tutorial covers the retrieval side.

Step 7: Scope permissions with separate grants

Do not hand your All Buckets keys to every agent. Create additional grants with least privilege: a Read-only grant scoped to one bucket for a reporting agent, a Write grant for an ingestion agent, and a 24-hour expiry for anything experimental. The S3 gateway checks each grant’s permissions per operation, so a too-narrow grant fails safely on the operations it should not touch. This grant-per-agent pattern is the practical payoff of AIOZ’s access management model, and it is worth reading before you automate anything against production buckets.

Troubleshooting

Missing or invalid credentials on every tool call

The docs’ Issues section lists two credential failures. Missing credentials means you forgot one or both argument fields; the fix is to add both S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY to the tool arguments. Invalid credentials means the key, secret, grant family, or permission is wrong: check that the key pair matches the tool family (S3 tools need S3 grant keys, vector tools need vector grant keys) and that the grant has permission for the requested operation. Remember that a single-bucket grant legitimately cannot list all buckets, so narrow failures are a scope signal, not a key typo.

The upload “succeeded” but the file never appeared

You opened the presigned URL in a browser or called put_s3_object and stopped. The tool only mints the URL; bytes move only when you issue the PUT with every returned header included. Re-run the curl -X PUT command from Step 5, paste all headers exactly, and then confirm with head_s3_object.

get_s3_object fails on a PDF or image

The default text mode expects UTF-8 content, so binary files return an error. Retry with encoding: "base64" in the tool arguments. For files near the size limit, remember the documented ceiling: at most 4 GiB comes back through MCP.

query_vectors returns zero matches

Three causes cover almost every case, and the docs list them: the vectors were inserted into a different bucket or index than you are querying, the query vector’s dimension does not match the index dimension, or a metadata filter is too restrictive. Verify the index with get_index, drop the metadata filter to a plain topK query, and only then re-add filters one at a time.

delete_s3_bucket refuses to delete

A bucket must be empty before deletion. List its objects with list_s3_objects (note the continuationToken pagination when isTruncated is true), delete them with delete_s3_object, and retry.

The client connects but shows no tools

Confirm the client actually supports HTTP SSE transport; older stdio-only clients cannot talk to this server. Re-check the URL for typos (https://mcp.aiozstorage.network/sse, with /sse), and repeat the curl handshake from Step 2 to rule out a network block.

Conclusion

The AIOZ Storage MCP Server gives an agent a full S3 surface and a vector database over one SSE connection, with per-call credentials and grant-scoped permissions keeping the blast radius small. Start with a short-lived All Buckets grant, walk the presigned-upload flow once by hand, then lock each agent down to its own narrow grant. If you want to build a local MCP server of your own next, our build an MCP server in Python tutorial shows the other side of the protocol.

Frequently asked questions