MCP server

Connect any MCP client to yield.xyz’s live tool server and look up every tool’s inputs, outputs, and access tier.

The yield.xyz MCP server exposes yield discovery, diligence, transaction building, and portfolio tracking as 22 typed tools that any Model Context Protocol client can call directly inside a conversation. Point Claude, Cursor, or another MCP-compatible agent at one endpoint and it works with live APYs, TVL, balances, and chain-correct unsigned transactions instead of guessing at request shapes.

Endpoint and transport

The server listens at https://mcp.yield.xyz/mcp over Streamable HTTP. It only accepts POST; a GET to the same path returns 405 rather than opening a legacy SSE stream.

Verify it’s live before wiring it into a client:

curl https://mcp.yield.xyz/health

{ "status": "ok", "service": "yield-mcp-server" }

A client that only supports local stdio servers connects through the mcp-remote bridge shown below rather than talking to the endpoint directly.

Authentication and access

Without a key, requests run against a shared service key and are metered per tool on a 24-hour rolling window: read tools per caller IP, wallet tools per wallet address. Over quota, any metered tool accepts an x402 micropayment per call, or you can wait for the window to roll:

Tier	Tools	Free calls / 24h	Beyond the free tier
Read (discovery, diligence, tracking)	yields_get_all, yields_get, yields_get_validators, yields_get_risk, yields_get_reward_rate_history, yields_get_tvl_history, yields_get_kyc_status, networks_get_all, providers_get_all, actions_get, actions_get_all, get_transaction	1,000 per tool, per caller IP	An x402 micropayment of $0.001 per call, or wait for the window to roll
Wallet execution	yields_get_balances, actions_enter, actions_exit, actions_manage	30 per tool, per wallet address	An x402 micropayment of $0.001 per call, or wait for the window to roll

x402 payments settle in USDC on Base, or USDC, USDT0, or USDG on X Layer. submit_hash and the five documentation tools carry no quota at all.

Set your own key with the x-api-key header on any transport, or an ?api_key= query parameter on the POST endpoint for clients that can’t set headers. A key you supply bypasses every quota and the x402 gate entirely; usage is billed to your own account instead. Get one from Projects & API keys.

Machine-readable pricing and tier data are also published at https://mcp.yield.xyz/.well-known/x402.

Connect a client

Any MCP client that can add a remote Streamable HTTP server takes the endpoint directly. A client that only supports stdio needs the mcp-remote bridge. This is the config the yield-xyz-agentkit plugin registers:

{
  "mcpServers": {
    "yield-xyz-agentkit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.yield.xyz/mcp"]
    }
  }
}

If your client is Claude Code, installing the yield-xyz-agentkit plugin registers this connection for you instead of editing config by hand.

Tool reference

The server registers 22 tools, grouped by job. Each yields, actions, transactions, networks, and providers tool maps to one Yield API endpoint; the docs tools read the live documentation and OpenAPI spec. Inputs marked required must be present; everything else is optional. Paid marks the four wallet-execution tools metered as described in Authentication and access.

Group	Tools	Covers
Yields	8	Search, full metadata, validators, risk, historical APY/TVL, live balances, KYC status
Actions	5	Build unsigned enter/exit/manage transactions, poll a single action, list a wallet’s actions
Transactions	2	Poll a transaction and register its broadcast hash
Networks & providers	2	Supported chains and the protocols/validator operators behind each yield
Docs	5	Search and read the live documentation, query the live OpenAPI spec, diagnose an API error, list reference repos

Always call yields_get before actions_enter or actions_exit, and yields_get_balances before actions_manage. A yield’s own mechanics.arguments schema is the authority on which fields it needs; never hardcode arguments from another yield. actions_enter, actions_exit, and actions_manage never sign or broadcast: sign the returned transactions in stepIndex order and report each hash with submit_hash. See Guardrails.

Yields

Tool	Inputs	Returns
yields_get_all	token: string sort: enum search: string networks: string[] types: enum[] (staking, lending, restaking, vault, concentrated_liquidity_pool, liquidity_pool, real_world_asset, fixed_yield) yieldIds: string[] (max 100) inputTokens: string[] providers: string[] hasCooldownPeriod: boolean hasWarmupPeriod: boolean limit: number (1 to 50, default 20) offset: number (default 0)	Paginated yields; id, name, token(s), network, type, providerId, reward rate, TVL (USD), status, cooldown/warmup/lockup in days, entry limits, and a full kyc object on RWA yields
yields_get	yieldId: string (required)	One yield’s full metadata; mechanics (type, cooldown/warmup/lockup, entry limits, fee, the arguments.enter/.exit field schemas, requiresValidatorSelection), reward rate, statistics, risk summary, input tokens
yields_get_validators	yieldId: string (required) limit: number (1 to 50, default 20) offset: number (default 0) preferred: boolean name: string status: string address: string provider: string	Paginated validators; address, name, status, reward rate, commission, preferred flag, TVL
yields_get_risk	yieldId: string (required)	Risk ratings for the yield; the schema is provider-defined and not fixed
yields_get_reward_rate_history	yieldId: string (required) period: enum (1d,7d,30d,90d,1y,all; default 30d) from: string (ISO date) to: string (ISO date) interval: enum (day,week,month; default day) limit: number (1 to 365, default 30) offset: number (default 0)	Time series of { timestamp, rewardRate } snapshots
yields_get_tvl_history	Same shape as yields_get_reward_rate_history	Time series of { timestamp, tvl, tvlRaw } snapshots
yields_get_balances Paid	address: string (required) network: string (required) yieldIds: string[]	items[]; one entry per yield with balances[] (amount, amountUsd, isEarning, token, pendingActions[] carrying the passthrough value for actions_manage); plus an errors[] array for yields that failed to resolve
yields_get_kyc_status	yieldId: string (required) address: string (required)	Normalized kycStatus for the wallet on that yield, with authorizeUrl when verification is required

