> 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/mcp/mcp-server-reference.md).

# MCP Server Reference

Reference for the `antd-mcp` server that exposes the `antd` daemon as MCP tools for AI agents and MCP-compatible clients.

## Server command

### Main command

**Command:** `antd-mcp`

Runs the MCP server in stdio mode by default.

### SSE mode

**Command:** `antd-mcp --sse`

Runs the MCP server in SSE mode for web-based clients.

## Installation

Use this setup:

```bash
pip install "antd[rest]"
pip install -e antd-mcp/
```

Run the editable install from an `ant-sdk` checkout root.

The package metadata declares:

* Python `>=3.10`
* dependency on `mcp>=1.2.0`
* dependency on `antd>=0.1.0`

## Configuration

### Environment variables

| Variable        | Required | Description                                                                             |
| --------------- | -------- | --------------------------------------------------------------------------------------- |
| `ANTD_BASE_URL` | No       | Overrides daemon auto-discovery and points the MCP server at a specific `antd` REST URL |

### Daemon discovery order

At startup, the server resolves the daemon base URL in this order:

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

The discovery helper still checks a `daemon.port` file before falling back to the default URL.

`antd` writes the port file to `ant/sdk/daemon.port` and `antd-mcp` reads from the same path, so port-file discovery works without `ANTD_BASE_URL` when both are installed from the same `ant-sdk` checkout. Set `ANTD_BASE_URL` explicitly when you want a fixed URL regardless of port-file state, or when you are running `antd-mcp` against a daemon on a different host.

## Claude Desktop configuration

```json
{
  "mcpServers": {
    "antd-autonomi": {
      "command": "antd-mcp",
      "env": {
        "ANTD_BASE_URL": "http://127.0.0.1:8082"
      }
    }
  }
}
```

Adjust `ANTD_BASE_URL` if your daemon runs on a different host or port.

## Data tools

### Store Data

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

Stores text on the network as public or private data.

### Retrieve Data

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

Retrieves text from the network by address or DataMap.

### Upload a File

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

Uploads a local file to the network. When `private=True`, the returned `address` is the caller-held DataMap and is not stored on-network. When `private=False` (default), the DataMap is stored on-network and `address` is the public retrieval address.

### Download a File

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

Downloads a file to a local path. Pass the on-network address when `private=False` (default) or the caller-held DataMap when `private=True`. The daemon writes the file, so the daemon and the MCP server must share a filesystem.

### Stream a File Download

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

Downloads a file to `dest_path` like `download_file`, but streams the bytes back to the MCP server process and writes them on the MCP server's host one chunk at a time with constant memory. Use it for large objects, or when the daemon and MCP server do not share a filesystem. Pass the on-network address when `private=False` (default) or the caller-held DataMap when `private=True`. The response includes `bytes_written`.

### Estimate Cost

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

Estimates storage cost for text or a local file path. Pass `payment_mode` to reflect the cost of a specific payment strategy.

Provide exactly one of `text` or `file_path`.

### Check Health

**Tool:** `check_health()`

Checks daemon health and returns the current network name.

## Wallet tools

### Get Wallet Address

**Tool:** `wallet_address()`

Returns the wallet public address configured in the daemon.

### Get Wallet Balance

**Tool:** `wallet_balance()`

Returns token and gas balances from the daemon.

### Approve Wallet Spend

**Tool:** `wallet_approve()`

Approves token spend on payment contracts.

## Chunk tools

### Store a Chunk

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

Stores a raw chunk. The input is base64-encoded.

### Get a Chunk

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

Fetches a raw chunk and returns base64-encoded data.

## External-signer tools

### Prepare a File Upload

**Tool:** `prepare_upload(path, visibility?)`

Prepares a file upload for external signing and returns payment details plus a `payment_type` discriminator. Pass `visibility="public"` to include the serialized DataMap chunk in the same payment batch; the finalize response then includes `data_map_address`, the public retrieval address for the upload.

### Prepare a Public File Upload

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

Convenience wrapper equivalent to `prepare_upload(path, visibility="public")`. Use it when the external signer should pay for both the file chunks and the DataMap chunk in one batch.

### Prepare a Data Upload

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

Prepares a private data upload for external signing. The input is base64-encoded.

The file and data prepare tools return either:

* `payment_type: "wave_batch"` with quote-level `payments`
* `payment_type: "merkle"` with `depth`, `pool_commitments`, `merkle_payment_timestamp`, and `payment_vault_address`

### Finalize a Wave-Batch Upload

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

Finalizes an externally-signed upload when the prepare step returned `payment_type: "wave_batch"`. Returns `address`, `chunks_stored`, `data_map`, and `data_map_address`. `data_map` is the hex-encoded serialized DataMap. `data_map_address` is set when the upload was prepared with `visibility="public"`; otherwise it is empty.

### Finalize a Merkle Upload

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

Finalizes an externally-signed upload when the prepare step returned `payment_type: "merkle"`. Returns the same fields as `finalize_upload`.

### Prepare a Single-Chunk Upload

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

Prepares one raw chunk for external-signer upload. If the chunk is already stored, the response contains `already_stored=true` and `address`, and no payment or finalize call is needed. Otherwise, the response contains a wave-batch payment intent with `upload_id`, `payments`, `total_amount`, payment contract addresses, and `rpc_url`.

### Finalize a Single-Chunk Upload

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

Submits a prepared chunk to the network after the external signer has paid. Returns `address`, the network address of the stored chunk.

## Payment modes

The server accepts the same daemon payment mode strings for the tools that upload content:

| Mode     | Description                |
| -------- | -------------------------- |
| `auto`   | Default mode               |
| `merkle` | Force Merkle batch payment |
| `single` | Force per-chunk payments   |

## Success and error responses

Successful tool responses are JSON and always include a `network` field.

Examples:

```json
{
  "healthy": true,
  "network": "local",
  "version": "0.6.1",
  "evm_network": "local",
  "uptime_seconds": 42,
  "build_commit": "529280c3",
  "payment_token_address": "",
  "payment_vault_address": ""
}
```

Example `upload_file` response:

```json
{
  "address": "abc123...",
  "storage_cost_atto": "1000000",
  "gas_cost_wei": "42000000000000",
  "chunks_stored": 7,
  "payment_mode_used": "auto",
  "network": "local"
}
```

Example `store_data` response:

```json
{
  "address": "abc123...",
  "chunks_stored": 1,
  "payment_mode_used": "auto",
  "network": "local"
}
```

Structured `AntdError` responses include:

| Field         | Description                                                                   |
| ------------- | ----------------------------------------------------------------------------- |
| `error`       | Normalized error code such as `NOT_FOUND`, `BAD_REQUEST`, or `PAYMENT_FAILED` |
| `message`     | Human-readable message                                                        |
| `status_code` | Daemon HTTP status code                                                       |
| `network`     | Connected network                                                             |

Unexpected errors include `error`, `message`, and `network`, but may not include `status_code`.

## Upstream sources

* [ant-sdk](https://github.com/WithAutonomi/ant-sdk)

## Related pages

* [How to Use the MCP Server](/developers/mcp/use-the-autonomi-mcp-server.md)
* [SDK Overview](/developers/sdk/install/reference/overview.md)
* [REST API](/developers/sdk/install/reference/rest-api.md)