API MCP

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

https://si.ampli.net/mcp

Two MCP serversThis 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.

Tools

Tool	Arguments	Does	Price unit
`optimize`	`chain_id`, `request` (the optimize 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 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.

Cursor
Claude Code
TypeScript SDK

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

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

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"

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.

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.

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

Sign and retry

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

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

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.

Get started

API

Agents

Reference

Tools

What is free

Connect with a partner key

Pay per call with x402

Rules for agents