> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://modelcontextprotocol.io/) 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:

```bash theme={null}
curl https://mcp.yield.xyz/health
```

```json theme={null}
{ "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](https://github.com/coinbase/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](/documentation/get-started/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:

```json theme={null}
{
  "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](/documentation/ai-agents/agentkit/claude-code) 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. <Badge color="orange">Paid</Badge> marks the four wallet-execution tools metered as described in [Authentication and access](#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 |

<Note>
  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](/documentation/ai-agents/agentkit/guardrails).
</Note>

### Yields

| Tool | Inputs | Returns |
| - | - | - |
| `yields_get_all` | `token: string`<br />`sort: enum`<br />`search: string`<br />`networks: string[]`<br />`types: enum[]` (`staking`, `lending`, `restaking`, `vault`, `concentrated_liquidity_pool`, `liquidity_pool`, `real_world_asset`, `fixed_yield`)<br />`yieldIds: string[]` (max 100)<br />`inputTokens: string[]`<br />`providers: string[]`<br />`hasCooldownPeriod: boolean`<br />`hasWarmupPeriod: boolean`<br />`limit: number` (1 to 50, default 20)<br />`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)**<br />`limit: number` (1 to 50, default 20)<br />`offset: number` (default 0)<br />`preferred: boolean`<br />`name: string`<br />`status: string`<br />`address: string`<br />`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)**<br />`period: enum` (`1d`,`7d`,`30d`,`90d`,`1y`,`all`; default `30d`)<br />`from: string` (ISO date)<br />`to: string` (ISO date)<br />`interval: enum` (`day`,`week`,`month`; default `day`)<br />`limit: number` (1 to 365, default 30)<br />`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` <Badge color="orange">Paid</Badge> | `address: string` **(required)**<br />`network: string` **(required)**<br />`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)**<br />`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` <Badge color="orange">Paid</Badge> | `yieldId: string` **(required)**<br />`address: string` **(required)**<br />`amount: string` **(required)**<br />`inputToken: string`<br />`inputTokenNetwork: string`<br />`validatorAddress: string`<br />`executionMode: enum` (`individual`, default; `batched`, reserved for future use)<br />`useMaxAllowance: boolean`<br />`receiverAddress: string` | An action with one or more ordered unsigned transactions (`stepIndex` order) |
| `actions_exit` <Badge color="orange">Paid</Badge> | `yieldId: string` **(required)**<br />`address: string` **(required)**<br />`amount: string` (required unless `useMaxAmount` is `true`)<br />`outputToken: string`<br />`outputTokenNetwork: string`<br />`validatorAddress: string`<br />`executionMode: enum`<br />`useInstantExecution: boolean`<br />`useAutoClaim: boolean`<br />`useMaxAmount: boolean`<br />`receiverAddress: string` | Same action shape as `actions_enter`. Does not accept `passthrough`; use `actions_manage` to complete a queued withdrawal |
| `actions_manage` <Badge color="orange">Paid</Badge> | `yieldId: string` **(required)**<br />`address: string` **(required)**<br />`action: string` **(required)**; a pending-action type such as `CLAIM_REWARDS` or `UNLOCK`, read from `yields_get_balances` `pendingActions[].type`<br />`passthrough: string` **(required)**; from `pendingActions[].passthrough`, passed back verbatim<br />`amount: string`<br />`executionMode: enum` | Same action shape |
| `actions_get` | `actionId: string` **(required)** | The action's current status and its transactions |
| `actions_get_all` | `address: string` **(required)**<br />`statuses: enum[]` (`CREATED`, `PROCESSING`, `WAITING_FOR_NEXT`, `SUCCESS`, `FAILED`, `CANCELED`, `STALE`)<br />`intent: enum` (`enter`,`exit`,`manage`)<br />`type: string`<br />`yieldId: string`<br />`network: string`<br />`limit: number` (1 to 100, default 20)<br />`offset: number` (default 0) | Paginated actions for the address |

<AccordionGroup>
  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |
  </Accordion>
</AccordionGroup>

### 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)**<br />`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)<br />`category: enum` (`evm`,`cosmos`,`substrate`,`misc`) | Array of `{ id, name, category, logoURI }` |
| `providers_get_all` | `limit: number` (1 to 100, default 20)<br />`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`<br />`method: enum` (`get`,`post`,`put`,`patch`,`delete`,`all`; default `all`)<br />`query: string`<br />`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)**<br />`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

<Columns cols={2}>
  <Card title="AgentKit for Claude Code" icon="plug" href="/documentation/ai-agents/agentkit/claude-code">
    Install the plugin that registers this connection automatically.
  </Card>

  <Card title="Guardrails" icon="shield" href="/documentation/ai-agents/agentkit/guardrails">
    Rules an agent follows before it signs or broadcasts anything.
  </Card>

  <Card title="Agent skills" icon="puzzle-piece" href="/documentation/ai-agents/agentkit/agent-skills">
    Install yield.xyz capability into agents outside Claude Code.
  </Card>

  <Card title="Yield API reference" icon="book" href="/api-reference/getting-started">
    The REST API behind every tool.
  </Card>
</Columns>


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