Pods MCP Server - Pods API

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 — Structured overview for LLM consumption
OpenAPI Spec — 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.

Swap

Get quotes, generate signed bytecode, and track status for same-chain and cross-chain swaps

Yield

List strategies, get quotes, deposit and withdraw, check open positions and transaction history

SDK Widgets

Scaffold frontend projects, validate provider configs, check SDK compatibility, and write env files

Diagnostics

Health checks, API key validation, token listing, and error code explanations

Skills

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. 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.

Full Skills Guide

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

Skills Guide

Higher-order workflows with dryRun, partial-success, and skill-level error codes

Setup Guide

Install and configure the MCP server in your AI host

Tools Reference

Complete reference for all 25 tools and 9 prompts

Quickstart

Make your first API call in 5 minutes

​When to Use What

​Capabilities

Swap

Yield

SDK Widgets

Diagnostics

Skills

​Minimal Tool Set

​1. Recommend Integration Path

​2. Get a Swap Quote

​3. Get Deposit Bytecode

​4. Check Wallet Positions

​5. Explain an Error

​Skills

Full Skills Guide

​Pre-built Prompts

​Decision Rules

​API Direct vs SDK Widgets

​Handling Swap Status

​Observability

​Next Steps

Skills Guide

Setup Guide

Tools Reference

Quickstart

When to Use What

Capabilities

Minimal Tool Set

1. Recommend Integration Path

2. Get a Swap Quote

3. Get Deposit Bytecode

4. Check Wallet Positions

5. Explain an Error

Skills

Pre-built Prompts

Decision Rules

API Direct vs SDK Widgets

Handling Swap Status

Observability

Next Steps