MCP tool reference

The Aerospike Voyager MCP server exposes 23 tools to AI coding agents, organized by category. The Read Only and Full Access columns indicate which access profile allows each tool.

Parameters in italics are optional. Every parameter is passed as a JSON field on the tool call.

Prerequisites

• The MCP server started. See Setup.
• You have at least one saved cluster connection.

Tip

You can view the live tool catalog in Voyager by navigating to the MCP Server page. Every tool’s description and JSON schema for arguments is available there.

Response shape

Tools that return data include two complementary views in the MCP response:

• content[0].text: a formatted, human-readable rendering. Most MCP clients (Claude Desktop, Cursor) display this to the user.
• structuredContent: the same data as a JSON object. AI agents that support structured content can consume this directly without parsing text.

structuredContent is present on get_record, create_record, update_record, query, the five browse tools (get_cluster_summary, list_namespaces, get_namespace_stats, list_sets, get_nodes), and the two info tools (execute_info, execute_info_on_node). Every connection tool, plus record_exists, delete_record, delete_bin, and truncate_set, return text only.

Example (get_record):

{
  "content": [{
    "type": "text",
    "text": "Record:\n  Key: user8 (string)  |  Digest: 00d8...  |  Partition: 2048  |  Node: BB9C5F97288A0D6\n  Generation: 1  |  TTL: namespace default\n\n  Bins (7):\n    active   [bool   ]  false\n    age      [int    ]  43\n    ..."
  }],
  "structuredContent": {
    "key": "user8",
    "keyType": "string",
    "digest": "00d8362e4cac83f58f538f81d8d8a3f8ec8fbacc",
    "node": "BB9C5F97288A0D6",
    "partitionId": 2048,
    "generation": 1,
    "expiration": 0,
    "bins": {
      "active": { "type": "bool", "value": false },
      "age":    { "type": "int",  "value": 43 },
      ...
    }
  }
}

Note

The returned key field carries the user key the record itself stores, independent of how you addressed it. A record written with the send-key option returns its user key on a digest lookup as well as a key lookup. A record written without send-key returns an empty key on every lookup, including a lookup by that same key, because the cluster holds no user key to report.

keyType names the Aerospike type of the stored key: string, int, or blob. It is omitted when the record stores no user key. Use it to tell an integer-keyed record from a string-keyed one, which key alone cannot do because both render as digits.

Connection management

Tool	Description	Parameters	Read Only	Full Access
list_connections	List all saved connections	none	Yes	Yes
get_connection	Get details of a specific connection	connectionId	Yes	Yes
create_connection	Create a new cluster connection	name, hosts, port, username, password, authMode, tlsName, caCert, clientCert, clientKey, insecureTLS, timeout, loginTimeout, useServicesAlternate	No	Yes
update_connection	Update an existing connection	connectionId, plus any field accepted by create_connection. Omitted fields keep their current value	No	Yes
delete_connection	Delete a saved connection	connectionId	No	Yes
connect	Connect to a saved cluster	connectionId	Yes	Yes
disconnect	Disconnect from a cluster	connectionId	Yes	Yes
test_connection	Test connectivity to a cluster without saving it	hosts, port, username, password, authMode, tlsName, caCert, clientCert, clientKey, timeout, loginTimeout	Yes	Yes

hosts is a comma-separated seed list in host:port form, for example 192.168.1.1:3000,10.0.0.2:3000. Certificates and keys are supplied as standard base64-encoded PEM, encoding the whole file including the BEGIN and END markers.

authMode accepts internal (default), external, and pki on every tool that takes it. external requires a TLS configuration (caCert, clientCert, or tlsName) and both username and password. pki requires clientCert and clientKey and takes no username or password.

The connection must be disconnected before update_connection succeeds. To clear a string field, pass an empty string. Omitting a field leaves the stored value unchanged. The update is a read-modify-write that is not atomic, so concurrent updates to the same connection can overwrite each other.

Cluster browsing

Tool	Description	Parameters	Read Only	Full Access
get_cluster_summary	Get cluster name, server versions, cluster size, namespace names, and per-node metadata. Lightweight, with no record counts or storage usage	connectionId	No	Yes
list_namespaces	List all namespaces in the connected cluster with aggregated stats: master object count, memory and device storage, replication factor, per-node breakdown	connectionId	Yes	Yes
get_namespace_stats	Get the same aggregated stats for a single namespace	connectionId, namespace	No	Yes
list_sets	List all sets in a namespace with their object counts, storage usage, and tombstones	connectionId, namespace	Yes	Yes
get_nodes	Get cluster node names, host addresses, and build versions	connectionId	Yes	Yes

Note

get_cluster_summary and get_namespace_stats read cluster metadata and change nothing, but the Read Only allowlist does not include them. Agents restricted to Read Only can use list_namespaces, which returns namespace names and stats in one call.

Record operations

