> ## Documentation Index
> Fetch the complete documentation index at: https://docs.si.ampli.net/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the Ampli Intelligence docs. API base: https://si.ampli.net/api/v1. API MCP: https://si.ampli.net/mcp.
> Auth is a partner key (X-Partner-Name and X-Partner-API-Key headers) or an x402 payment in USDC on Base.
> For a single-treasury agentic wallet or Wallet-as-a-Service, use the ampli^ SDK at https://ampli.net and https://docs.ampli.net. agk_ keys and /api/v1/agent-runtime belong to that SDK.
> Use only the routes and tools documented here. Do not invent endpoints or parameters.
> The ampli^ SDK (https://ampli.net, docs at https://docs.ampli.net) can use this intelligence to deliver a single-treasury agentic wallet or Wallet-as-a-Service. This host is si.ampli.net. Auth is a partner key or an x402 payment. agk_ keys and /api/v1/agent-runtime belong to the SDK Agent API.
> Every amount is an integer string in the token's base units. USDC, EURC, USDT0, and USDG use 6 decimals (1000000 is 1 USDC). WETH and cbETH use 18. cbBTC uses 8.
> The service is non-custodial. It returns an allocation, an action plan, and calldata. It never holds keys, signs, or sends a transaction.
> APR values are percentages measured now or over the trailing 7 days. They are not forecasts and nothing here guarantees a return.
> x402 payments are verified before the work and settled only when the response is 2xx. A 400 or 422 costs nothing.
> Partner headers always win. A request with a wrong partner key returns 401 and does not fall back to payment.
> Monitor alerts arrive only on the websocket. create_monitor_session returns a token; the client must open the socket itself.
> Market names in optimize must come from list_protocols for the same chain and token. Do not guess names.

# API MCP

> The four Ampli Intelligence capabilities as MCP tools at https://si.ampli.net/mcp. Discovery is free; each tool call needs partner headers or an x402 payment in _meta.

The API MCP server exposes the same handlers as the REST API, over Streamable HTTP:

```text theme={null}
https://si.ampli.net/mcp
```

> [!NOTE]
>
> **Two MCP servers**
>
> This page is about the **API MCP**, which runs paid tools. The **docs MCP** at `https://docs.si.ampli.net/mcp` is free and read-only: it searches and reads these pages. See [Build with AI](https://docs.si.ampli.net/build-with-ai.md).

## Tools

| Tool | Arguments | Does | Price unit |
| :- | :- | :- | :- |
| `optimize` | `chain_id`, `request` (the [optimize](https://docs.si.ampli.net/optimize.md) body) | Allocation, action plan, calldata. Executes nothing | per call |
| `list_protocols` | `chain_id`, `token_address` | Markets for a token with current and 7-day net APR | per call |
| `protocol_health` | `assets`: list of `{chain_id, address}` | Peg, utilization, liquidity, backing | per asset |
| `create_monitor_session` | `hours` (1 to 24) | Token for the [monitor](https://docs.si.ampli.net/monitor.md) websocket | per hour |

Each tool description includes its current price. Results come back as JSON in both `content` and `structuredContent`. Amounts are base units, as in the REST API.

Typical order: `list_protocols` for market names, `protocol_health` for any market you are unsure about, then `optimize` with those names.

## What is free

`initialize`, `tools/list`, and the tool schemas cost nothing. Only `tools/call` is paid.

## Connect with a partner key

Send the partner headers on the MCP HTTP request. No payment is taken for any tool.

> [tab] Cursor
>
> Add to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "ampli-intelligence": {
>       "url": "https://si.ampli.net/mcp",
>       "headers": {
>         "X-Partner-Name": "your-partner-name",
>         "X-Partner-API-Key": "${env:AMPLI_PARTNER_API_KEY}"
>       }
>     }
>   }
> }
> ```

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http ampli-intelligence https://si.ampli.net/mcp \
>   --header "X-Partner-Name: your-partner-name" \
>   --header "X-Partner-API-Key: $AMPLI_PARTNER_API_KEY"
> ```

> [tab] TypeScript SDK
>
> ```ts theme={null}
> import { Client } from "@modelcontextprotocol/sdk/client/index.js";
> import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
>
> const transport = new StreamableHTTPClientTransport(new URL("https://si.ampli.net/mcp"), {
>   requestInit: {
>     headers: { "X-Partner-Name": "your-partner-name", "X-Partner-API-Key": process.env.AMPLI_PARTNER_API_KEY! },
>   },
> });
> const client = new Client({ name: "my-agent", version: "1.0.0" });
> await client.connect(transport);
>
> const markets = await client.callTool({
>   name: "list_protocols",
>   arguments: { chain_id: 8453, token_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
> });
> ```

A wrong partner key returns an error result with status `401`. It does not fall back to payment.

## Pay per call with x402

Without partner headers, every `tools/call` needs an x402 payment. This needs an MCP client that can sign x402 payments; editors such as Cursor cannot do this on their own, so use partner headers there.

**1. Call the tool**

A call without payment returns `isError: true`. Its `structuredContent` is the x402 offer, the same JSON as the REST `PAYMENT-REQUIRED` header, with the price for this call in `accepts`.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_protocols",
    "arguments": { "chain_id": 8453, "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }
  }
}
```

**2. Sign and retry**

Sign the offer with an x402 client and put the payment payload object in `params._meta["x402/payment"]`.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_protocols",
    "arguments": { "chain_id": 8453, "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
    "_meta": {
      "x402/payment": {
        "x402Version": 2,
        "accepted": { "scheme": "exact", "network": "eip155:8453", "amount": "10000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xAmpliTreasury", "maxTimeoutSeconds": 120, "extra": { "name": "USD Coin", "version": "2" } },
        "payload": { "signature": "0x...", "authorization": { "from": "0xPayer", "to": "0xAmpliTreasury", "value": "10000", "validAfter": "0", "validBefore": "1763000000", "nonce": "0x..." } }
      }
    }
  }
}
```

**3. Read the receipt**

The successful result carries the settlement in `result._meta["x402/payment-response"]`, with the transaction hash.

Payment follows the same rules as REST: verified before the tool runs, settled only when it succeeds. A validation error, such as an empty `assets` list or `hours` above 24, settles nothing.

## Rules for agents

* Use only these four tools and the documented arguments. Do not invent tools or fields.
* `create_monitor_session` returns a token. Your agent must open the websocket itself; the MCP server does not hold it.
* Never ask a person for a private key. The tools need none, and the paying wallet signs on the client side.
* Report amounts in base units and in human units, and never present an APR as a promise.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.