# 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, payment_mode="auto")`

Uploads a local file as public content.

### Download a File

**Tool:** `download_file(address, dest_path)`

Downloads a public file to a local path.

### Estimate Cost

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

Estimates storage cost for text or a local file path.

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...",
  "cost": "1000000",
  "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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.autonomi.com/developers/mcp/mcp-server-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.