Philidor DeFi Vault Risk Analytics

Key material

Philidor never accepts keys. Never send private keys, session keys, seeds, or mnemonics to any Philidor API or MCP input. Inputs carrying key material receive a structured refusal before tool, prompt, or resource handlers run. The API and MCP return data only; they do not build, sign, or broadcast transactions. Keys and execution stay in the client-side SDK.

A 32-byte pool identifier and a private key can have the same shape. Documented identifier fields still accept exact identifiers; never paste a key into them.

Why Philidor?

Most DeFi data tools give you raw numbers. Philidor gives your AI agent institutional-grade risk intelligence.

Quick Start

Remote Server (Recommended)

Connect directly to the hosted server — zero installation, always up to date:

https://mcp.philidor.io/api/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{  "mcpServers": {    "philidor": {      "url": "https://mcp.philidor.io/api/mcp"    }  }}

Claude Code

claude mcp add philidor --transport http https://mcp.philidor.io/api/mcp

Cursor

Add to .cursor/mcp.json:

{  "mcpServers": {    "philidor": {      "url": "https://mcp.philidor.io/api/mcp"    }  }}

Windsurf

Add to your MCP settings:

{  "mcpServers": {    "philidor": {      "serverUrl": "https://mcp.philidor.io/api/mcp"    }  }}

Docker (stdio)

docker run -i --rm ghcr.io/philidor-labs/philidor-mcp

Local (stdio)

git clone https://github.com/Philidor-Labs/philidor-mcp.gitcd philidor-mcpnpm installnpm start

Tools

15 standalone tools for vault discovery, risk analysis, lending markets, loop venue checks, policy attestations, and protocol research.

check_policy

Check positions against your own limits and constraints. Returns the API's compliance attestation: compliance, violations, policy_hash, findings, and snapshotId. With issue: true, an issued attestation also includes attestation_id, signerAddress, and verification_url (GET /v1/graph/attestation/{id}/verify). No risk figures are recalculated. Missing, malformed, or partial responses produce an error. The legacy verdict appears only as deprecated_verdict; use compliance.

For local stdio/Docker, set PHILIDOR_API_KEY in the server process environment to your Philidor API credential. Keep it out of tool arguments, chat, and source control. This is not a wallet key. Without an eligible key the tool returns a structured refusal with the API's required plan, x402 price (when available), and upgrade link. It does not pay automatically. The hosted plugin uses its own documented client authentication.

No Philidor policy is preselected. This reports conformity with your policy; it does not recommend a vault. Philidor does not prepare transactions and never accepts wallet keys. Execution stays in the client-side SDK.

search_vaults

Search and filter DeFi vaults by chain, protocol, asset, risk tier, TVL, and more.

get_vault

Get detailed information about a specific vault including risk breakdown, recent events, and historical snapshots. Lookup by id or by network + address.

get_vault_risk_breakdown

Detailed breakdown of a vault's four risk vectors: Asset Composition, Platform and Strategy, Control and Governance, and History.

list_markets

List lending markets (Aave/Spark pools, Aave V4 spokes, Compound Comet, Morpho Blue pairs, Kamino K-Lend). Aave V4 spokes that share a liquidity hub are grouped under composed hub parents (e.g. aave-v4-1-hub-core).

get_market

One market with every reserve (supplied, supply APR, borrowed, borrow APR, utilization, tier). Accepts spoke ids and composed hub ids.

get_market_events

Published risk events for one lending market. Hub ids union spoke feeds.

check_loop_venue

Underwrite a collateral/debt loop on one market: score, tier, utilization, borrow APR, deposit status, and recent incidents for both legs. Does not compute health factor and does not prepare transactions.

compare_vaults

Side-by-side comparison of 2–3 vaults on TVL, APR, risk score, risk tier, and audit status.

find_safest_vaults

Find the top 10 audited vaults sorted by Philidor risk score (higher = lower assessed risk; not a safety guarantee).

get_protocol_info

Protocol details including TVL, vault count, versions, auditors, bug bounties, and security incidents.

get_curator_info

Curator details including managed vaults, TVL, chain distribution, and performance metrics.

get_market_overview

High-level DeFi vault market statistics: total TVL, vault count, risk distribution, and TVL by protocol. No parameters required.

explain_risk_score

Explain what a specific risk score means, including the tier, calculation method, and thresholds.

list_vaults_with_incidents

List all vaults that had a recent critical incident (last 365 days). Sorted by TVL descending, then by recency. No parameters required.

Resources

Prompts

Example Prompts

Once connected, try asking your AI assistant:

Discovery

"Find the safest USDC vaults with at least $10M TVL"

"What Morpho vaults are available on Base?"

"Show me the DeFi market overview"

Analysis

"Run due diligence on the Steakhouse USDC vault on Ethereum"

"Compare the top 3 USDC vaults by risk score"

"What's the risk breakdown for this vault: ethereum/0x..."

Portfolio

"Assess my portfolio: 50% in Morpho Steakhouse USDC, 30% in Aave USDC, 20% in Yearn USDC"

"Which protocols have had security incidents?"

"What does a risk score of 8.5 mean?"

Risk Scoring

Philidor uses the Vector Risk Framework v4.1 to decompose vault risk into three measurable vectors:

Final Score = 40% Asset + 40% Platform + 20% Governance

Asset Composition (40%)

Quality of underlying collateral. Blue-chip assets (ETH, USDC) score highest. Factors include oracle reliability, liquidity depth, and peg stability.

Platform Code (40%)

Code maturity measured by:

• Lindy Score — time-based safety (>2 years ≈ 9/10)
• Audit Density — number and quality of audits
• Dependency Risk — multiplicative penalties for risky dependencies
• Incident Penalty — caps score after security incidents

