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:

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

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

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

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

Example store_data response:

{
  "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

Related pages

• How to Use the MCP Server

• SDK Overview

• REST API