Actions

Transaction-building tools never sign or broadcast; they return unsigned transactions for your own signer.

Tool	Inputs	Returns
actions_enter Paid	yieldId: string (required) address: string (required) amount: string (required) inputToken: string inputTokenNetwork: string validatorAddress: string executionMode: enum (individual, default; batched, reserved for future use) useMaxAllowance: boolean receiverAddress: string	An action with one or more ordered unsigned transactions (stepIndex order)
actions_exit Paid	yieldId: string (required) address: string (required) amount: string (required unless useMaxAmount is true) outputToken: string outputTokenNetwork: string validatorAddress: string executionMode: enum useInstantExecution: boolean useAutoClaim: boolean useMaxAmount: boolean receiverAddress: string	Same action shape as actions_enter. Does not accept passthrough; use actions_manage to complete a queued withdrawal
actions_manage Paid	yieldId: string (required) address: string (required) action: string (required); a pending-action type such as CLAIM_REWARDS or UNLOCK, read from yields_get_balances pendingActions[].type passthrough: string (required); from pendingActions[].passthrough, passed back verbatim amount: string executionMode: enum	Same action shape
actions_get	actionId: string (required)	The action’s current status and its transactions
actions_get_all	address: string (required) statuses: enum[] (CREATED, PROCESSING, WAITING_FOR_NEXT, SUCCESS, FAILED, CANCELED, STALE) intent: enum (enter,exit,manage) type: string yieldId: string network: string limit: number (1 to 100, default 20) offset: number (default 0)	Paginated actions for the address

Action object fields

actions_enter, actions_exit, and actions_manage all return the same action object:

Field	Type	Notes
id	string	Action ID; poll it with actions_get
intent	string	enter, exit, or manage
type	string	e.g. STAKE, UNSTAKE, CLAIM_REWARDS
yieldId / address	string
amount / amountRaw / amountUsd	string | null	Human-readable, raw, and USD-denominated amounts
executionPattern	string	synchronous, asynchronous or batch are declared; current actions return synchronous or batch
status	string	CREATED on success; poll actions_get until it reaches a terminal state
transactions	array	Ordered transaction objects, below
createdAt / completedAt	string | null
rawArguments	object | null	The arguments the action was built with

Transaction object fields

Each entry in transactions[]:

Field	Type	Notes
id	string	Pass to submit_hash and get_transaction
network / status / type / title	string	e.g. type APPROVAL, SUPPLY, UNSTAKE
stepIndex	number	Execution order; follow it sequentially
hash	string | null	null until broadcast
unsignedTransaction	string | object	A JSON string on EVM chains; a plain object on non-EVM chains. Never modify it
gasEstimate	string	A raw gas estimate; not a structured object
isMessage	boolean	When true, sign as a message instead of a transaction
annotatedTransaction / structuredTransaction	object | null	Free-form, human-readable breakdowns; no fixed schema

Transactions

Tool	Inputs	Returns
get_transaction	transactionId: string (required)	A transaction object. status is one of NOT_FOUND, CREATED, BLOCKED, WAITING_FOR_SIGNATURE, SIGNED, BROADCASTED, PENDING, CONFIRMED, FAILED, SKIPPED; CONFIRMED, FAILED, and SKIPPED are terminal
submit_hash	transactionId: string (required) hash: string (required, ≤100 chars)	The updated transaction with hash and broadcastedAt populated. Carries no quota; call it once per broadcast transaction; calling it again on an already-terminal transaction returns HTTP 412

Networks & providers

networks_get_all returns the full list, narrowed by search or category; providers_get_all paginates with limit/offset.

Tool	Inputs	Returns
networks_get_all	search: string (min 2 chars) category: enum (evm,cosmos,substrate,misc)	Array of { id, name, category, logoURI }
providers_get_all	limit: number (1 to 100, default 20) offset: number (default 0)	Paginated { id, name } for every protocol and validator provider

Docs

Builder-facing tools for developing an integration; not for live yield data or user transactions.

Tool	Inputs	Returns
yield_lookup_docs	query: string (required, 2 to 200 chars)	Up to 8 ranked documentation pages (title, section, description, URL) from the live llms.txt index
yield_fetch_doc	url: string (required); a docs.yield.xyz URL, typically from yield_lookup_docs	The full markdown of that page
yield_get_api_spec	endpoint: string method: enum (get,post,put,patch,delete,all; default all) query: string section: enum (endpoints,schemas,errors,all; default all)	Formatted endpoint, schema, or error detail read live from https://api.yield.xyz/docs.json
yield_troubleshoot_error	error: string (required) context: string	A diagnosis, a fix, and a doc reference; falls back to a live OpenAPI-spec lookup when the error isn’t in the static catalog
yield_list_repos	none	A categorized list of public yield.xyz GitHub repos (widget, SDK, signing libraries, assets) with raw-file fetch instructions

Next steps

AgentKit for Claude Code

Install the plugin that registers this connection automatically.

Guardrails

Rules an agent follows before it signs or broadcasts anything.

Agent skills

Install yield.xyz capability into agents outside Claude Code.

Yield API reference

The REST API behind every tool.