Skip to main content
Glama

keel-mcp

npm MCP Registry

A Model Context Protocol server for Keel, the liquidity risk engine for Stellar. It lets an AI agent (Claude Desktop, Claude Code, Cursor, or any MCP client) answer questions like these with Keel's own numbers:

  • "Is USTRY safe as collateral for a 500,000 USDC loan?"

  • "How much AQUA can I sell before the price drops more than 5%?"

  • "Which monitored assets are CRITICAL right now, and why?"

  • "What did Keel see at ledger 61340263, the Blend exploit?"

An oracle answers what is the price. Keel answers what volume can that price actually support: executable depth from the SDEX order book and AMM pools at +/-2%, 5% and 10%, and the largest collateral position that liquidity can safely back. This server exposes those figures to agents. It reads the public API at https://api.keels.app/v1; the dashboard is at keels.app.

Install

Requires Node.js 20 or newer.

Claude Code

claude mcp add keel -- npx -y @keel-official/mcp

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "keel": {
      "command": "npx",
      "args": ["-y", "@keel-official/mcp"]
    }
  }
}

From a checkout, to run unreleased changes:

npm install && npm run build
claude mcp add keel -- node /absolute/path/to/keel-mcp/dist/index.js

Configuration

Variable

Default

Purpose

KEEL_API_URL

https://api.keels.app/v1

