# MCP tool reference

The Aerospike Voyager MCP server exposes the following tools to AI coding agents. Tools are organized by category. The **Browse and read only** and **All tools enabled** columns indicate which [access profile](https://aerospike.com/docs/database/tools/voyager/mcp/access-profiles) includes each tool.

::: 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

Every tool call returns 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.

Example (`get_record`):

```json
{

  "content": [{

    "type": "text",

    "text": "Record:\n  Key: user8  |  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",

    "digest": "00d8362e4cac83f58f538f81d8d8a3f8ec8fbacc",

    "node": "BB9C5F97288A0D6",

    "partitionId": 2048,

    "generation": 1,

    "expiration": 0,

    "bins": {

      "active": { "type": "bool", "value": false },

      "age":    { "type": "int",  "value": 43 },

      ...

    }

  }

}
```

::: note
When `get_record` is looked up by digest (`idType: "digest"`), the returned `key` field is an empty string. The user key is only populated on key-based lookups.
:::

## Connection management

| Tool | Description | Browse and read only | All tools enabled |
| --- | --- | --- | --- |
| `list_connections` | List all saved connections | Yes | Yes |
| `get_connection` | Get details of a specific connection | Yes | Yes |
| `create_connection` | Create a new cluster connection | No | Yes |
| `update_connection` | Update an existing connection | No | Yes |
| `delete_connection` | Delete a saved connection | No | Yes |
| `connect` | Connect to a saved cluster | Yes | Yes |
| `disconnect` | Disconnect from a cluster | Yes | Yes |
| `test_connection` | Test connectivity to a cluster | Yes | Yes |

## Cluster browsing

| Tool | Description | Browse and read only | All tools enabled |
| --- | --- | --- | --- |
| `list_namespaces` | List all [namespaces](https://aerospike.com/docs/database/learn/architecture/data-storage/data-model) in the connected cluster | Yes | Yes |
| `list_sets` | List all sets in a namespace | Yes | Yes |
| `get_nodes` | Get cluster node information | Yes | Yes |

## Record operations

| Tool | Description | Browse and read only | All tools enabled |
| --- | --- | --- | --- |
| `get_record` | Read a record by key or digest | Yes | Yes |
| `record_exists` | Check if a record exists | Yes | Yes |
| `query` | Scan or filter records; paginated (see below) | Yes | Yes |
| `create_record` | Create a new record | No | Yes |
| `update_record` | Update an existing record | No | Yes |
| `delete_record` | Delete a record | No | Yes |
| `delete_bin` | Delete a bin from a record | No | Yes |
| `truncate_set` | Remove all records from a set | No | Yes |

## Cluster info

| Tool | Description | Browse and read only | All tools enabled |
| --- | --- | --- | --- |
| `execute_info` | Run an info command on the cluster | No | Yes |
| `execute_info_on_node` | Run an info command on a specific node | No | Yes |

::: caution
The `browse and 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.

## Supported bin types

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

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

Supported `type` values: `int`, `float`, `string`, `bool`, `blob`, `list`, `map`, `geo`, `nil`.

::: note
The `nil` type is accepted on input but a bin with a `nil` value is silently omitted from the stored record. To explicitly clear a bin on 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 you may encounter:

-   **Internal errors**, including profile-blocked tool calls and unhealthy connections.
-   **Query timeouts or cancellations** — narrow the filter or add a secondary index.

## Next steps

-   [Access profiles](https://aerospike.com/docs/database/tools/voyager/mcp/access-profiles)
-   [Setup](https://aerospike.com/docs/database/tools/voyager/mcp/setup)
-   [MCP server overview](https://aerospike.com/docs/database/tools/voyager/mcp)