Governance (20%)

Exit window for users:

Risk Tiers

Architecture

┌──────────────────┐     ┌─────────────────┐     ┌──────────────┐│  Claude / Cursor  │────▶│  Philidor MCP   │────▶│ Philidor API ││  Windsurf / etc.  │◀────│  Server         │◀────│              │└──────────────────┘     └─────────────────┘     └──────┬───────┘                          15 tools, 3 resources,         │                          4 prompts                      │                                                   ┌────▼────┐                                                   │ On-chain │                                                   │  data    │                                                   └─────────┘

• Transport: Streamable HTTP (remote) or stdio (local/Docker)
• API: Calls the Philidor Public API — public analytics need no API key; policy attestations require an eligible API plan
• Stateless: Fresh server instance per request, no session state
• Data: 700+ vaults across Ethereum, Base, Arbitrum, Polygon, Optimism, and Avalanche

Cursor Marketplace Plugin

This repository packages a Cursor plugin that connects the agent to the hosted Philidor MCP server and loads five workflow skills. The plugin does not embed an API key. Philidor stays read-only: it scores vaults and lending venues, and it does not compute a health factor or prepare a transaction.

The plugin points at the hosted server, which is ahead of the stdio server in this repo:

https://mcp.philidor.io/api/mcp

Transport is Streamable HTTP. The hosted server has additional tools beyond this standalone client; use tools/list to discover the current surface. src/server.ts registers 15 standalone tools, 3 resources (philidor://methodology, philidor://supported-chains, philidor://supported-protocols), and 4 prompts (vault_due_diligence, portfolio_risk_assessment, defi_yield_comparison, review_loop_venue).

Product page: philidor.io/mcp. Docs: MCP server, quickstart, tools, resources, prompts.

Install

After the plugin is listed, open Customize in Cursor, find Philidor, and choose Install (project or user scope). That loads the skills and the hosted MCP server together.

Until then, connect the same server without the plugin by adding this to .cursor/mcp.json:

{  "mcpServers": {    "philidor": {      "url": "https://mcp.philidor.io/api/mcp"    }  }}

To try the plugin from a local checkout, copy this repo to ~/.cursor/plugins/local/philidor (the folder must contain .cursor-plugin/plugin.json), then run Developer: Reload Window and confirm the skills and MCP server under Customize. Local plugin imports have to be allowed. A marketplace plugin with the same name takes precedence over the local copy.

Example prompts

• "Run due diligence on the Gauntlet USDC vault on Ethereum."
• "Which Prime USDC vaults on Ethereum still accept deposits, and how do their scores compare to APR?"
• "Check looping weETH against USDC on Aave V4 Ethereum Main before I borrow."
• "List the largest Aave V4 markets by supplied value and any recent events on the one I pick."
• "Which vaults had a critical incident in the last year?"
• "I need basket constituents and the oracle freshness feed. Is that on the free MCP or the API?"

Skills tell the agent to copy vault ids, network slugs, addresses, and market ids from tool results, and not to invent risk numbers. Loop checks call check_loop_venue, then stop. Health factor and unsigned transactions belong to the protocol MCP (Aave is https://mcp.aave.com). Baskets, oracle vectors, enriched assets, the event stream, and Risk Graph look-through are outside the free MCP. The philidor-api-handoff skill sends those questions to API Access and Plans and pricing without quoting a price.

Submission checklist

Do not submit from this fork until a reviewer accepts the pull request. Listing is a manual review at cursor.com/marketplace/publish. The repository must be public. Cursor reviews the open-source tree and each later update.

• .cursor-plugin/plugin.json parses and matches the plugin schema (name philidor, lowercase kebab-case)
• description states that the plugin is read-only vault and market risk analytics
• mcp.json is the only MCP connector and has no auth header
• Each skill directory has a SKILL.md whose name matches the folder and whose description says when to use it
• assets/logo.svg is committed and logo is the relative path assets/logo.svg
• Manifest paths are relative and exist (skills/..., ./mcp.json). No .., no absolute paths
• No ${VAR} placeholders, so variables stays unset
• README (this section) documents install and example prompts
• Live check: initialize and tools/list against https://mcp.philidor.io/api/mcp still succeed
• Tried locally from ~/.cursor/plugins/local/philidor (Customize shows 5 skills and the Philidor MCP server)
• Submit the public GitHub URL at cursor.com/marketplace/publish. This repo is a single plugin indexed by .cursor-plugin/marketplace.json with source "."

Agent Skill

Install the Philidor MCP skill into your coding agent via skills.sh:

npx skills add philidor-labs/philidor-mcp

This gives your agent full knowledge of all tools, resources, prompts, recommended workflows, and best practices for DeFi vault analysis.

Also Available

Supported Protocols

Morpho, Aave (v3/v4), Spark, Compound, Yearn, Beefy, Uniswap, Nest, Maple, Kamino — with more being added regularly.

See the full list at app.philidor.io.

Development

git clone https://github.com/Philidor-Labs/philidor-mcp.gitcd philidor-mcpnpm installnpm start

The server connects to the public Philidor API by default. To use a custom endpoint:

PHILIDOR_API_URL=http://localhost:3003 npm start

Links

• Philidor MCP landing — hosted server overview
• MCP docs — tools, resources, and prompts
• Philidor Analytics — explore vaults and risk scores
• Philidor CLI — terminal-based vault intelligence
• API Documentation — OpenAPI/Swagger docs
• Risk Methodology — how scores are calculated
• Smithery — MCP server registry
• Twitter — updates and announcements

License

MIT