> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/gotts-safe-mcp-server/mcp-server/01-overview.md). # Overview and Goals > **Package**: `packages/safe/` (`@gotts.ai/safe`) | **Last Updated**: 2026-02-18 > > For market context and ecosystem data, see [shared/market-context.md](/docs/prd-shared/market-context.md). *** ## What This Is Gotts Safe is a production-grade Model Context Protocol server that gives any LLM, AI agent, or autonomous system complete, safe access to the Uniswap protocol across all deployed chains. It is a single server that combines on-chain data querying, trade execution, liquidity management, cross-chain intents, and a defense-in-depth safety system. The name "Safe" reflects that Gotts holds custody of agent wallets within the server. ## Why It Matters The AI agent ecosystem is growing rapidly. Agents need to interact with DeFi protocols, and Uniswap is the largest decentralized exchange by volume. Today, agents attempting to use Uniswap face a fragmented, unsafe landscape: * **Five community-built Gotts Safes** exist, all from the same author (kukapay), all low quality. The trading server requires raw private keys in environment variables with no simulation or safety guards. The data servers each cover a single narrow function. None use Uniswap's official Trading API or SDKs. * **GOAT SDK** has a Uniswap plugin, but it is swap-only with no data querying, LP management, or safety layers. * **No existing server** combines data + execution + safety in one package. Agents must compose 3-4 separate servers and still lack guardrails. Gotts Safe eliminates this fragmentation. It becomes the authoritative way for any AI agent to interact with Uniswap, with safety guarantees that prevent LLM hallucinations from causing fund loss. ## The Problem It Solves 1. **Fragmentation**: Agents currently need multiple MCP servers (price, pools, trading, positions) from untrusted sources. This server consolidates everything. 2. **Safety**: Existing servers have zero safety layers. An LLM that hallucinates a token address or amount can drain a wallet. This server makes every transaction pass through simulation, allowlists, spending limits, and hallucination detection before execution. The ClawHub incident (386 malicious skills) underscores that safety must be structural, not optional. 3. **Completeness**: No existing server supports LP management, V4 hooks, UniswapX, Permit2, or cross-chain intents. This server covers the full Uniswap protocol surface. 4. **Quality**: Existing servers bypass Uniswap's official SDKs and Trading API. This server is built on the canonical SDK stack, ensuring correct behavior across protocol versions. 5. **Agent Capital Markets Integration**: No existing server supports x402 payments, ERC-8004 agent identity, or agent-optimized access patterns. This server is designed for Agent Capital Markets from day one. ## Design Philosophy * **Full autonomy**: Agents are configured once (wallet, policies, allowlists) and operate independently. No human clicks, no manual approvals, no browser flows. * **Safety-first**: Every transaction is simulated before execution. Multiple independent safety layers ensure that no single failure can result in fund loss. * **Comprehensive**: One server replaces five community servers plus adds LP management, V4, UniswapX, cross-chain, and safety. * **Profile-based progressive disclosure**: One binary, one deployment, but the tool surface is controlled by a `TOOL_PROFILE` config. Agents that only need data get 18 tools; traders get 27; LP managers get 37; vault participants get 40. No agent is overwhelmed with 147 tools unless it asks for the `full` profile. Profiles are composable — `TOOL_PROFILE=trader,vault` activates both. See [02-architecture.md](/docs/gotts-safe-mcp-server/mcp-server/02-architecture.md) for the profile system. * **TypeScript-native**: Built on Uniswap's official TypeScript SDKs. Published as `@gotts.ai/safe` on npm. * **Wallet-agnostic**: Works with any viem-compatible account -- local keys, Privy, Safe, or custom signers. *** ## Goals | ID | Goal | Rationale | | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | G1 | Expose 60+ MCP tools covering data, historical data, token directory, protocol fees (TokenJar/Firepit), trading, LP, CCA/token launch, approvals, safety, utilities, real-time streams, and local testnet management | Complete protocol coverage in one server, including CCA participation, Liquidity Launcher, am-AMM, historical OHLCV, token metadata, protocol fees, streaming, and local testnet with V2/V3/V4 deployment | | G2 | Support all 11 Uniswap-deployed chains | Full chain parity | | G3 | Support Uniswap V2, V3, V4, UniswapX, and Universal Router | Full protocol version coverage | | G4 | Implement defense-in-depth safety: simulation, allowlists, spending limits, rate limiting, circuit breakers, nonce management, hallucination detection | Prevent fund loss from LLM errors | | G5 | Support 5 wallet types: local key, Privy, Safe, ZeroDev, generic viem Account | Cover all agent wallet patterns | | G6 | Achieve sub-2-second response for read operations, sub-5-second for quotes | Usable latency for interactive agents | | G7 | Publish as `@gotts.ai/safe` on npm | Standard distribution channel | | G8 | Expose via stdio, HTTP+SSE, and Streamable HTTP (WebSocket) MCP transports | Support local and remote deployment, plus real-time streaming for autonomous agents | | G9 | Provide a comprehensive configuration system via env vars and config file | Operator-controlled safety policies | | G10 | Cross-chain intent support via ERC-7683 | Uniswap-native competitive advantage | | G11 | x402 payment integration for pay-per-use access | Agent-native monetization without API keys. Agents pay per request in USDC on Base (\~200ms settlement). Eliminates onboarding friction. | | G12 | ERC-8004 agent identity awareness | Verified agents get lower fees, priority execution, reputation-gated pool access. Enables trust-tiered service levels. | | G13 | Agent treasury management tools | Self-funding agents need to auto-convert earned fees, rebalance treasuries, and manage operating capital through Uniswap | | G14 | Historical data: trade history, OHLCV candlesticks, and price charts | Agents making trading and LP decisions need historical context. No existing Gotts Safe provides candlestick data, historical prices, or trade history. | | G15 | Comprehensive token list with metadata (name, symbol, logo, price, pairs, verified status) | Agents need rich token information for discovery, verification, and presentation. Token logos and metadata enable agent UIs. | | G16 | Real-time streaming via WebSocket/SSE for prices, trades, LP events, and pool state changes | Autonomous agents (market makers, position monitors, arbitrage bots) need live data streams, not just request-response. MCP's Streamable HTTP transport enables this. | | G17 | CCA (Continuous Clearing Auction) participation tools: bid submission, clearing price monitoring, multi-bid management, token claiming | CCA is live on mainnet (Feb 2, 2026) and is the new standard for fair token launches. Agents need first-class CCA tooling. | | G18 | Liquidity Launcher integration for atomic token launch (create + distribute + CCA + V4 pool seeding) | Token launchers (Clanker, Flaunch) need atomic deployment pipelines. Agents deploying tokens need this end-to-end. | | G19 | am-AMM (Auction-Managed AMM) tools for Bunni v2 pool management bidding | am-AMM creates a direct revenue model for agents managing V4 pools via rent-based auctions. Key value prop for agent-managed vaults. | | G20 | Vault integration: compose seamlessly with `packages/vault/` Gotts Vaults tools for ERC-4626 vault operations | The vault protocol depends on core Gotts Safe tools for pool data, swaps, and LP. Shared safety pipeline enables defense-in-depth across both. | | G21 | Dual delivery: publish as both MCP server (`@gotts.ai/safe`) and Gotts Skills packages for maximum ecosystem reach | OpenClaw (188K+ GitHub stars, 5,705+ skills) has no native MCP support. Dual delivery ensures all agent frameworks can integrate. | | G22 | x402 outbound client for pay-per-use external data acquisition (CoinGecko, Elsa, future providers) | Agents need richer data than on-chain sources alone. x402 eliminates API key friction. CoinGecko covers 250+ networks and all DEXs. Elsa provides multi-chain portfolio analytics, wallet behavior analysis, yield discovery, and cross-DEX quotes. | | G23 | Evaluation and quality framework with per-tool unit tests, integration tests, regression detection, and quality gates per milestone | No existing Gotts Safe has quality assurance. Evaluation ensures reliability and catches regressions as the tool count grows. | | G24 | Intelligence tools: MEV risk scoring, IL calculation, venue comparison, token discovery with risk scoring, pool simulation, agent revenue tracking | Agents need analytical capabilities beyond raw data reads. Intelligence tools transform data into actionable insights for trading, LP, and treasury decisions. | ## Non-Goals | ID | Non-Goal | Reason | | ---- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NG1 | Building a hosted/managed service (Uniswap runs the server for agents) | Phase 1 is self-hosted. Hosted offering is a future consideration. | | NG2 | Supporting non-Uniswap DEXs (SushiSwap, Curve, etc.) | This is a Uniswap server. Agents can compose with other MCP servers for other protocols. | | NG3 | Building a frontend or UI | This is a headless server for programmatic access. | | NG4 | Implementing a custom routing algorithm | We use Uniswap's Trading API and smart-order-router for routing. | | NG5 | Supporting Solana or non-EVM chains | Uniswap is EVM-only. | | NG6 | Providing financial advice or automated trading strategies | The server executes what agents request. Strategy is the agent's responsibility. | | NG7 | KYC/AML compliance enforcement | Out of scope. Agents and their operators are responsible for compliance. | | NG8 | Deep analytics beyond subgraph/RPC capability (Dune-level custom queries, cross-protocol analytics, MEV analysis) | Use dedicated analytics MCP servers for Dune/Flipside queries. The server does provide subgraph-powered historical data (OHLCV, trade history, volume) per G14. | | NG9 | Smart contract deployment (V4 hooks, custom contracts) | Covered by companion skills/agents, not this MCP server. | | NG10 | Fiat on/off-ramp | Use a fiat on/off-ramp MCP server for fiat operations. | *** ## User Personas ### Persona 1: The Autonomous Trading Agent **Who**: An AI agent (built on ElizaOS, GOAT, OpenClaw, LangChain, or custom) that executes trades on Uniswap without human intervention. **Needs**: * Get real-time quotes across all chains * Execute swaps safely with pre-flight simulation * Check balances and manage approvals * Operate within configured spending limits * Recover gracefully from failed transactions **Example workflow**: "Swap 500 USDC for WETH on Base with max 0.5% slippage" results in quote, simulate, approve (if needed), execute, confirm -- all autonomously. ### Persona 2: The LP Management Agent **Who**: An autonomous agent that manages concentrated liquidity positions, rebalancing when prices move out of range. **Needs**: * Query pool state (current tick, liquidity distribution, fee APY) * Add and remove liquidity across V3 and V4 pools * Collect accrued fees * Monitor position health (in-range status, IL) * Discover new high-yield pools **Example workflow**: Agent detects position is 80% out of range, collects fees, removes liquidity, and opens a new position centered on the current price. ### Persona 3: The Agent Developer **Who**: A developer building an AI agent that interacts with Uniswap. Uses Claude Code, Cursor, or similar AI-assisted development tools. **Needs**: * Well-documented MCP tools with clear parameter types and return schemas * Predictable error handling (structured error codes, not opaque failures) * Easy local setup for development and testing * Configuration options for safety policies during development vs. production **Example workflow**: Developer configures Gotts Safe in their agent's MCP config, sets testnet chain + relaxed spending limits for development, then tightens policies for production deployment. ### Persona 4: The LLM (Claude, GPT, Gemini) with MCP Access **Who**: A general-purpose LLM connected to Gotts Safe, answering user questions about Uniswap or executing operations on their behalf. **Needs**: * Data tools that return LLM-friendly responses (formatted numbers, context, not raw hex) * Tool descriptions that are clear enough for the LLM to select the right tool * Safety tools that the LLM can invoke proactively (validate token before trading it) * Error messages that the LLM can interpret and explain to the user **Example workflow**: User asks "What's the best pool for WETH/USDC on Ethereum?" -- LLM calls `get_pools_by_token_pair`, interprets TVL/volume/fee data, and recommends a pool. ### Persona 5: The Self-Funding Agent **Who**: An autonomous agent (like BankrBot agents, CLAWD, Squaer Agent) that earns revenue from token trading fees, LP fees, or providing services to other agents via x402 — and uses Uniswap to manage its own treasury. **Needs**: * Auto-convert earned fees (in various tokens) to stablecoins or operating tokens * DCA strategies for converting volatile earnings to stable operating capital * LP into pools to generate additional yield on idle treasury funds * Track portfolio balance across chains and token types * Operate with strict spending limits to prevent treasury drain * Pay for MCP server access via x402 micropayments (no API key provisioning) **Example workflow**: Agent earns 0.5 ETH in token trading fees, auto-swaps 80% to USDC via Uniswap for compute costs, LPs the remaining 20% in ETH/USDC pool for yield. ### Persona 6: The Agent Token Deployer **Who**: An agent platform (like Clanker, BankrBot) that deploys tokens for other agents and needs automated pool creation and liquidity management on Uniswap V4. **Needs**: * Create Uniswap V4 pools with configurable hooks (anti-snipe, dynamic fees, revenue share) * Bootstrap initial liquidity for newly created tokens * Lock LP tokens for configurable durations * Query pool performance metrics for deployed tokens * Support vaulting and vesting patterns for agent tokens **Example workflow**: Agent platform deploys new token → creates Uniswap V4 pool with ClankerHook (2-block MEV protection) → provides initial liquidity → locks LP for 10 years → reports pool address and trading metrics. ### Persona 7: The Protocol Fee Searcher **Who**: An autonomous agent (bot) that monitors the TokenJar for accumulated protocol fees and executes profitable burn-and-claim transactions via the Firepit contract. Burns 4,000 UNI to claim assets worth significantly more. **Needs**: * Real-time monitoring of TokenJar balances across all fee sources (V2, V3, V4, UniswapX, Unichain native) * Profitability analysis: compare TokenJar value vs. UNI burn cost (threshold \* UNI price) * Optimal asset selection (top 20 assets by value from the jar) * Full execution pipeline: approve UNI → select assets → call Firepit.release() * Historical burn event analysis to time entries optimally * Fee accumulation rate tracking to predict next profitable burn window * Competitive awareness: monitor other searchers targeting the same jar **Example workflow**: Agent monitors TokenJar → detects $2.4M accumulated with 4,000 UNI threshold ($40K cost) → calculates $2.36M profit → approves UNI → selects top 20 assets → executes burn → receives assets → optionally swaps received tokens to stables via Uniswap. ### Persona 8: The Cross-Chain Agent **Who**: An agent that operates across multiple chains, moving assets and finding optimal execution venues. **Needs**: * Query data and execute on any of the 11 supported chains * Submit ERC-7683 cross-chain intents * Compare prices and liquidity across chains * Track cross-chain intent fulfillment status **Example workflow**: Agent finds WETH is cheaper on Arbitrum than Ethereum, submits an ERC-7683 intent to buy on Arbitrum and deliver to Ethereum.