Lagoon MCP Server

Model Context Protocol (MCP) server providing conversational access to Lagoon DeFi vault analytics through Claude, Codex, Cursor, and any other MCP-compatible client.

Overview

Lagoon MCP enables natural language queries about DeFi vaults, user portfolios, and performance metrics. Query vault data, analyze portfolios, and generate financial reports without writing GraphQL by hand.

Key features:

• Vault discovery — search and filter by asset, chain, TVL, and more
• Portfolio analysis — cross-chain aggregation with risk and performance metrics
• Performance tracking — historical metrics, OHLCV, and trend analysis
• Smart caching — tiered TTLs tuned to data volatility
• Type-safe — TypeScript types generated from the GraphQL schema
• Rich resources — schema introspection and a DeFi terminology guide
• Smart prompts — financial-analysis guidance with best practices

Quick Install

Prerequisites: Node.js ≥18.0.0. Pick your agent below and run the command.

claude mcp add --transport stdio \
  --env LAGOON_GRAPHQL_URL=https://api.lagoon.finance/query \
  lagoon -- npx -y @lagoon-protocol/lagoon-mcp

codex mcp add lagoon \
  --env LAGOON_GRAPHQL_URL=https://api.lagoon.finance/query \
  -- npx -y @lagoon-protocol/lagoon-mcp

[mcp_servers.lagoon]
command = "npx"
args = ["-y", "@lagoon-protocol/lagoon-mcp"]
env = { LAGOON_GRAPHQL_URL = "https://api.lagoon.finance/query" }

{
  "mcpServers": {
    "lagoon": {
      "command": "npx",
      "args": ["-y", "@lagoon-protocol/lagoon-mcp"],
      "env": { "LAGOON_GRAPHQL_URL": "https://api.lagoon.finance/query" }
    }
  }
}

How it works: ① Run the command. ② Your agent registers the MCP server. ③ Ask natural-language questions — e.g. "Find USDC vaults on Arbitrum with TVL > $1M."

Environment variables

Usage

"Show me my portfolio for wallet 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

"Find all USDC vaults on Arbitrum with more than $1M TVL"

"How has the lgUSDC vault on Arbitrum performed over the last 30 days?"

"What are the top 5 vaults by TVL across all chains?"

⚠️ Important Legal Disclaimer

THIS TOOL PROVIDES INFORMATIONAL CONTENT ONLY - NOT FINANCIAL ADVICE

Lagoon MCP is a data analysis tool that provides information about DeFi vaults. All analysis outputs are for educational and informational purposes only and should NOT be interpreted as:

• Financial, investment, legal, or tax advice
• Recommendations to buy, sell, hold, or trade any asset
• Guarantees of future performance or returns
• Professional financial guidance

Your Responsibilities

Before making ANY investment decisions:

1. Conduct Independent Research: Verify all data independently
2. Consult Professionals: Seek advice from qualified financial, legal, and tax advisors
3. Understand Risks: DeFi and cryptocurrency investments carry substantial risks including:
   • Complete loss of invested capital
   • Smart contract vulnerabilities
   • Market volatility and illiquidity
   • Regulatory uncertainty
4. Invest Responsibly: Only invest what you can afford to lose completely

No Warranties or Guarantees

We provide this software "AS IS" without warranties of any kind. We:

• Make no guarantees about data accuracy, completeness, or timeliness
• Accept no liability for investment losses or damages
• Do not endorse any specific vaults, protocols, or strategies
• Disclaim all responsibility for third-party platform performance

Past performance does not predict future results. Market conditions change rapidly.

Available Tools

Complete tool documentation in docs/tools/.

See also: Tool Selection Guide | Common Workflows

Quick Examples

Basic Vault Analysis

"Show me vault details for 0x1234... on Arbitrum"
→ Returns comprehensive vault data with current metrics

"How has this vault performed over the last 30 days?"
→ Returns TVL history, growth metrics, and trend analysis

Portfolio Management

"Analyze my portfolio at 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
→ Returns cross-chain positions sorted by USD value

"What's my total exposure to USDC vaults?"
→ Aggregates all USDC positions across chains

Advanced Analytics

"Compare these 3 vaults and tell me which has the best risk-adjusted returns"
→ Returns comparison table with rankings and metrics

"Analyze the risk profile for vault 0x1234..."
→ Returns multi-factor risk breakdown with insights

"Predict future yields for lgUSDC based on 90-day history"
→ Returns ML-based forecast with confidence intervals

Data Export & Reporting

"Export the top 10 vaults by TVL as CSV"
→ Returns formatted CSV data for spreadsheet analysis

"Get transaction history for vault 0x1234... and export as JSON"
→ Returns structured transaction data for external tools

Resources & Prompts

Resources

