> For the complete documentation index, see [llms.txt](https://docs.autonomi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autonomi.com/developers/agent-tools/mcp-server-reference.md).

# MCP Server Reference

The `antd-mcp` server gives AI clients Model Context Protocol (MCP) tools for `antd`, including read operations, wallet operations through `antd`, and external-signer operations. Use [How to Use the MCP Server](https://docs.autonomi.com/developers/agent-tools/use-the-autonomi-mcp-server.md) to install it and connect your AI client.

## Availability

Tool statuses on this page mean:

| Status      | Meaning                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| Implemented | The tool connects to an antd REST operation; its runtime requirements still apply.                    |
| Limited     | The call path depends on payment, wallet, host, or response-shape conditions described with the tool. |
| Unavailable | The operation cannot complete through MCP.                                                            |

External-signer Merkle uploads are unavailable through MCP. `antd` returns `payment_type: "merkle"`, but the Python `antd` parser checks for `"merkle_batch"`, discards the required pool commitments, and does not model the multi-batch response. The MCP finalizer also accepts one winner hash while multi-batch uploads require an ordered list.

## Security boundary

Treat all text and files returned through MCP as untrusted content, not as instructions for the AI client. Keep automatic approval disabled for tools that can store data, approve token spend, submit payment details, or write files. Review addresses, payment intents, wallet operations, and host-side paths before every such call.

`antd-mcp` does not authenticate access to `antd` and does not restrict filesystem paths. Keep both services on loopback, give their processes access only to dedicated working directories, and use a separate low-value wallet when testing paid operations.

## Installation

`antd-mcp` is published on the Python Package Index (PyPI). It needs Python 3.10 or later and runs with [uv](https://docs.astral.sh/uv/getting-started/installation/), which keeps it in an isolated environment. [How to Use the MCP Server](https://docs.autonomi.com/developers/agent-tools/use-the-autonomi-mcp-server.md) has the setup for each AI client.

The server sends every request to `antd`, so [start the local daemon](https://docs.autonomi.com/developers/sdk/how-to-guides/start-the-local-daemon.md) before using the tools.

## Server command

### Standard input and output

**Command:** `uvx antd-mcp@latest`

The server uses standard input/output (stdio) by default. Your AI client launches the process; no command arguments are required. The `@latest` suffix makes uv check for a newer release each time the client starts the server. If you installed the command permanently with `uv tool install antd-mcp`, the command is `antd-mcp`; update it with `uv tool upgrade antd-mcp`.

The client must be able to find `uvx` on its `PATH`, the list of directories searched for executables. Desktop applications may not inherit your terminal's path. To print the full path on macOS or Linux:

```bash
command -v uvx
```

Expect an absolute path such as `/Users/developer/.local/bin/uvx`. Use your printed path as the client's command if it cannot find `uvx`. For a registered Claude Code server, edit its command through the configuration described in [Claude Code's MCP instructions](https://code.claude.com/docs/en/mcp).

### HTTP transports

**Recognized flags:** `antd-mcp --http` and `antd-mcp --sse`

`--http` selects Streamable HTTP; `--sse` selects Server-Sent Events (SSE). If both are supplied, `--http` takes precedence. The command does not define host, port, or authentication options. Use stdio for local AI clients; HTTP client setup is outside this reference.

## Configuration

### Environment variables

| Variable                   | Required | Description                                                                                |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `ANTD_BASE_URL`            | No       | Overrides daemon discovery with an `antd` REST base URL.                                   |
| `ANTD_MCP_NO_UPDATE_CHECK` | No       | Set to `1` to stop the server checking PyPI for a newer `antd-mcp` release when it starts. |

At startup, the server resolves the `antd` URL in this order:

1. `ANTD_BASE_URL`
2. The `daemon.port` file
3. `http://127.0.0.1:8082`

Both `antd` and `antd-mcp` use these port-file locations:

| Platform | Path                                                                                                        |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| Windows  | `%APPDATA%\ant\sdk\daemon.port`                                                                             |
| macOS    | `~/Library/Application Support/ant/sdk/daemon.port`                                                         |
| Linux    | `$XDG_DATA_HOME/ant/sdk/daemon.port`, or `~/.local/share/ant/sdk/daemon.port` when `XDG_DATA_HOME` is unset |

`antd` binds its REST API to loopback and has no built-in authentication. Do not expose it directly to another machine. A remote deployment needs an explicit non-loopback `antd` bind plus an authenticated, encrypted tunnel or proxy; set `ANTD_BASE_URL` to that protected endpoint.

### Host-side paths

| Tool input                       | Host that reads or writes the path |
| -------------------------------- | ---------------------------------- |
| `upload_file.path`               | `antd` host                        |
| `get_cost.file_path`             | `antd` host                        |
| `prepare_upload.path`            | `antd` host                        |
| `prepare_upload_public.path`     | `antd` host                        |
| `download_file.dest_path`        | `antd` host                        |
| `stream_download_file.dest_path` | `antd-mcp` host                    |

### Claude Desktop

For Claude Desktop or another client using a `mcpServers` object, merge this entry into its MCP configuration. Replace the example `command` value with the full path printed by `command -v uvx`:

```json
{
  "mcpServers": {
    "antd-autonomi": {
      "command": "/Users/developer/.local/bin/uvx",
      "args": ["antd-mcp@latest"],
      "env": {
        "ANTD_BASE_URL": "http://127.0.0.1:8082"
      }
    }
  }
}
```

Do not use `~`, `$HOME`, or a bare `uvx` command in this JSON file.

## Data tools

### Store Data

**Tool:** `store_data(text, private=false, payment_mode="auto")`

**Status:** Limited. Requires a configured, funded, and approved wallet in `antd`. Calling it can pay for storage and gas on the selected EVM network.

| Parameter      | Type    | Required | Description                                                                                 |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `text`         | string  | Yes      | UTF-8 text to store.                                                                        |
| `private`      | boolean | No       | `false` stores the DataMap on the Autonomi Network; `true` returns the caller-held DataMap. |
| `payment_mode` | string  | No       | `auto`, `merkle`, or `single`. Default: `auto`.                                             |

**Result fields:** `address` (string), `chunks_stored` (integer), `payment_mode_used` (string), and `network` (string).

For private data, `address` contains the caller-held serialized DataMap. Losing it prevents retrieval. For public data, `address` is the stored DataMap's retrieval address.

### Retrieve Data

**Tool:** `retrieve_data(address, private=false)`

**Status:** Implemented.

| Parameter | Type    | Required | Description                                                             |
| --------- | ------- | -------- | ----------------------------------------------------------------------- |
| `address` | string  | Yes      | Public retrieval address, or a caller-held DataMap when `private=true`. |
| `private` | boolean | No       | Selects caller-held DataMap retrieval. Default: `false`.                |

**Result fields:** `text` (string) and `network` (string). Bytes that are not valid UTF-8 are decoded with replacement characters; use a file or chunk tool for arbitrary binary data.

### Upload a File

**Tool:** `upload_file(path, private=false, payment_mode="auto")`

**Status:** Limited. Requires a configured, funded, and approved wallet in `antd`. The path must exist on the `antd` host.

| Parameter      | Type    | Required | Description                                                                          |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `path`         | string  | Yes      | Absolute file path on the `antd` host.                                               |
| `private`      | boolean | No       | `false` stores the DataMap on the Autonomi Network; `true` returns it to the caller. |
| `payment_mode` | string  | No       | `auto`, `merkle`, or `single`. Default: `auto`.                                      |

**Result fields:** `address` (string), `storage_cost_atto` (string), `gas_cost_wei` (string), `chunks_stored` (integer), `payment_mode_used` (string), and `network` (string).

### Download a File

**Tool:** `download_file(address, dest_path, private=false)`

**Status:** Implemented when the `antd` host can write the destination.

| Parameter   | Type    | Required | Description                                                             |
| ----------- | ------- | -------- | ----------------------------------------------------------------------- |
| `address`   | string  | Yes      | Public retrieval address, or a caller-held DataMap when `private=true`. |
| `dest_path` | string  | Yes      | Destination on the `antd` host. Its parent directory must exist.        |
| `private`   | boolean | No       | Selects caller-held DataMap retrieval. Default: `false`.                |

**Result fields:** `status` (`"downloaded"`), `dest_path` (string), and `network` (string).

### Stream a File Download

**Tool:** `stream_download_file(address, dest_path, private=false)`

**Status:** Implemented when the `antd-mcp` host can write the destination.

| Parameter   | Type    | Required | Description                                                             |
| ----------- | ------- | -------- | ----------------------------------------------------------------------- |
| `address`   | string  | Yes      | Public retrieval address, or a caller-held DataMap when `private=true`. |
| `dest_path` | string  | Yes      | Destination on the `antd-mcp` host. An existing file is replaced.       |
| `private`   | boolean | No       | Selects caller-held DataMap retrieval. Default: `false`.                |

The MCP server streams bytes from `antd` and writes them without buffering the whole object.

**Result fields:** `status` (`"downloaded"`), `dest_path` (string), `bytes_written` (integer), and `network` (string).

### Estimate Cost

**Tool:** `get_cost(text=None, file_path=None, payment_mode="auto")`

**Status:** Limited. This tool returns an estimate, not a payment quote or charged amount.

| Parameter      | Type           | Required | Description                                     |
| -------------- | -------------- | -------- | ----------------------------------------------- |
| `text`         | string or null | No       | UTF-8 text to estimate.                         |
| `file_path`    | string or null | No       | File path on the `antd` host.                   |
| `payment_mode` | string         | No       | `auto`, `merkle`, or `single`. Default: `auto`. |

Provide at least one content input. If both are present, `text` takes precedence and `file_path` is ignored. If neither is present, the tool returns a `BAD_REQUEST` payload.

`antd` samples up to five chunk addresses and extrapolates the storage cost. Its gas value is an advisory heuristic rather than a live gas-oracle result. File estimates include the public DataMap chunk; text estimates expose no public/private selector and must not be treated as an exact estimate for default public `store_data`.

**Result fields:** `type` (`"data"` or `"file"`), `cost` (string), `file_size` (integer), `chunk_count` (integer), `estimated_gas_cost_wei` (string), `payment_mode` (string), and `network` (string).

### Check Health

**Tool:** `check_health()`

**Status:** Implemented.

**Parameters:** None.

**Result fields:** `healthy` (boolean), `network` (string), `version` (string), `evm_network` (string), `uptime_seconds` (integer), `build_commit` (string), `payment_token_address` (string), and `payment_vault_address` (string).

The result also reports `antd_mcp_version`, `latest_antd_mcp_version`, `update_available`, and `update_check`. When it starts, the server makes one request to PyPI for the latest release; `update_available` is null until PyPI answers, or when the check is off or failed, and `update_check` says which (`"pending"`, `"disabled"`, `"failed"`, or `"done"`). When a newer release exists, `update_hint` says how to upgrade.

The MCP server captures its `network` value during startup. If the initial health request fails, later tool payloads can continue to report `"network": "unknown"` until the MCP server restarts.

`healthy` reports that `antd` responds; it does not establish readiness to store data. This MCP tool does not expose `write_ready`, peer counts, the re-bootstrap threshold, or the last successful store age available from the [REST health endpoint](https://docs.autonomi.com/developers/sdk/reference/rest-api.md).

Decoded health response for the default Autonomi Network connection, after the update check has finished with no newer release (uptime varies):

```json
{
  "healthy": true,
  "network": "default",
  "version": "<antd version>",
  "evm_network": "arbitrum-one",
  "uptime_seconds": 0,
  "build_commit": "<build commit>",
  "payment_token_address": "0xa78d8321B20c4Ef90eCd72f2588AA985A4BDb684",
  "payment_vault_address": "0x9A3EcAc693b699Fc0B2B6A50B5549e50c2320A26",
  "antd_mcp_version": "<antd-mcp version>",
  "latest_antd_mcp_version": "<antd-mcp version>",
  "update_available": false,
  "update_check": "done"
}
```

## Wallet tools

### Get Wallet Address

**Tool:** `wallet_address()`

**Status:** Limited. Requires `AUTONOMI_WALLET_KEY` to configure a valid wallet in `antd`.

**Parameters:** None.

**Result fields:** `address` (string) and `network` (string).

### Get Wallet Balance

**Tool:** `wallet_balance()`

**Status:** Limited. Requires a wallet configured in `antd` and access to its EVM network.

**Parameters:** None.

**Result fields:** `balance` (string containing the Autonomi Network Token (ANT) balance in atto units), `gas_balance` (string containing the gas balance in wei), and `network` (string).

### Approve Wallet Spend

**Tool:** `wallet_approve()`

**Status:** Limited. This is a state-changing operation, not a configuration check.

**Parameters:** None.

The tool submits an ERC-20 approval transaction that lets the payment contract spend ANT for the wallet configured in `antd`. It requires enough gas and can incur a transaction fee.

**Result fields:** `approved` (boolean) and `network` (string).

## Chunk tools

### Store a Chunk

**Tool:** `chunk_put(data)`

**Status:** Limited. Requires a configured and funded wallet in `antd` and can pay for storage and gas.

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `data`    | string | Yes      | Base64-encoded raw chunk bytes. |

**Result fields:** `address` (string), `cost` (string), and `network` (string). `antd` returns an empty `cost` string because this endpoint does not report the prepaid per-chunk cost.

### Get a Chunk

**Tool:** `chunk_get(address)`

**Status:** Implemented.

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `address` | string | Yes      | 64-character hexadecimal chunk address. |

**Result fields:** `data` (base64-encoded string) and `network` (string).

## External-signer tools

The file and data external-signer tools are limited to preparations that return `payment_type: "wave_batch"`. If a prepare call returns `payment_type: "merkle"`, do not submit a payment from its MCP result. The required Merkle batch payment fields are incomplete. These tools also do not expose antd's signed-quote options or [quote verification](https://docs.autonomi.com/developers/sdk/reference/rest-api.md#verify-quotes).

External-signer tools do not require the wallet configured in `antd`. They do require an external wallet on the same EVM network as `antd`, enough ANT and gas, and explicit submission of the returned payment intent.

### Prepare a File Upload

**Tool:** `prepare_upload(path, visibility=None)`

**Status:** Limited to wave-batch results. The path must exist on the `antd` host.

| Parameter    | Type           | Required | Description                                                                          |
| ------------ | -------------- | -------- | ------------------------------------------------------------------------------------ |
| `path`       | string         | Yes      | Absolute file path on the `antd` host.                                               |
| `visibility` | string or null | No       | `"private"`, `"public"`, or `None`. Default: `None`, which selects private behavior. |

For a usable wave-batch preparation, the result fields are `upload_id`, `payment_type` (`"wave_batch"`), `payments`, `total_amount`, `payment_vault_address`, `payment_token_address`, `rpc_url`, `total_chunks`, `already_stored_count`, and `network`. Each `payments` item contains `quote_hash`, `rewards_address`, and `amount`.

With `visibility="public"`, the serialized DataMap chunk joins the same payment batch and the finalize result can include its public retrieval address.

### Prepare a Public File Upload

**Tool:** `prepare_upload_public(path)`

**Status:** Limited to wave-batch results. The path must exist on the `antd` host.

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `path`    | string | Yes      | Absolute file path on the `antd` host. |

This is equivalent to `prepare_upload(path, visibility="public")` and returns the same wave-batch fields.

### Prepare a Data Upload

**Tool:** `prepare_data_upload(data)`

**Status:** Limited to wave-batch results and private visibility.

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `data`    | string | Yes      | Base64-encoded bytes to prepare. |

The tool returns the same wave-batch fields as `prepare_upload`. It does not expose a visibility parameter, so it prepares a caller-held DataMap rather than a public DataMap address.

### Finalize a Wave-Batch Upload

**Tool:** `finalize_upload(upload_id, tx_hashes)`

**Status:** Limited to a prepare result with `payment_type: "wave_batch"`.

| Parameter   | Type   | Required | Description                                                       |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| `upload_id` | string | Yes      | Opaque identifier returned by the prepare tool.                   |
| `tx_hashes` | object | Yes      | Map from each `quote_hash` to its submitted EVM transaction hash. |

**Result fields:** `address` (string), `chunks_stored` (integer), `data_map` (hex-encoded string), `data_map_address` (string), and `network` (string).

The MCP flow does not request `antd`'s legacy `store_data_map` behavior, so `address` is empty. For a private preparation, keep `data_map`; `data_map_address` is empty. For a public preparation, use `data_map_address` as the public retrieval address.

### Finalize a Merkle Upload

**Tool:** `finalize_merkle_upload(upload_id, winner_pool_hash)`

**Status:** Unavailable through MCP.

| Parameter          | Type   | Required | Description                                                                                               |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `upload_id`        | string | Yes      | Opaque identifier returned by a prepare tool.                                                             |
| `winner_pool_hash` | string | Yes      | One winning pool hash. `antd` needs an ordered list for multi-batch uploads, which this tool cannot send. |

The function exists in the tool list, but the MCP prepare response does not provide a complete Merkle payment intent and this finalizer cannot represent multiple winner hashes. Do not use it to submit or finalize a paid upload.

### Prepare a Single-Chunk Upload

**Tool:** `prepare_chunk_upload(data_base64)`

**Status:** Limited. The no-payment result is usable; a new chunk requires external payment.

| Parameter     | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| `data_base64` | string | Yes      | Base64-encoded raw chunk bytes. |

When the chunk already exists, the result fields are `address`, `already_stored` (`true`), and `network`; no payment or finalize call is needed.

For a new chunk, the result fields are `address`, `already_stored` (`false`), `upload_id`, `payment_type` (`"wave_batch"`), `payments`, `total_amount`, `payment_vault_address`, `payment_token_address`, `rpc_url`, and `network`. Each `payments` item contains `quote_hash`, `rewards_address`, and `amount`.

### Finalize a Single-Chunk Upload

**Tool:** `finalize_chunk_upload(upload_id, tx_hashes)`

**Status:** Limited. Call it only after the external signer submits every payment returned by `prepare_chunk_upload`.

| Parameter   | Type   | Required | Description                                                       |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| `upload_id` | string | Yes      | Opaque identifier returned by `prepare_chunk_upload`.             |
| `tx_hashes` | object | Yes      | Map from each `quote_hash` to its submitted EVM transaction hash. |

**Result fields:** `address` (string) and `network` (string).

## Pointer tools

A pointer is an address you publish once and can later point at new content, such as each new version of a file. Its owner can move it, forward it to another pointer, or hand it over to another pointer for good.

Pointers need `antd` 0.16.0 or later. Reads are free. A create, update, or transfer costs about the price of one chunk, and every attempt pays again. These tools never retry a paid write, so check the pointer with `pointer_get` before repeating a failed call.

`antd` signs pointer writes with owner keys it loads at startup. Create a key with `ant pointer keygen --output <file>`, then start `antd` with `--pointer-keys <file-or-directory>` or set `ANTD_POINTER_KEYS_DIR`. Without a key, `antd` can read pointers but not write them. The tools name a pointer by its address; no key passes through MCP.

{% hint style="warning" %}
A pointer key cannot be replaced, because the pointer's address comes from it. Anyone who holds the key can hand the pointer over to themselves for good. Keep key files readable only by the account that runs `antd`.
{% endhint %}

Counters are returned as decimal strings, not JSON numbers. A final pointer's counter is `18446744073709551615`, which JSON number parsing rounds.

### List Writable Pointers

**Tool:** `pointer_keys()`

**Status:** Implemented. Free.

**Parameters:** None.

**Result fields:** `keys` (the 64-character hexadecimal addresses of the pointers this `antd` holds keys for) and `network` (string).

### Read a Pointer

**Tool:** `pointer_get(address, include_owner_key=false)`

**Status:** Implemented. Free.

| Parameter           | Type    | Required | Description                                                                                         |
| ------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `address`           | string  | Yes      | Pointer address: 64 hexadecimal characters, `0x` optional.                                          |
| `include_owner_key` | boolean | No       | Also return `owner`, the owner's public key (about 3,900 hexadecimal characters). Default: `false`. |

**Result fields:** `address`, `counter` (decimal string), `target`, `kind` (`"chunk"`, `"pointer"`, or `"unknown"`), `kind_tag`, `state_id`, `is_final` (boolean: `true` once the pointer is transferred or frozen, after which nothing can change it), `transferred_to` (string or null), and `network`. Returns `NOT_FOUND` when no pointer exists at the address.

### Resolve a Pointer

**Tool:** `pointer_resolve(address)`

**Status:** Implemented. Free.

| Parameter | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `address` | string | Yes      | Pointer address: 64 hexadecimal characters, `0x` optional. |

Follows forwarded and transferred pointers to the target at the end of the chain. When `kind` is `"chunk"` and the target was stored as public data or a public file, pass `target` to `retrieve_data` or `download_file`.

**Result fields:** `target`, `kind`, `kind_tag`, and `network`. Returns `NOT_FOUND` when a pointer on the chain does not exist.

### Check Pointer Finality

**Tool:** `pointer_finality(address)`

**Status:** Implemented. Free.

| Parameter | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `address` | string | Yes      | Pointer address: 64 hexadecimal characters, `0x` optional. |

Asks the pointer's close group, the nodes responsible for storing it, which state they hold. Check this before relying on a transfer: only `status: "final"` means one final state, held by a majority, with every node answering.

| Status        | Meaning                                                                              |
| ------------- | ------------------------------------------------------------------------------------ |
| `open`        | No node holds a final state. The owner can still move the pointer.                   |
| `settling`    | One final state, not yet held by a majority.                                         |
| `unconfirmed` | One final state held by a majority, but not every node answered. Ask again.          |
| `final`       | Settled.                                                                             |
| `forked`      | The owner signed two or more different final states.                                 |
| `unknown`     | A status this server does not recognize; `raw_status` has the value `antd` returned. |

**Result fields:** `status`, `raw_status`, `is_final` (boolean), `group` (number of nodes in the close group), `answered` (number that answered), `counter` (decimal string when `open`, otherwise null), `state` (the final state seen, for `settling`, `unconfirmed`, and `final`), `states` and `majority` (for `forked`), `transferred_to` (set once a transfer is final), and `network`. Each state contains `state_id`, `kind`, `kind_tag`, `target`, `holders` (number of nodes holding it), and `transferred_to`.

### Find a Pointer's Controller

**Tool:** `pointer_controller(address)`

**Status:** Implemented. Free.

| Parameter | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `address` | string | Yes      | Pointer address: 64 hexadecimal characters, `0x` optional. |

Follows every transfer from `address` to the pointer whose owner now decides what the address resolves to.

**Result fields:** `pointer` (that pointer's address), `transfers` (each pointer handed over to, in order), `frozen` (boolean: `true` when `pointer` is final without having been handed over, so nobody can move it), and `network`.

### Create a Pointer

**Tool:** `pointer_create(owner, target, kind="chunk")`

**Status:** Limited. Requires the owner's key in `antd` and a configured, funded wallet. Calling it pays about the price of one chunk.

| Parameter | Type   | Required | Description                                                                                      |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `owner`   | string | Yes      | Pointer address. `antd` must hold its key (see `pointer_keys`).                                  |
| `target`  | string | Yes      | Address to point at, such as the `address` from a public `store_data` or `upload_file`.          |
| `kind`    | string | No       | `chunk` for stored data or a file, or `pointer` to forward to another pointer. Default: `chunk`. |

**Result fields:** `address`, `state_id`, `counter` (decimal string), and `network`.

Returns `ALREADY_EXISTS`, before paying, when the pointer exists; use `pointer_update` instead. Returns `CONFLICT` when a prepared write to the pointer awaits payment.

### Update a Pointer

**Tool:** `pointer_update(owner, target, kind="chunk")`

**Status:** Limited. Requires the owner's key in `antd` and a configured, funded wallet. Calling it pays about the price of one chunk. Creates the pointer if it does not exist.

| Parameter | Type   | Required | Description                                                                                                                               |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `owner`   | string | Yes      | Pointer address. `antd` must hold its key (see `pointer_keys`).                                                                           |
| `target`  | string | Yes      | New address to point at.                                                                                                                  |
| `kind`    | string | No       | `chunk` for stored data or a file, or `pointer` to forward to another pointer. The owner can still change a forwarding. Default: `chunk`. |

**Result fields:** `address`, `state_id`, `counter` (decimal string, one higher than before), and `network`.

Returns `POINTER_FINAL` when the pointer was transferred or frozen and can never change; this is usually refused before paying. Returns `CONFLICT` either when a prepared write awaits payment, refused before paying, or when this update lost to a newer state and may already have been paid for. The error's `hint` says which.

### Transfer a Pointer

**Tool:** `pointer_transfer(owner, recipient, confirm_irreversible=false)`

**Status:** Limited and irreversible. Requires the owner's key in `antd` and a configured, funded wallet. Calling it pays about the price of one chunk.

A transfer makes the pointer at `owner` final for good: nobody, including its owner, can update or transfer it again. Readers of its address are sent on to the pointer at `recipient`, which only the recipient's owner can move. There is no undo.

Unless `confirm_irreversible` is `true`, the tool sends and pays nothing and returns `CONFIRMATION_REQUIRED`. Set it only after the user has confirmed this exact transfer, including both addresses.

| Parameter              | Type    | Required | Description                                                                            |
| ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `owner`                | string  | Yes      | Address of the pointer to hand over. `antd` must hold its key.                         |
| `recipient`            | string  | Yes      | Address of the pointer to hand it to. It must exist and must not lead back to `owner`. |
| `confirm_irreversible` | boolean | No       | Must be `true` to proceed. Default: `false`.                                           |

**Result fields:** `address`, `state_id`, `finality` (in the form `pointer_finality` returns), `finality_error`, and `network`. If the finality check failed, `finality` is null and `finality_error` says why. The transfer is stored either way: check it with `pointer_finality` and do not call this tool again.

### Prepare a Pointer Write for an External Signer

**Tool:** `pointer_prepare(owner, op, target=None, kind=None, recipient=None)`

**Status:** Limited. Requires the owner's key in `antd`. Payment comes from an external wallet.

`antd` signs the write with the owner key and returns a payment quote. It pays nothing and needs no `antd` wallet. Pay the returned `payments` from the external wallet, then call `pointer_finalize`. Until the write is finalized, or expires after one hour, other writes to the pointer return `CONFLICT`.

This tool has no confirmation step. A finalized transfer is irreversible, so confirm a transfer with the user before paying for it.

| Parameter   | Type           | Required                  | Description                                                        |
| ----------- | -------------- | ------------------------- | ------------------------------------------------------------------ |
| `owner`     | string         | Yes                       | Pointer address. `antd` must hold its key (see `pointer_keys`).    |
| `op`        | string         | Yes                       | `create`, `update`, or `transfer`.                                 |
| `target`    | string or null | For `create` and `update` | Address to point at.                                               |
| `kind`      | string or null | No                        | For `create` and `update`: `chunk` or `pointer`. Default: `chunk`. |
| `recipient` | string or null | For `transfer`            | Address of the pointer to hand it to.                              |

**Result fields:** `upload_id`, `op`, `address`, `state_id`, `counter` (decimal string), `payment_type` (`"wave_batch"`), `total_amount`, `payments`, `payment_vault_address`, `payment_token_address`, `rpc_url`, and `network`. Each `payments` item contains `quote_hash`, `rewards_address`, and `amount`.

`ALREADY_EXISTS`, `POINTER_FINAL`, and `BAD_REQUEST` are returned before any quote.

### Finalize a Pointer Write

**Tool:** `pointer_finalize(upload_id, tx_hashes)`

**Status:** Limited. Call it only after the external signer submits every payment returned by `pointer_prepare`.

| Parameter   | Type   | Required | Description                                                       |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| `upload_id` | string | Yes      | Identifier returned by `pointer_prepare`.                         |
| `tx_hashes` | object | Yes      | Map from each `quote_hash` to its submitted EVM transaction hash. |

**Result fields:** `address`, `state_id`, `counter` (decimal string), `finality` (for a transfer, in the form `pointer_finality` returns; otherwise null), and `network`.

* `CLOSE_GROUP_SHORTFALL` with `retryable: true`: the payment was kept. Call this tool again with the same `upload_id` to store the write without paying again; `tx_hashes` is ignored on a repeat. Stop after a few attempts, because the kept attempt expires after one hour. With `retryable: false`, nothing was kept.
* `BAD_REQUEST`: the hashes do not match the payment. Correct them and call again.
* `NOT_FOUND`: the `upload_id` expired or was already finalized.

## Manifest tools

A manifest bundles several uploaded files, each with an optional relative path, into one thing you can share as an `ant://manifest/` link or as a `.ant` file. Both tools are free: they upload and pay nothing.

### Build a Manifest

**Tool:** `build_manifest(entries, name=None, torrent_info_hashes=None, embed_roots=true)`

**Status:** Implemented. Free.

Upload the files first with `store_data` or `upload_file`, then pass what those tools returned.

| Parameter             | Type           | Required | Description                                                                                                                              |
| --------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `entries`             | list           | Yes      | The files, in any order. Each entry is an object with the fields below.                                                                  |
| `name`                | string or null | No       | Suggested root directory name.                                                                                                           |
| `torrent_info_hashes` | list or null   | No       | BitTorrent info-hashes (hexadecimal) to record.                                                                                          |
| `embed_roots`         | boolean        | No       | Embed each file's root DataMap so readers learn its exact size without fetching it. Set `false` for a smaller manifest. Default: `true`. |

Each entry needs exactly one of `data_map` or `address`:

| Entry field | Type    | Required         | Description                                                                                                               |
| ----------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `data_map`  | string  | One of these two | Hexadecimal DataMap from a private upload. It is embedded in the manifest, so anyone with the manifest can read the file. |
| `address`   | string  | One of these two | Address from a public upload.                                                                                             |
| `path`      | string  | No               | Relative path such as `notes/one.txt`. Without one, the entry is named by its content address.                            |
| `size`      | integer | No               | File size in bytes to record. Leave it out rather than passing `0`, unless the file is empty.                             |
| `sha256`    | string  | No               | Hexadecimal SHA-256 hash of the file's contents to record. Requires `antd` 0.17.0 or later.                               |

**Result fields:** `manifest_base64` (the `.ant` file, base64-encoded), `link` (the `ant://manifest/` link, or null when the manifest is larger than the recommended 1,500 bytes; share the file instead), `entries`, and `network`. Each entry contains `effective_name`, `path`, `size`, `kind` (`"embedded"` or `"public"`), `content_address`, `data_map`, `exact_size`, `error`, and `sha256`.

A bad entry returns `BAD_REQUEST` with a message naming it, such as `entries[2]`.

### Decode a Manifest

**Tool:** `decode_manifest(manifest_base64=None, link=None, resolve=false)`

**Status:** Implemented. Free.

| Parameter         | Type           | Required         | Description                                                                                                                                                                          |
| ----------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `manifest_base64` | string or null | One of these two | The `.ant` file, base64-encoded, as `build_manifest` returns it.                                                                                                                     |
| `link`            | string or null | One of these two | An `ant://manifest/` link, an `ant://file/` link, or a bare public address. The last two read as one entry with no path.                                                             |
| `resolve`         | boolean        | No               | Also fetch each entry's root from the network to fill in `exact_size` where the manifest does not record it. Needs the network and can time out; retrying is safe. Default: `false`. |

**Result fields:** `source` (`"manifest"` or `"file_link"`), `name`, `torrent_info_hash_v1`, `torrent_info_hash_v2`, `entries` (with the same fields as `build_manifest`), and `network`. Unset values are null, not `0`. An entry that fails to resolve reports the problem in its own `error` field.

To fetch an entry, pass its `content_address` to `retrieve_data` or `download_file`, or, for an embedded entry, its `data_map` with `private=true`.

## Payment modes

The internal-wallet `store_data`, `upload_file`, and `get_cost` tools accept these strings:

| Mode     | Description                                                                                 |
| -------- | ------------------------------------------------------------------------------------------- |
| `auto`   | Uses Merkle batch payment for 64 or more chunks and per-chunk payment below that threshold. |
| `merkle` | Forces Merkle batch payment; requires at least two chunks.                                  |
| `single` | Forces per-chunk payment.                                                                   |

These modes do not repair the external-signer Merkle limitation. `store_data` and `upload_file` send payment through the wallet configured in `antd`; `get_cost` estimates without submitting payment.

## Success and error responses

Every tool returns a string containing JSON-encoded text. MCP supplies it in `content[0].text` and also wraps that string in `structuredContent.result`. Decode either string to read the result fields listed on this page; those fields are not direct properties of `structuredContent`. Successful payloads include `network`.

Operation errors caught by the tools use the same output format. Clients must inspect the decoded payload for `error`; `isError: false` does not mean the Autonomi operation succeeded. Protocol and argument-validation failures can instead be reported by MCP itself.

Errors derived from the Python `AntdError` hierarchy contain:

| Field         | Type    | Description                                     |
| ------------- | ------- | ----------------------------------------------- |
| `error`       | string  | Normalized MCP error code.                      |
| `message`     | string  | Human-readable message.                         |
| `status_code` | integer | `antd` HTTP status code.                        |
| `network`     | string  | Network value captured when `antd-mcp` started. |

The formatter defines these codes:

| Code                    | Meaning                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NOT_FOUND`             | Requested content or upload state was not found.                                                                                                                                                                                                                                                                                     |
| `ALREADY_EXISTS`        | Content or state already exists.                                                                                                                                                                                                                                                                                                     |
| `VERSION_CONFLICT`      | A version or fork conflict was reported.                                                                                                                                                                                                                                                                                             |
| `BAD_REQUEST`           | Input failed validation.                                                                                                                                                                                                                                                                                                             |
| `PAYMENT_FAILED`        | A wallet or payment operation failed.                                                                                                                                                                                                                                                                                                |
| `NETWORK_ERROR`         | `antd` could not complete an Autonomi Network operation.                                                                                                                                                                                                                                                                             |
| `PARTIAL_UPLOAD`        | A paid upload stored only some chunks. The error also carries `chunks_stored`, `chunks_failed`, `total_chunks`, `retryable`, and `retention_known`. When `retryable` is `true`, call the same finalize tool again with the same upload ID to store the remainder without paying again; when it is `false`, prepare the upload again. |
| `TOO_LARGE`             | Input exceeded a size limit.                                                                                                                                                                                                                                                                                                         |
| `INTERNAL_ERROR`        | `antd` reported an internal failure.                                                                                                                                                                                                                                                                                                 |
| `SERVICE_UNAVAILABLE`   | `antd` has no wallet configured, or too few nodes are available yet. Refused before paying, so it is safe to try again later.                                                                                                                                                                                                        |
| `POINTER_FINAL`         | The pointer was transferred or frozen and can never change. Do not retry.                                                                                                                                                                                                                                                            |
| `POINTER_FORKED`        | The pointer's owner signed two different final states and the network has no answer. Do not retry; `pointer_finality` lists the states.                                                                                                                                                                                              |
| `CONFLICT`              | Another write to the pointer is in the way. The `hint` says whether anything was paid.                                                                                                                                                                                                                                               |
| `CLOSE_GROUP_SHORTFALL` | Too few of the responsible nodes answered or stored. Also carries `retryable`; see [Finalize a Pointer Write](#finalize-a-pointer-write).                                                                                                                                                                                            |
| `CONFIRMATION_REQUIRED` | `pointer_transfer` was called without `confirm_irreversible: true`. Nothing was sent or paid.                                                                                                                                                                                                                                        |
| `DAEMON_NOT_RUNNING`    | No `antd` is answering at the configured address. [Start the local daemon](https://docs.autonomi.com/developers/sdk/how-to-guides/start-the-local-daemon.md), or check `ANTD_BASE_URL`.                                                                                                                                              |
| `UNKNOWN`               | An `AntdError` subclass has no MCP mapping.                                                                                                                                                                                                                                                                                          |
| `UNEXPECTED`            | A non-`AntdError` exception occurred.                                                                                                                                                                                                                                                                                                |

`UNEXPECTED` payloads contain `error`, `message`, and `network`, but do not contain `status_code`.

The pointer codes, `SERVICE_UNAVAILABLE`, and `DAEMON_NOT_RUNNING` also carry a `hint` field saying what to do next. Read it before any further paid call.

## Upstream sources

* [antd-mcp source](https://gitlab.com/autonomi/ant-sdk/-/tree/main/antd-mcp)

## Related pages

* [How to Use the MCP Server](https://docs.autonomi.com/developers/agent-tools/use-the-autonomi-mcp-server.md)
* [Build with AI Tools](https://docs.autonomi.com/developers/agent-tools/use-mcp-with-ai-tools.md)
* [SDK Overview](https://docs.autonomi.com/developers/sdk/reference/overview.md)
* [REST API](https://docs.autonomi.com/developers/sdk/reference/rest-api.md)
