MCP Server

AIOZ Storage provides an MCP server that lets MCP-compatible AI assistants work with AIOZ Storage vector buckets, indexes, and vectors. Use it when you want an assistant to create vector resources, insert vectors, retrieve vectors, or run vector search through natural-language prompts.

This page focuses on connecting your MCP client to the AIOZ Storage MCP server and using the available vector tools.

Connect

Add the AIOZ Storage MCP server to an MCP-compatible client using HTTP SSE transport.

Use this SSE URL:

https://mcp-vector.aiozstorage.network/sse

After the client connects, it should show the AIOZ Storage vector tools.

Authentication

Every MCP tool call requires AIOZ Storage credentials in the tool arguments:

Example:

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

AIOZ Storage validates credentials before executing a tool call. Use credentials with only the permissions required for the task.

Important: To create, list, get, or delete vector buckets with the MCP server, first create a Vector Access Grant with All Buckets scope, then generate credentials from that grant. Bucket-level tools require credentials that can operate across vector buckets.

If your MCP client supports saved secrets, store these values in the client and let the client pass them to each tool call. Otherwise, include them when you ask the assistant to perform an operation.

Example prompts

Once connected, you can use natural-language prompts in your MCP client.

Create a vector bucket named your-vector-bucket.

Create a cosine vector index named your-vector-index in your-vector-bucket with dimension 1536.

Upsert these vectors into your-vector-index and attach title and document_type metadata to each vector.

Search your-vector-index for the 5 closest vectors to this query vector. Include metadata in the result.

List all vector buckets, then list indexes inside your-vector-bucket.

Tools

All tools require S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY.

Vector buckets

Required: credentials generated from a Vector Access Grant with All Buckets scope.

Vector indexes

Vectors

Limits

Arguments

create_vector_bucket

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
  "vectorBucketName": "your-vector-bucket",
  "tags": {
    "environment": "production"
  }
}

create_index

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
  "vectorBucketName": "your-vector-bucket",
  "indexName": "your-vector-index",
  "dimension": 1536,
  "distanceMetric": "cosine"
}

Supported distanceMetric values:

The MCP server also accepts l2 as an alias for euclidean and ip as an alias for dot.

The MCP server always creates float32 indexes.

put_vectors

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
  "vectorBucketName": "your-vector-bucket",
  "indexName": "your-vector-index",
  "vectors": [
    {
      "key": "vector-1",
      "data": {
        "float32": [0.12, 0.42, 0.87]
      },
      "metadata": {
        "title": "Your document title",
        "document_type": "technical-guide"
      }
    }
  ]
}

Each vector must include:

• key: a unique vector key in the index.
• data.float32: the vector values.
• metadata: optional JSON metadata.

The vector length must match the index dimension.

Use at most 500 vectors in one put_vectors call.

get_vectors

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
  "vectorBucketName": "your-vector-bucket",
  "indexName": "your-vector-index",
  "keys": ["vector-1", "vector-2"],
  "returnData": false,
  "returnMetadata": true
}

list_vectors

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
  "vectorBucketName": "your-vector-bucket",
  "indexName": "your-vector-index",
  "maxResults": 100,
  "nextToken": "",
  "returnData": false,
  "returnMetadata": true
}

Use nextToken from the previous response to continue pagination.

Set returnData or returnMetadata to true only when you need vector values or metadata in the response.

query_vectors

{
  "S3_ACCESS_KEY_ID": "your-access-key-id",
  "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
  "vectorBucketName": "your-vector-bucket",
  "indexName": "your-vector-index",
  "queryVector": [0.11, 0.44, 0.86],
  "topK": 5,
  "filter": {
    "document_type": "technical-guide"
  },
  "returnDistance": true,
  "returnMetadata": true
}

topK defaults to 10 when omitted or set to 0.

Set returnDistance: true explicitly when you need distance scores. Set returnMetadata: true explicitly when you need metadata in the result.

Metadata filters can match direct key/value pairs:

{
  "document_type": "technical-guide"
}

They can also use operators such as $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, and $not:

{
  "$and": [
    { "document_type": "technical-guide" },
    { "views": { "$gte": 1000 } }
  ]
}

Issues

Missing credentials

Add both credential fields to the tool arguments.

Invalid credentials

Check that the access key and secret key are correct and have permission to list vector buckets.

No query matches

Check that vectors were inserted into the expected bucket and index, the query vector has the same dimension as the index, and any metadata filter is not too restrictive.