> For the complete documentation index, see [llms.txt](https://docs.zeroauthority.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zeroauthority.xyz/nova-bot/nova-tools/using-nova-tools-with-ai-agents.md).

# Using Nova Tools with AI Agents

Nova's tools are available to AI agents via the **Model Context Protocol (MCP)** and a standard **REST API** with **x402 inline payments** on Stacks mainnet.

{% hint style="info" %}
No API keys, no subscriptions, no registration. Free tools run subject to rate limits; paid tools are paid per request via x402 — see the [x402 Payment Guide](/nova-bot/nova-tools/x402-payment-integration-guide.md) for payment mechanics, accepted tokens, and safety guarantees.
{% endhint %}

***

## Connecting

### Option 1: MCP Server (Recommended)

Install the Nova MCP server to give your agent native tool access:

```bash
npx @nova/mcp-server
```

Or connect directly via Streamable HTTP:

```
https://nova.zeroauthoritydao.com/mcp
```

**Environment variables** (optional):

| Variable               | Default                             | Description                                                            |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| `NOVA_API_URL`         | `https://nova.zeroauthoritydao.com` | Nova API base URL                                                      |
| `AGENT_STACKS_ADDRESS` | —                                   | Your Stacks address, sent as identity for the higher agent rate limits |

### Option 2: REST API (Direct)

Call tool endpoints directly with standard HTTP:

```bash
curl -X POST https://nova.zeroauthoritydao.com/api/tools/stacks-token-analytics/run \
  -H "Content-Type: application/json" \
  -d '{"input": {"token": "WELSH"}}'
```

Paid tools return **HTTP 402** with payment requirements — the [x402 Payment Guide](/nova-bot/nova-tools/x402-payment-integration-guide.md) covers how to complete payment and retry.

***

## Tool Discovery

The full catalog (50+ tools across Stacks, Bitcoin, EVM, Solana, TON, Sui, Aptos, Hyperliquid, and community ecosystems) is in the [Tools catalog](/nova-bot/nova-tools.md). Machine-readable listings:

| Endpoint                      | What it returns                                                    |
| ----------------------------- | ------------------------------------------------------------------ |
| `GET /api/tools`              | Tool list with slugs, input schemas, and pricing                   |
| `GET /.well-known/agent.json` | Agent manifest: tools, schemas, payment options, MCP endpoint info |
| `GET /api/tools/openapi.json` | OpenAPI spec                                                       |
| `GET /llms.txt`               | llms.txt index                                                     |

Over MCP, call `tools/list` — every tool is auto-discovered with full input schemas and pricing.

***

## Payment Model

| Caller Type                           | Paid Tools                                   | Free Tools                 |
| ------------------------------------- | -------------------------------------------- | -------------------------- |
| **Nova Premium** (JWT)                | Free within the monthly included-calls limit | Free, unlimited            |
| **Identified agent** (Stacks address) | x402 payment per call                        | Free, rate-limited         |
| **Anonymous** (IP only)               | x402 payment per call                        | Free, stricter rate limits |

Payment mechanics — headers, the 402 flow, accepted tokens, errors, and the verify → execute → settle safety guarantee — live in the [x402 Payment Guide](/nova-bot/nova-tools/x402-payment-integration-guide.md).

***

## Rate Limits

| Caller Type                                 | Limit                        |
| ------------------------------------------- | ---------------------------- |
| Identified agent (x402 / wallet-identified) | **10 req/min, 240 req/hour** |
| Anonymous (per IP)                          | **5 req/min, 120 req/hour**  |

Exceeding limits returns **429 Too Many Requests** (never 402). Include your Stacks address (`AGENT_STACKS_ADDRESS` / `X-STACKS-ADDRESS`) to get the higher agent limits.

***

## Example: Full Agent Flow

1. **Discover tools**: `GET /.well-known/agent.json`
2. **Call a tool**: `POST /api/tools/stacks-token-analytics/run` with `{"input": {"token": "WELSH"}}`
3. **Receive 402**: parse the `payment-required` header for payment options
4. **Sign payment** and **retry** with the `payment-signature` header ([details](/nova-bot/nova-tools/x402-payment-integration-guide.md))
5. **Receive results**: tool output in the body, settlement receipt in the `payment-response` header