> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pods.finance/llms.txt
> Use this file to discover all available pages before exploring further.
# Pods MCP Server
> Connect AI agents and coding assistants to Pods's DeFi infrastructure with zero-config tool discovery
The Pods MCP Server exposes the full Pods API as a set of discoverable, typed tools for any MCP-compatible AI host — Claude Desktop, Cursor, Windsurf, and others. Your AI assistant can quote swaps, generate deposit bytecode, check wallet positions, and scaffold SDK projects without ever constructing a raw HTTP request.
**Machine-readable resources:**
* [llms.txt](/llms.txt) — Structured overview for LLM consumption
* [OpenAPI Spec](/openapi.yaml) — Full API specification
## When to Use What
| Use Case | Recommended | Why |
| ----------------------------------------- | --------------- | --------------------------------------------------------------- |
| Execute DeFi operations from a backend | **API** | Direct HTTP calls, full control |
| Build a frontend with yield and swap UI | **SDK Widgets** | Handles wallets, signing, execution |
| AI agent in an MCP-compatible host | **MCP Server** | Zero-config tool discovery, typed inputs and outputs |
| Scaffold a new project inside your AI IDE | **MCP Server** | Generates all files for Next.js, React, Remix, Gatsby |
| Decode errors inline while developing | **MCP Server** | `get_error_explanation` returns causes, retryability, and fixes |
| Integrate without additional dependencies | **API** | Simple HTTP, no runtime required |
For AI agents running inside MCP-compatible hosts like Claude, Cursor, or Windsurf, the MCP Server is the most streamlined path — it exposes every core endpoint as a discoverable tool with typed parameters so the agent never has to construct raw HTTP requests.
## Capabilities
The server ships with **25 tools** and **9 prompts** across five categories.
Get quotes, generate signed bytecode, and track status for same-chain and cross-chain swaps
List strategies, get quotes, deposit and withdraw, check open positions and transaction history
Scaffold frontend projects, validate provider configs, check SDK compatibility, and write env files
Health checks, API key validation, token listing, and error code explanations
Higher-order workflows that chain multiple atomic tools into a single orchestrated call — swap+deposit, best-yield lookup, rebalance, and integration pre-flight
## Minimal Tool Set
These five tools cover the most common agent workflows.
### 1. Recommend Integration Path
Analyzes your stack and recommends API Direct or SDK Widgets.
**Tool:** `recommend_integration_path`
**Key inputs:** `frontendFramework`, `walletProvider`, `backendLanguage`, `features`
**Returns:** recommended path with rationale.
### 2. Get a Swap Quote
Request a ready-to-execute quote for a token swap.
**Tool:** `get_swap_quote`
**Key inputs:** `fromChain`, `toChain`, `fromToken`, `toToken`, `fromAmount`, `fromAddress`
**Returns:** quote object with `transactionRequest` and expiry timestamp.
Quotes expire after 5 minutes. Call `execute_swap_bytecode` promptly after receiving one.
### 3. Get Deposit Bytecode
Generate transactions for depositing into a yield strategy.
**Tool:** `get_deposit_bytecode`
**Key inputs:** `strategyId`, `amount`, `wallet`, `action`
**Returns:** ordered array of transactions to sign and broadcast.
The array may contain multiple transactions (e.g. token approval + deposit). Execute them in order.
### 4. Check Wallet Positions
Get all open yield positions for a wallet address.
**Tool:** `get_wallet_positions`
**Key inputs:** `wallet`
**Returns:** positions with current value, principal, profit, and APY per strategy, plus a total balance summary.
### 5. Explain an Error
Decode a Pods error code with causes, retry guidance, and resolution steps.
**Tool:** `get_error_explanation`
**Key inputs:** `errorCode`
**Returns:** human-readable description, causes, whether it is retryable, and fix suggestions.
## Skills
Skills are higher-order workflows that chain multiple atomic tools into a single orchestrated call — `swap_and_deposit`, `find_best_yield_for_asset`, `rebalance_position`, `diagnose_integration`, plus two analytical prompts (`portfolio_briefing`, `integration_review`). They support `dryRun` preview mode, partial-success returns that preserve already-generated bytecode when a later step fails, and dedicated error codes consumable via `get_error_explanation`.
Decision table, per-skill deep dives, dryRun and partial-success walkthroughs, skill-level error code reference, and runtime documentation resources.
## Pre-built Prompts
The server ships with 9 conversation starters for common integration scenarios. Invoke them by name from your AI host.
| Prompt | What It Does |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `choose_integration_path` | Wizard that picks API Direct vs SDK Widgets for your stack |
| `troubleshoot` | Diagnoses errors given a code, tx state, and description |
| `api_quickstart` | Step-by-step guide for a given feature and language |
| `api_integration_wizard` | Full flow: quote → bytecode → signing → status tracking |
| `sdk_quickstart` | Fast path: scaffold → env setup → validate config |
| `sdk_integration_wizard` | Complete SDK setup: compatibility → scaffold → validate |
| `sdk_migration_guide` | Breaking changes and migration steps between SDK versions |
| `portfolio_briefing` | Skills prompt: guided analytical briefing of a wallet's yield portfolio — positions, recent activity, underperformers, and recommended rebalances |
| `integration_review` | Skills prompt: audit workspace Pods code against a pitfalls checklist (quote TTL, rawQuote forwarding, EIP-1193 value encoding, action names, webhook signature) |
## Decision Rules
### API Direct vs SDK Widgets
* **API Direct** — your backend generates transactions and your frontend signs them with any wallet library (ethers.js, viem, wagmi)
* **SDK Widgets** — you want pre-built React components that handle the full swap or yield UX with built-in wallet connection
Call `recommend_integration_path` if you are unsure which path fits your stack.
### Handling Swap Status
```
Status: PENDING
└── Poll every 10–30 seconds
Status: DONE
├── substatus: COMPLETED → Transfer successful
├── substatus: PARTIAL → User received a different token (still success)
└── substatus: REFUNDED → Tokens returned to sender
Status: FAILED
└── Check error message, may need user intervention
```
## Observability
In HTTP mode, the server includes a built-in dashboard at `/dashboard` showing tool call counts, latency, error rates, and session quality. Events are logged to NDJSON files and can be forwarded to a central collector for aggregation across multiple instances.
## Next Steps
Higher-order workflows with dryRun, partial-success, and skill-level error codes
Install and configure the MCP server in your AI host
Complete reference for all 25 tools and 9 prompts
Make your first API call in 5 minutes