Tool	Description	Parameters	Read Only	Full Access
get_record	Read a record by key or digest	connectionId, namespace, set, id, idType, policy	Yes	Yes
record_exists	Check if a record exists	connectionId, namespace, set, id, idType	Yes	Yes
query	Scan or filter records, paginated (see Query pagination)	connectionId, namespace, set, expression, values, indexHintBin, pageToken, policy	Yes	Yes
create_record	Create a new record	connectionId, namespace, set, key, keyType, bins, policy	No	Yes
update_record	Update the named bins of an existing record	connectionId, namespace, set, digest, bins, policy	No	Yes
delete_record	Delete a record	connectionId, namespace, set, id, idType, policy	No	Yes
delete_bin	Delete a bin from a record	connectionId, namespace, set, digest, binName, policy	No	Yes
truncate_set	Remove all records from a set	connectionId, namespace, set	No	Yes

Addressing a record

get_record, record_exists, and delete_record take an idType that says how to read id:

idType	id holds	Notes
key	A string user key	The default identity for a record written with a bare key.
intkey	An integer user key	A decimal integer within the signed 64-bit range. Hexadecimal, floating-point, and exponent forms are rejected with a validation error. A decimal value outside the signed 64-bit range returns no record rather than a validation error.
digest	A 40-character hex digest	Addresses the record whichever key type wrote it.

Both idType and keyType accept key (string) and intkey (integer). String and integer keys work on reads, exists checks, deletes, and creates. create_record has no digest option because a digest is a one-way hash and would create a record whose user key could never be recovered.

A string user key and an integer user key with the same digits are different records, because Aerospike hashes the user key’s type into the digest. An agent that knows only the digits can try both. update_record and delete_bin identify the record by digest, which you get from a get_record or query response.

The policy object

The optional policy object carries the Aerospike client policy for the call. Read policies accept fields such as totalTimeout, socketTimeout, maxRetries, replicaPolicy, readModeAP, and readModeSC. Write policies accept recordExistsAction, generationPolicy, generation, commitLevel, expiration, durableDelete, and sendKey.

Every enumerated policy value is lower camelCase. Upper snake case values such as EXPECT_GEN_EQUAL are rejected. The default column is the value Voyager applies when the field is omitted, taken from its policy preferences:

Field	Accepted values	Default
recordExistsAction	update, updateOnly, replace, replaceOnly, createOnly	update
generationPolicy	none, expectGenEqual, expectGenGT	none
commitLevel	all, master	all
replicaPolicy	master, masterProles, sequence, preferRack, random	sequence
readModeAP	one, all	one
readModeSC	session, linearize, allowReplica, allowUnavailable	session

Use generationPolicy: "expectGenEqual" with generation for optimistic locking, and durableDelete: true for durable deletes. For example:

{ "generationPolicy": "expectGenEqual", "generation": 4 }

Caution

Some tool schemas advertise these values in upper snake case. The server rejects them. A call using EXPECT_GEN_EQUAL fails with unknown generationPolicy "EXPECT_GEN_EQUAL".

The query policy.expectedDuration field has the same mismatch: the schema advertises LONG|SHORT|LONG_RELAX_AP but the server only accepts long, short, and longRelaxAP.

Cluster info

Tool	Description	Parameters	Read Only	Full Access
execute_info	Run one or more info commands on the cluster	connectionId, commands	No	Yes
execute_info_on_node	Run one or more info commands on a specific node	connectionId, node, commands	No	Yes

commands is an array of info command strings, for example ["namespaces", "build"]. node is a node name from get_nodes.

Caution

The Read Only profile excludes execute_info and execute_info_on_node because the Aerospike info protocol supports mutation subcommands (such as set-config:, truncate:, and recluster:). Excluding these tools entirely is the only reliable way to prevent unintended mutations through the info channel.

Query pagination

The query tool paginates results automatically. Defaults and limits:

• Default page size: 20 records
• Maximum page size: 256 records (set via policy.maxRecords)
• Pagination cursor: the server returns a nextPageToken in structuredContent when more records are available. Pass it as the pageToken argument on the next call to fetch the next page.
• Text signal: the human-readable summary includes “(more pages available)” when additional pages exist.

The nextPageToken is a large hex-encoded binary cursor (typically 50+ KB). Store it verbatim; do not truncate or modify.

Filter with the optional expression argument, which takes an Aerospike Expression Language expression such as $.age > 30 or $.city == "NYC". Omit it for a plain query. Use values to supply placeholder values for parameterized expressions. Use indexHintBin to name the bin for secondary-index selection, or omit it to let the server discover available indexes automatically.

Supported bin types

Write operations (create_record, update_record) accept bins as typed BinInput objects:

{ "name": "age", "type": "int", "value": 30 }

Supported type values for writes: int, float, string, bool, blob, list, map, geo.

Read responses can also return hyperloglog bins, which are read-only and cannot be written through Voyager.

Note

To write a bin with a null value, pass "value": null with any supported type. To remove a bin from an existing record, use delete_bin.

Errors

Errors are returned with isError: true in the MCP result. The text content is a human-readable message that includes a short summary, additional detail where relevant, and remediation guidance.

Common error categories:

• Profile-blocked: the active access profile does not allow the tool. The response body is blocked by active profile.
• Validation errors (for example [VOY-C018] Auth mode unsupported): parameters failed server-side checks. The error text opens with the code and title, followed by the message and, where present, server code, remediation, and a docs link.
• Internal errors, such as an unhealthy connection.
• Query timeouts or cancellations. Narrow the filter or add a secondary index.

Next steps

• Access profiles
• Setup
• MCP server overview