• GraphQL Schema (lagoon://graphql-schema) — full GraphQL schema in SDL format with 24-hour caching
• DeFi Glossary (lagoon://defi-glossary) — terminology guide for Lagoon DeFi Protocol (500+ lines)

Prompts

Prompts are self-explanatory templates invoked by name. See Prompt Guidelines for usage patterns.

Invoke prompts by name in your agent (e.g. "Use the financial-analysis prompt to evaluate this vault").

See also: Disclaimer Standards

Manual configuration

Quick Install covers the four most common agents. The snippets below are for clients without a mcp add CLI, or for users who prefer to edit config files directly.

{
  "mcpServers": {
    "lagoon": {
      "command": "npx",
      "args": ["-y", "@lagoon-protocol/lagoon-mcp"],
      "env": { "LAGOON_GRAPHQL_URL": "https://api.lagoon.finance/query" }
    }
  }
}

{
  "mcpServers": {
    "lagoon": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lagoon-protocol/lagoon-mcp"],
      "env": { "LAGOON_GRAPHQL_URL": "https://api.lagoon.finance/query" }
    }
  }
}

$schema: "https://raw.githubusercontent.com/lastmile-ai/mcp-agent/main/schema/mcp-agent.config.schema.json"
mcp:
  servers:
    lagoon:
      command: "npx"
      args: ["-y", "@lagoon-protocol/lagoon-mcp"]
      env:
        LAGOON_GRAPHQL_URL: "https://api.lagoon.finance/query"

Development

For gotchas, conventions, testing, and how to add a tool, see docs/agent-notes.md — the developer reference, also imported by CLAUDE.md.

Quick start

git clone https://github.com/hopperlabsxyz/lagoon-mcp.git
cd lagoon-mcp
npm install
npm run codegen    # generate types from the GraphQL schema (only after backend schema changes)
npm run build
npm run dev        # stdio, hot-reload
npm test

Project structure

lagoon-mcp/
├── docs/
│   ├── agent-notes.md          # Developer reference (gotchas, conventions, add-a-tool)
│   └── tools/                  # Individual tool documentation
├── skills/                     # Claude Skills for enhanced interactions
├── src/
│   ├── tools/                  # Tool implementations + registry.ts
│   ├── services/               # Business-logic services (e.g. RiskService)
│   ├── resources/              # MCP resources
│   ├── prompts/                # MCP prompts
│   ├── skills/                 # Skills TypeScript API
│   ├── graphql/                # GraphQL client, queries, fragments
│   ├── sdk/                    # APR, simulation, and math utilities
│   ├── core/                   # DI container, cache adapter, invalidation
│   ├── cache/                  # Cache TTL and key definitions
│   ├── schemas/                # Zod config/env schemas
│   ├── types/                  # TypeScript + generated GraphQL types
│   └── utils/                  # Utilities
├── tests/                      # Test suite
└── package.json

Architecture

System flow

┌─────────────┐         ┌──────────────┐           ┌─────────────┐
│   Agent     │ ◄─MCP──►│  Lagoon MCP  │◄─GraphQL─►│   Backend   │
│             │         │    Server    │           │     API     │
└─────────────┘         └──────────────┘           └─────────────┘
                              │
                              │ Cache + DI
                              ▼
                        ┌──────────────┐
                        │  Container   │
                        └──────────────┘
                        │   │        │
                   Cache  Client  Services

Patterns

• Hybrid service layer — direct GraphQL for simple tools; service layer (e.g. RiskService) for complex multi-step analytics.
• Dependency injection — ServiceContainer wires GraphQL client, cache, and config; tests inject a mock container.
• Type safety — GraphQL schema → TS via graphql-codegen; runtime input validation with Zod; strict TS compilation.

Caching strategy

Tiered TTLs optimized for data volatility:

Tag-based invalidation; automatic expiration via TTL; manual invalidation on data mutations.

Testing

• Vitest with multi-layer coverage: unit (mocked GraphQL), integration (real backend, optional), SDK (computation library).
• 80% coverage gate enforced via vitest thresholds.
• Cache hit-rate monitoring (target: 60–70%); ~300–800 tokens per query.

Quality

TypeScript strict mode · ESLint · Prettier · Vitest · Husky pre-commit hooks · Commitlint conventional commits.

Troubleshooting

Connection errors (Error: Request timeout) → Check LAGOON_GRAPHQL_URL and verify the backend is running.

GraphQL errors (Vault not found) → Verify vault address and chain ID. Use the query_graphql tool to test raw queries.

Stale cache data → Cache TTLs are conservative. Restart the MCP server to clear cache, or wait for TTL expiration.

Type errors after schema update (Type 'unknown' is not assignable to type 'Vault') → Run npm run codegen to regenerate types from the updated schema.

FAQ

Which clients does this work with? Any MCP-compatible client. Verified with Claude Code, Claude Desktop, Codex, Cursor, and the OpenAI Agents SDK; works with other MCP clients (Cline, Continue, …) since it uses the standard stdio transport.

Do I need to modify the code for different platforms? No. The server uses the standard MCP protocol over stdio. Only the per-client config syntax differs — covered in Quick Install and Manual configuration.

Is there a rate limit? No rate limiting in the MCP itself. The Lagoon GraphQL backend is public, no auth.

Can I add custom tools? Yes — fork the repo, add your tool in src/tools/, and register it in TOOL_REGISTRY in src/tools/registry.ts. See docs/agent-notes.md.

How do I update to a new version? npx -y @lagoon-protocol/lagoon-mcp always pulls the latest published version. If you used the legacy global install, run npm update -g @lagoon-protocol/lagoon-mcp.

Does this work with all chains? Yes — all chains available in the Lagoon backend (12+ networks).

License

MIT — see LICENSE.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Tool Docs · Developer Reference
• Release history: CHANGELOG.md

Acknowledgments

• Built with Model Context Protocol
• Powered by Anthropic Claude
• GraphQL backend by the Lagoon Team

Made with ❤️ for the Lagoon DeFi community