MCP server · Cleave

Connect

Add a remote MCP server with this URL:

https://api.cleave.fi/mcp

Most clients take a JSON entry like this:

{
  "mcpServers": {
    "cleave": {
      "url": "https://api.cleave.fi/mcp"
    }
  }
}

The server is stateless: every request stands on its own and no session is kept.

Pin a wallet

To limit a connection to one wallet, put the wallet in the path:

https://api.cleave.fi/mcp/0xYourWalletAddress

On a pinned connection:

cleave_plan_swap plans only for the pinned wallet. Another wallet is refused.
A plan to any other recipient comes back blocked, with no calls.
cleave_get_gas orders gas only for the pinned wallet.

Connection settings

Add settings to the connection URL as query parameters. They bind every tool call on that connection, and the agent cannot change them.

Setting	Values	Default	Effect
`maxUsd`	A positive dollar amount, up to 2 decimals	No cap	A plan worth more is blocked; a gas order above it is refused
`listedOnly`	`1` or `0`	`1`	With `1`, a plan whose token to receive is not on Cleave's token list is blocked

For example, a pinned wallet with a 250 USD cap:

https://api.cleave.fi/mcp/0xYourWalletAddress?maxUsd=250&listedOnly=1

When maxUsd is set and the token to sell has no price, the plan is blocked, because the cap cannot be checked. Any other query parameter is refused.

Tools

Tool	What it does	Moves funds
`cleave_plan_swap`	Plans a swap on one chain, a cross-chain swap or a bridge, and returns unsigned calls in signing order	No
`cleave_track_swap`	Reports the state of a sent plan or a gas order, and what arrived	No
`cleave_find_token`	Finds a token by symbol or address and flags look-alikes	No
`cleave_get_gas`	Offers native gas for USDC, then executes the order the wallet signed	Only the signed gas order

cleave_plan_swap

Input:

Field	Required	Meaning
`fromChainId`	yes	Chain id of the token to sell
`toChainId`	no	Chain id of the token to receive; defaults to `fromChainId`
`sellToken`, `buyToken`	yes	A listed symbol or a contract address
`amount`	yes	Decimal amount of `sellToken`, in token units, such as `"25.5"`
`wallet`	yes	The wallet that signs and pays
`recipient`	no	Who receives; defaults to `wallet`
`maxSlippageBps`	no	Slippage limit in basis points, 0 to 5000

The answer, in order of what to read first:

blocked and notices: a notice with level block means no calls; warn notices and a recipient other than the wallet set requiresConfirmation.
route.outcomeKind: exact, at_least, token_else_fallback, exact_or_refund_later or at_least_or_refund_later.
receive: the expected amount, the minimum, the fallback token if the swap on arrival fails, and where a refund goes if the transfer is not filled.
fees: costs charged by others, such as a bridge fee or a messaging fee in the native coin. Network gas is not listed.
pullsAtMost: the most the calls can take from the wallet.
validUntil: unix seconds. Calls sent later are stale.
calls: {chainId, from, to, data, value} for each transaction, in signing order.
requestId: pass it to cleave_track_swap.

cleave_track_swap

Input: chainId and txHash of the sent transaction, plus the plan's requestId when known. For a gas order, requestId alone.

The answer gives status, one of pending, in_flight, held_for_recipient, delivered, refund_pending, refunded or failed, with:

matchesPlan: whether the mined transaction runs the plan's call (null when it cannot be read)
arrived: chain, token, amount and transaction of what arrived, when known
next: what to do next, and pollAfterSec: when to check again
feedback: on a delivered swap or gas order only, where to leave feedback on ERC-8004

Track before sending a plan again: sending a plan that is still in flight can pay twice.

After a successful trade, agents can leave feedback on the ERC-8004 reputation registry for agentId 1135050 on Base.

cleave_find_token

Input: chainId and query, a symbol or a contract address. The answer lists candidates with their address, decimals and whether they are on Cleave's token list, with a lookalike flag when a token copies a listed one. A symbol shared by several listed tokens returns them all. An unlisted token is found only by its address.

cleave_get_gas

Two calls:

With payChainId, chainId, recipient, amount (USDC) and wallet, it returns an offer: the fee, the minimum native amount, the deadline and one USDC authorization to sign.
With offer, signature and wallet, it executes the order and returns a requestId for cleave_track_swap.

See x402 gas top-up for amounts, chains and outcomes.

Errors

A refusal comes back as a tool result with isError: true. Its structured content holds error.code, error.reason, error.message and error.retryable. A retryable refusal can carry retryAfterSec.

Limits

Each caller's address can make 40 requests per 10 seconds and 120 per minute. Requests from a known hosted platform, where many agents share one address, are counted by wallet instead: the pinned wallet, or the wallet in the request.
All agents share one planning capacity. When it is busy, the answer is rate_limited with reason agent_limit and a short retryAfterSec.
A request body can be at most 16 KiB.

Terms of use

Use of the API, the partner API and the MCP server is subject to the Terms of Use and the Privacy Policy. By sending requests or connecting a client after this notice, you accept them.

If an agent or other software calls Cleave, its operator accepts them and is responsible for what it does. Partner and agent keys are issued only after the key holder accepts them. Stay within the published rate limits.