Point at another deployment, or at the contract mock (http://localhost:4010)

KEEL_TIMEOUT_MS

15000

Per request timeout, for the Keel API and for each Soroban RPC step of audit_blend_pool

KEEL_CACHE_TTL_MS

60000

Cache for the asset list and methodology. Scans run every 15 minutes

KEEL_SOROBAN_RPC_URL

https://mainnet.sorobanrpc.com

Soroban RPC used by audit_blend_pool to read Blend pools

Related MCP server: aster-agent-gateway

Tools

Every tool is read-only and returns two things: a short text answer for the model, and the exact figures as structured JSON. Every answer carries its provenance: ledger sequence, ledger close time, data source, methodology version, and how far behind the latest ledger the data is.

Tool

Answers

keel_status

Is the engine healthy, which ledger was scanned last, how many assets are monitored

list_assets

Monitored assets with band, confidence, max safe collateral and flags. Filter by band or hasFlag

find_asset

Resolves a code (USDY) to its CODE:ISSUER ids. Returns every issuer and picks none

get_asset_risk

The full reading for one asset, or a historical reconstruction with ledger

check_collateral_size

within, exceeds or unknown for a proposed collateral amount, the ratio, and which limit binds

estimate_trade_depth

Which measured rung (2%, 5%, 10%) absorbs a buy or sell size, or that it exceeds them all

get_risk_history

Band, depth and collateral over a ledger window or every stored reading of one source, with band changes

compare_assets

2 to 10 assets side by side

get_methodology

Methodology version, every threshold, and the calibration note

audit_blend_pool

A Blend lending pool's collateral caps and current supply set beside Keel's safe size for each asset (see below)

Resources: keel://methodology (JSON) and keel://report/blend-february-2026, the open backtest report on the February 2026 Blend incident.

Prompt: assess_collateral(assetId, amount, protocol?) runs the tools in order and asks for an answer that states the verdict, the binding limit, the band and its confidence, every unevaluated flag, and the provenance.

Blend Pool Cap Audit

audit_blend_pool (and npm run audit:blend, which writes a markdown and a JSON report to reports/) reads a Blend V2 lending pool from Stellar: every reserve's collateral factor, supply cap, total supplied and total borrowed, and the pool oracle's price. For each reserve that can back a loan it converts the supply cap (what the pool is configured to accept) and the total supplied (what it holds now) to USDC at Keel's executable price, and sets both beside Keel's maxSafeCollateral.

Per reserve it answers supplied_exceeds, cap_exceeds, within, unknown, not_monitored or not_collateral (collateral factor 0 or disabled), plus the gap between the Blend oracle price and Keel's executable price.

Three things to know when reading it, and every report prints them:

  1. Keel's safe size is defined for ONE collateral position. Reading a whole reserve against it is the natural reading for liquidations (they all sell into the same book) and a conservative one for manipulation (an attacker controls one position).

  2. Keel measures liquidity on Stellar only. XLM, with deep centralized-exchange markets, reads as far riskier here than its whole market is. "Exceeds" means "exceeds what Stellar itself can absorb", which is what an on-chain liquidation depends on.

  3. It is a comparison with published figures, not a recommended cap. Keel computes no cap of its own.

Known pools: YieldBlox and Fixed (Blend V2 mainnet). Any other pool can be passed by contract id.

Example

You: Is USTRY safe as collateral for a 500,000 USDC loan on Blend?

Agent (calls find_asset, get_asset_risk, check_collateral_size): No. 500,000 USDC is 7.23x Keel's recommended maximum of 69,120.49 USDC for USTRY:GCRY...MYWC. The binding limit is manipulation: pushing the price to the critical level through the order book caps the size well below the liquidation limit (133,252.90). USTRY is in band HIGH with partial confidence, so the band is a floor: HOLDER_CONCENTRATION_EXTREME fired (the largest holder has 91.46%), and NO_GENUINE_TRADE_30D, NO_GENUINE_TRADE_7D and WASH_TRADE_SUSPECTED could not be evaluated. Ledger 64657818, methodology 1.0.8-draft. Keel's thresholds are chosen, not calibrated.

(Figures from the live API on 28 September 2026. Yours will differ.)

How it keeps answers honest

These rules come from Keel's engine and are enforced here as well:

  1. An asset is CODE:ISSUER, never a ticker. Several issuers publish USDY. find_asset returns all of them and the agent is told to ask.

  2. Provenance on every answer. Ledger and methodology version travel with every number, so anything an agent says can be checked against the API.

  3. Unknown is not safe. A figure the engine could not compute is reported with the reason Keel gives, never as zero. check_collateral_size answers unknown rather than guessing.

  4. Unevaluated is not clear. Flags that could not be checked are listed as such, and a partial band is described as a floor.

  5. No new methodology. The server compares an amount with figures the engine published. estimate_trade_depth gives a bracket between measured rungs, not an interpolated point, because the methodology defines no interpolation.

  6. Exact decimals. Every monetary comparison uses decimal.js, never floating point.

What this server will never do

  • Sign or submit a transaction, or hold a key. Keel is permanently read-only. The Keel API is read with GET only, and the test suite fails if src/ issues anything else. Blend pools are read through Soroban RPC with getLedgerEntries, and oracle prices with simulateTransaction on an unsigned, never-submitted transaction, which is how a Soroban contract is read.

  • Publish a price feed or act as an oracle.

  • Send alerts, webhooks or notifications.

  • Make a credit or investment decision. It reports liquidity; the lender decides.

Development

npm install
npm run typecheck
npm test
npm run build
npm run inspect          # MCP Inspector against the built server

The API types in src/api/schema.d.ts are generated from openapi/keel-openapi.yaml, a copy of the contract in keel-backend. Refresh both with npm run sync:contract (it expects ../keel-backend, or pass a path). A test fails when the copied contract's version differs from keel.contractVersion in package.json, so drift is visible rather than silent.

Releasing

Releases run in GitHub Actions (.github/workflows/publish.yml), which publishes the npm package with provenance and then publishes server.json to the MCP Registry through GitHub OIDC. The registry grants io.github.Keel-Official/* to workflows in this repository, so no personal login or OAuth approval is involved.

  1. Bump version in package.json, both version fields in server.json, and SERVER_VERSION in src/server.ts. A test fails if they disagree.

  2. Commit, then git tag vX.Y.Z && git push origin vX.Y.Z.

The workflow needs a repository secret NPM_TOKEN (granular token, publish access to @keel-official). Both publish steps skip a version that already exists, so a manual Run workflow is always safe to repeat.

License

MIT

Available Tools

10 tools
audit_blend_poolAudit a Blend lending pool against KeelA
Read-onlyIdempotent

Reads a Blend V2 pool's collateral configuration from Stellar (collateral factor, supply cap, total supplied, oracle price) and sets each collateral reserve beside Keel's maximum safe collateral size for that asset. Says per reserve whether what the pool HOLDS and what it would ACCEPT exceed what Stellar liquidity can absorb. Omit pool to audit every known pool (YieldBlox, Fixed). Read-only; state the interpretation notes with any conclusion.

Inputs: pool, withOraclePrices.

check_collateral_sizeCheck a collateral size against KeelA
Read-onlyIdempotent

Compares a proposed collateral amount with Keel's recommended maximum safe collateral size for the asset, and says which limit binds: liquidation (the book cannot absorb a forced sale) or manipulation (pushing the price up is cheaper than the loan it would unlock). Answers within, exceeds, or unknown. Unknown is not safe and not unsafe. This is a comparison with published figures, not a credit decision.

Inputs: amount (required), assetId (required), quote.

compare_assetsCompare Stellar assets side by sideA
Read-onlyIdempotent

Side-by-side comparison of 2 to 10 assets: band and confidence, max safe collateral, depth at 5% on both sides, and fired flags, each with its own ledger. Useful for choosing between collateral candidates. Figures are all in USDC.

Inputs: assetIds (required).

estimate_trade_depthPrice impact bracket for a trade sizeA
Read-onlyIdempotent

For traders and market makers: places a buy or sell size (in the quote asset, USDC) between the measured rungs of Keel's depth ladder, answering 'this moves the price by at most 2% / 5% / 10%' or 'this exceeds the measured depth'. It is a bracket, never a point estimate, because the methodology defines no interpolation between rungs. Depth combines the SDEX order book and AMM pools.

Inputs: side (required), amount (required), assetId (required), quote.

find_assetFind a Keel asset id by codeA
Read-onlyIdempotent

Resolves an asset code such as USDY or AQUA to the full CODE:ISSUER ids Keel monitors. When one code has several issuers, ALL of them are returned and none is chosen: ask the user which issuer they mean rather than picking one, because the same ticker from a different issuer is a different asset.

Inputs: code (required), issuer.

get_asset_riskLiquidity risk of a Stellar assetA
Read-onlyIdempotent

The full Keel risk reading for one asset: risk band and its confidence, fired and unevaluated flags, executable depth at +/-2%, 5% and 10% (SDEX order book plus AMM pools), recommended maximum safe collateral size with its liquidation and manipulation terms, holder concentration, volume to supply, and the last genuine trade. Pass ledger to read a historical reconstruction instead of the latest scan. Always quote the provenance line with the numbers.

Inputs: assetId (required), quote, ledger.

get_methodologyKeel methodology and thresholdsA
Read-onlyIdempotent

The methodology version and every threshold Keel uses to fire flags and size collateral, with the link to the full documentation. The thresholds are chosen, not calibrated against a set of incidents; mention that when explaining why an asset got its band.

Inputs: no named parameters.

get_risk_historyRisk history of a Stellar assetA
Read-onlyIdempotent

A time series of band, flags, depth and max safe collateral for one asset, from ONE data source. Give from and to (ledger sequences, at most 90 days apart) for a window, or omit both to list every stored reading of that source. Reconstructions such as the February 2026 USTRY series live under source offers-implied and are reachable only with both bounds omitted. Band changes are summarised.

Inputs: assetId (required), to, from, limit, +3 more.

keel_statusKeel service statusA
Read-onlyIdempotent

Whether the Keel engine is healthy, the ledger of its latest scan, how many Stellar assets it monitors, and the methodology version its numbers follow. Call this first when freshness matters.

Inputs: no named parameters.

list_assetsList monitored Stellar assetsA
Read-onlyIdempotent

Lists the Stellar assets Keel monitors with their risk band, band confidence, recommended maximum safe collateral size (USDC) and fired flags. Filter by band (e.g. CRITICAL) or by a single flag (e.g. MANIPULATION_CHEAP) to find risky collateral.

Inputs: band, limit, offset, hasFlag.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: discovery (find_asset, list_assets), single-asset detail (get_asset_risk), time series (get_risk_history), comparison (compare_assets), depth bracketing (estimate_trade_depth), and collateral sizing (check_collateral_size). The closest overlaps are find_asset vs list_assets (code resolution vs. risk-filtered listing) and estimate_trade_depth vs check_collateral_size, but the descriptions make the boundary clear.

    Naming Consistency4/5

    Nine of ten tools follow a clean verb_noun pattern (find_asset, get_asset_risk, list_assets, check_collateral_size, estimate_trade_depth, get_risk_history, compare_assets, audit_blend_pool, get_methodology). keel_status breaks the pattern as a server-prefixed noun and is the only deviation.

    Tool Count5/5

    Ten tools is well within the ideal 3-15 range and each earns its place: status, methodology, discovery, per-asset risk, history, comparison, two sizing/depth helpers, and a pool audit. No redundant filler.

    Completeness4/5

    Covers the full read lifecycle for Stellar asset risk: resolution, listing, detail, history, comparison, collateral sizing, depth estimation, plus blend pool auditing and methodology/status metadata. Minor gaps: no enumeration of available flags or bands, no watchlist/alerting, and no portfolio-level aggregate exposure, though agents can work around these via existing tools.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents read-only, keyless access to Hyperliquid market data, funding rates, account risk, and HyperEVM token transfers through MCP tools, with caching and rate limiting to protect upstream APIs.
      12
      85 PyPI
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents read-only, keyless access to Aster DEX data, including futures and spot markets, TradFi perpetuals, funding rates, order books, klines, vault deposit flows, and account views through MCP tools.
      13
      71 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Equips AI agents with institutional risk management and execution tools for Solana and Hyperliquid, enabling Kelly-criterion position sizing, VaR/CVaR analysis, Monte Carlo simulations, circuit breaker checks, and wallet/funding data queries through standardized MCP tools.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to query Keel's Stellar liquidity risk engine for executable order-book and AMM depth, maximum safe collateral sizes, asset risk bands, flags, and historical readings, with ledger and methodology provenance on every answer. All tools are read-only, so agents can assess collateral and trade depth without signing or submitting transactions.
      9
      7 npm
      MIT