Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

USDD Skills

AI Agent skills for the USDD stablecoin protocol. This package teaches agents how to query public analytics, inspect wallet-aware protocol state, and safely route Vault, PSM, and Earn writes through the official USDD MCP server.

This page describes the published USDD Skills package and its companion MCP server:

USDD Skills is a Skills + MCP/CLI hybrid package. It ships 4 Agent Skills, a local read-only analytics MCP server, CLI access to the same analytics layer, and install helpers for common MCP clients.

Overview

What it is

USDD Skills provides structured instructions for agents using USDD across two MCP servers:

  • Analytics MCP from this package: 14 read-only tools backed by public openapi.usdd.io endpoints.

  • Official MCP from @usdd/mcp-server-usdd: wallet/network state, protocol reads, Vault/PSM/Savings writes, token transfers, treasury, and Smart Allocator tools.

The local analytics MCP never signs transactions and does not hold private keys. All write-capable workflows are delegated to the official MCP.

Who it is for

  • Web3 users who want agent-assisted Vault, PSM, or Earn workflows.

  • Analysts who need public USDD supply, APY, collateral, and Smart Allocator data.

  • Agent and tooling builders integrating USDD into Claude Desktop, Claude Code, Cursor, Codex, project-level MCP configs, or compatible MCP hosts.

When not to use it

  • Do not use it for unattended trading, liquidation bots, or automated transaction execution. Write skills require a fresh chat confirmation after prechecks.

  • Do not use public analytics output as an oracle or settlement source. Analytics data is informational.

  • Do not use this package to store or pass private keys. Wallet handling belongs to the official MCP and wallet tooling.

  • Do not guess protocol addresses from docs or local tables. The skills require Chainlog-backed official MCP resolution.

Which Mode to Use

You want to…
Use
Reason

Compare Earn APY, supply, sUSDD supply, collateral history, public overview, Smart Allocator detail

Local Analytics MCP

Public, read-only, no wallet required

Run the same public analytics in a terminal or CI

CLI scripts/usdd_api.mjs

Scriptable JSON output, no agent required

Read wallet balance, allowance, wallet address, Vault ownership, PSM status, Savings status

Official MCP

Requires live chain, wallet-aware, or current protocol state

Open/manage Vaults, swap through PSM, deposit/withdraw Savings

Official MCP via Skill workflow

Holds wallet context and performs writes

Transfer tokens

Official MCP token-transfer flow

Uses prepare_token_transfer -> user confirmation -> confirm_token_transfer

Rule of thumb:

  • Public dashboard analytics -> local analytics MCP or CLI.

  • Wallet, current chain state, addresses, allowances, and all writes -> official MCP.

Architecture

Two MCP servers are intentionally non-overlapping.

Server
Package/source
Role
Writes?

usdd-analytics

This package, scripts/mcp_server.mjs

14 read-only tools over public USDD API

No

usdd-full

@usdd/mcp-server-usdd

Wallet/network state, on-chain reads, Vault/PSM/Savings writes, treasury, Smart Allocator

Yes

Agents must call the MCP tools. Skill workflows explicitly say not to fetch upstream API URLs directly.

Requirements

Requirement
Actual package behavior

Node.js

Required >=20.0.0; setup rejects older Node versions

Package version

@usdd/usdd-skills version 1.0.0

Official MCP

@usdd/mcp-server-usdd is installed by setup unless skipped

Local analytics dependencies

@modelcontextprotocol/sdk, dotenv

Public analytics auth

No API key required for the wrapped public analytics endpoints

RPC env keys

Optional keys are passed only to usdd-full: TRONGRID_API_KEY, TRON_FULL_NODE, TRON_NILE_FULL_NODE, ETH_RPC_URL, ETH_SEPOLIA_RPC_URL, BSC_RPC_URL, BSC_TESTNET_RPC_URL

Supported official MCP networks

tron, eth, bsc, tron_nile, eth_sepolia, bsc_testnet

Local analytics chain args

tron, eth, bsc for chain-scoped analytics tools

Local analytics history intervals

WEEKLY, MONTHLY, BIANNUAL, ANNUAL

The local analytics MCP does not use a NETWORK value. Network selection for official MCP tools is passed in tool arguments as network.

Installation

Recommended setup

The CLI exposes:

Recommended GitHub package setup:

Current setup behavior:

  • Checks Node.js v20+.

  • Installs global usdd-skills and @usdd/mcp-server-usdd, unless --skip-global-install or --dry-run is used.

  • Writes MCP config for selected clients with timestamped backups.

  • Creates a skills symlink at ~/.agents/skills/usdd-skills.

  • Registers:

    • usdd-analytics -> usdd-skills mcp-server

    • usdd-full -> mcp-server-usdd

Supported setup clients:

The special values are:

  • auto: detect project plus existing Claude Desktop, Cursor, and Codex config locations.

  • all: configure project, claude-desktop, cursor, and codex.

Dry run

Use dry run to inspect planned config writes without changing files:

Local checkout setup

Actual install.sh behavior:

  • Checks Node.js v20+.

  • Runs npm install.

  • Installs global @usdd/mcp-server-usdd.

  • Creates .env from .env.example if missing.

  • Runs node bin/usdd-skills.mjs setup --local-source --skip-global-install --yes.

For project config with local source, setup writes a portable .mcp.json using node plus a relative ./scripts/mcp_server.mjs path. User-level client configs use the current Node executable plus an absolute analytics script path.

Verify

Expected:

  • usdd-skills list-tools prints the 14 analytics MCP tools.

  • CLI commands print JSON on stdout.

  • Tests run with node --test scripts/*.test.mjs.

Upgrade

For a local checkout, update the checkout first, then rerun bash install.sh.

Uninstall

The included uninstall.sh is intentionally narrow:

It must be run from the @usdd/usdd-skills project root. It removes local node_modules and .env, then prints that full removal requires deleting the directory.

To remove a user-level install, remove the skills symlink and uninstall the global packages:

Also remove usdd-analytics and usdd-full from any MCP client configs that were configured.

Client Configuration

Both MCP servers use stdio transport. After editing client config, fully restart the client.

Project-local .mcp.json

The portable template is:

Generated local .mcp.json files should not be committed.

Claude Desktop

Config path on macOS:

Minimal config shape:

Claude Code

Cursor

Setup writes or merges:

Use the same mcpServers shape as Claude Desktop.

Codex

Setup writes or merges:

Recommended:

Manual config shape is the same two-server mcpServers block shown above. Restart Codex after editing config.

Verify:

The skills directory should contain:

OpenCode

The package includes an OpenCode plugin shim at:

That shim registers the 4 skills and the local usdd-analytics MCP server with:

The setup installer currently supports project, claude-desktop, cursor, and codex clients. It does not list opencode as a setup client option.

PATH fallback

If a desktop client cannot find usdd-skills or mcp-server-usdd, use an absolute command path or run local-source setup so the analytics MCP uses the current Node executable and an absolute script path for user-level configs.

Skill Catalog

Skill
Scope
Writes?
Primary MCP dependency

usdd-vault-v1

Vault/CDP: open, deposit, mint, repay, withdraw, close, risk review

Yes

Official MCP

usdd-psm-v1

PSM stablecoin <-> USDD swaps

Yes

Official MCP

usdd-earn-v1

Savings: deposit USDD -> sUSDD, withdraw USDD from sUSDD

Yes

Official MCP plus local analytics for APY/supply

usdd-analytics-v1

Public read-only analytics and routing

No

Local analytics MCP, official MCP for current wallet-aware state

Global routing rules

  • Chain-dependent official MCP work requires an explicit network before any MCP tool call.

  • Never default to TRON, mainnet, testnet, set_network, get_network, or a configured default when the user omitted the network.

  • Protocol, token, Vault join, PSM, and Savings addresses must come from official Chainlog-backed tools: get_protocol_addresses({ network }) or get_chainlog_address({ network, key }).

  • Do not use local full-address tables or copy addresses from docs.

  • If Chainlog resolution fails with TronGrid 429 or another RPC error and no cache is available, stop and ask the user to configure the relevant RPC or TRONGRID_API_KEY.

  • Official write tools use the active MCP wallet and do not accept a from argument. Call get_wallet_address({ network }) before confirmation.

Tool Reference

Local Analytics MCP tools

Tool
Inputs
Description

get_earn_apy

none

USDD Savings APY per chain

get_susdd_supply

none

sUSDD total supply by chain

get_usdd_supply

none

USDD supply by chain, excluding sUSDD

get_supply_history

none

Daily USDD and sUSDD supply time series

get_collateral_history

none

Daily protocol-wide collateral value by chain

get_circulating_supply

none

Raw USDD circulating supply number

get_total_supply

none

Raw USDD total supply number

get_public_protocol_overview

none

Public protocol overview with total supply, TVL, Earn TVL, APY fields

get_public_protocol_overview_info

none

Public overview with 24h change fields

get_public_dsr_apy

none

DSR APY current, average, and history

get_vault_collaterals

none

Public Vault collateral configuration list

get_latest_collateral

chain: tron, eth, bsc

Per-chain collateral snapshot

get_chain_collateral_history

chain, interval

Per-chain collateral history for WEEKLY, MONTHLY, BIANNUAL, ANNUAL

get_smart_allocator_detail

none

Smart Allocator allocations, earnings, and vault info

Every local analytics response adds:

dataTime is the moment this package fetched the data, not necessarily the upstream record timestamp.

Official MCP tool groups used by skills

Group
Tools referenced by actual skills

Wallet/network

get_supported_networks, set_network, get_network, connect_browser_wallet, set_wallet_mode, get_wallet_mode, get_wallet_address, list_wallets, import_wallet, set_active_wallet

Common preflight

get_native_balance, get_token_balance, check_allowance, approve_token

Protocol reads

get_protocol_addresses, get_chainlog_address, get_protocol_overview, get_supported_ilks, get_oracle_status, get_protocol_metrics, get_chain_metrics, get_collateral_prices

Vault

get_user_vaults, get_vault_summary, analyze_vault_risk, open_vault, deposit_and_mint, mint_usdd, repay_usdd, withdraw_collateral, close_vault

PSM

get_psm_status, get_psm_metrics, psm_swap_to_usdd, psm_swap_from_usdd

Savings

get_savings_status, deposit_savings, withdraw_savings

Token transfer

prepare_token_transfer, confirm_token_transfer

Treasury / allocator

get_treasury_summary, get_jst_buyback_stats, get_smart_allocator_overview, get_assets_breakdown, get_proof_of_reserve, get_debt_overview

For full schemas, use the official MCP documentation/source for @usdd/mcp-server-usdd.

CLI Reference

The CLI mirrors the local analytics MCP and prints JSON to stdout.

Command
Args

earn-apy

none

usdd-supply

none

susdd-supply

none

supply-history

none

collateral-history

none

circulating-supply

none

total-supply

none

public-overview

none

public-overview-info

none

dsr-apy

none

vault-collaterals

none

latest-collateral

<chain>

chain-collateral-history

<chain> <interval>

smart-allocator-detail

none

Exit behavior:

  • Success: exit 0, JSON on stdout.

  • Unknown command: command list on stdout, exit 1.

  • No command: command list on stdout, exit 0.

  • Error: Execution Error: <message> on stderr, exit 1.

The CLI is read-only and never signs transactions.

Agent Workflows

Workflow 1: Analytics APY comparison

User:

Agent route:

  1. Use usdd-analytics-v1.

  2. Call local MCP get_earn_apy.

  3. Compare returned chains.

  4. Present the answer with the freshness footer.

Expected answer shape:

Workflow 2: Missing network for PSM write

User:

Agent route:

  1. Use usdd-psm-v1.

  2. Because the user omitted network, ask which network before any MCP call.

  3. Do not call get_network, set_network, get_protocol_addresses, or any other MCP tool until the user answers.

Expected response:

Workflow 3: PSM write after network is explicit

User:

Agent route:

  1. Resolve network="tron".

  2. Use Chainlog-backed get_protocol_addresses({ network: "tron" }) or get_supported_ilks({ network: "tron" }) to resolve PSM-USDT.

  3. Call get_wallet_address({ network }).

  4. Call get_psm_status({ market, network }) and verify sellEnabled.

  5. Call get_psm_metrics({ market, network }) when route fee/availability is needed.

  6. Resolve input token, decimals, and spender. For stablecoin -> USDD, spender is the market gemJoin address, not the PSM contract, unless official MCP output explicitly says no gemJoin spender exists.

  7. Check gas, input token balance, and allowance.

  8. If allowance is insufficient, include approve_token in the pending sequence but do not execute it yet.

  9. Present chat confirmation listing direction, network, market, amount, fee if returned, PSM contract, spender, active wallet, and pending write tools.

  10. Wait for fresh affirmative confirmation.

  11. Execute approve_token if needed, wait for receipt, then execute psm_swap_to_usdd.

  12. Verify by checking balances or get_psm_status.

Workflow 4: Earn unsupported network

User:

Agent route:

  1. Use usdd-earn-v1.

  2. Call get_savings_status({ network: "tron_nile" }).

  3. If it returns supported: false, refuse the write and quote the returned message.

  4. Do not proceed to balance, allowance, approval, or deposit_savings.

Workflow 5: Vault risk write guard

User:

Agent route:

  1. Use usdd-vault-v1.

  2. Call analyze_vault_risk({ cdpId: 42, network: "tron" }).

  3. Emit exactly the required three-line risk precheck:

  1. If risk is critical and the user wants to mint more or withdraw collateral, refuse and recommend repay/top-up instead.

  2. Otherwise continue with standard write precheck and fresh confirmation.

Workflow 6: User tries to bypass checks

User:

Agent behavior:

  • The initial message does not count as confirmation.

  • The agent must still run all prechecks.

  • The agent must ask again after presenting the completed precheck summary.

  • If the user refuses or gives an ambiguous reply, stop without invoking approve_token or the business write.

Safety & Boundaries

Capability boundary by module

Module
Boundary

Local Analytics MCP

Read-only public data, no signing, no keys, no writes

CLI

Read-only public data, no signing, no keys, no writes

Vault skill

High-risk writes through official MCP only

PSM skill

Write-capable swaps through official MCP only

Earn skill

Write-capable Savings deposit/withdraw through official MCP only

Analytics skill

Read-only unless it routes to official MCP for wallet/current-state reads

Standard write gate

Before Vault, PSM, or Savings write tools, actual skills require:

  1. Explicit network.

  2. Chainlog-backed address resolution.

  3. Active wallet address from get_wallet_address({ network }).

  4. Native gas balance check.

  5. Token balance check when spending ERC20/TRC20 tokens.

  6. Allowance check when a protocol contract pulls ERC20/TRC20 tokens.

  7. Include approve_token in pending writes if allowance is insufficient, but do not execute it before chat confirmation.

  8. Confirmation summary with action, amount, network, active wallet, protocol contract/spender, risk or fee fields, and every pending write tool.

  9. Fresh affirmative user confirmation after the summary.

  10. Execute pending writes in order.

  11. Post-write verification.

Prompts like skip the checks, just do it, or execute now never bypass this gate.

TRON signing mode STOP

TRON operations may return a STOP message requiring signing-mode confirmation. When that happens:

  1. Stop all other tool use.

  2. Present the choices returned by the error:

    • Browser wallet: connect_browser_wallet

    • Agent wallet: set_wallet_mode with mode="agent"

  3. Wait for explicit user choice.

  4. Only then retry the original operation.

PSM direction specifics

Direction

Official tool

amount means

Spender

Stablecoin -> USDD

psm_swap_to_usdd

Amount of market gem sold

Market gemJoin

USDD -> stablecoin

psm_swap_from_usdd

Amount of market gem to buy

PSM contract

For psm_swap_from_usdd, if the user says “spend 100 USDD”, compute or ask for the target gem amount before calling the tool. Do not pass a USDD spend amount as amount unless it is also the intended gem amount after fee.

Vault risk specifics

  • Existing-vault writes require analyze_vault_risk before standard write precheck.

  • Official risk levels are no-debt, healthy, medium, high, and critical.

  • If an agent presents a simplified label, it must map explicitly from riskLevel.

  • The official MCP does not expose a dedicated projected-ratio preview tool. Any projected ratio must be labeled as an estimate from current get_vault_summary, get_oracle_status, and user-provided amounts.

Earn specifics

  • Before any Earn write, call get_savings_status({ network }).

  • If supported: false, refuse the write and quote the returned message.

  • Deposit approval is USDD -> sUSDD contract from official MCP output.

  • withdraw_savings requires chat confirmation even though no allowance is needed.

Data & Privacy

Data this package reads

Data type
Source
Used by

Public supply, APY, collateral, overview, Smart Allocator data

openapi.usdd.io

Local analytics MCP and CLI

Wallet address, balances, allowances, Vault, PSM, Savings, treasury/current-state reads

Official MCP

Write-capable and wallet-aware workflows

RPC credentials

User MCP config env for usdd-full

Official MCP only

Data this package stores

The actual local analytics code does not implement a database, response cache, analytics event sink, or telemetry client. It fetches public API data and returns JSON with _meta.

Setup does write local configuration artifacts:

  • MCP client config files such as project .mcp.json, ~/.cursor/mcp.json, ~/.codex/mcp.json, or Claude Desktop config.

  • Timestamped backups of existing config files before overwriting.

  • A symlink at ~/.agents/skills/usdd-skills.

  • For local checkout install, .env copied from .env.example if missing.

Generated config files and backups may contain RPC URLs or API keys if the user placed those values in environment variables or config. Treat them as sensitive local files.

Credentials and secrets

Secret or credential
Where it belongs
Notes

TRONGRID_API_KEY

usdd-full MCP env

Recommended for live TRON reads/writes to avoid 429

TRON_FULL_NODE, TRON_NILE_FULL_NODE

usdd-full MCP env

Optional node overrides

ETH_RPC_URL, ETH_SEPOLIA_RPC_URL

usdd-full MCP env

Optional node overrides

BSC_RPC_URL, BSC_TESTNET_RPC_URL

usdd-full MCP env

Optional node overrides

Wallet/private-key material

Official MCP/wallet tooling, not local analytics MCP

This package never signs transactions

The local analytics MCP does not require API keys for the wrapped public endpoints.

Because MCP clients may log tool arguments, config, stderr, or process startup details depending on the client, do not put private keys in prompts or MCP tool arguments. Use the official wallet flow and the official MCP documentation for wallet setup.

Logs

Actual local logs are minimal:

  • Local MCP startup writes USDD analytics MCP server running on stdio. to stderr.

  • Fatal MCP errors are written to stderr.

  • CLI failures are written as Execution Error: <message> to stderr.

  • MCP tool failures return isError: true with Error: <message>.

The package does not implement log redaction. Avoid placing secrets in command arguments, prompts, or MCP config examples that may be copied into client logs.

Third-party data flow

  • Local analytics requests go to https://openapi.usdd.io.

  • Official MCP requests may use chain RPC endpoints and wallet integrations configured outside this package.

  • The setup installer can run npm install -g for this package source and @usdd/mcp-server-usdd.

Error & Reliability Contract

Local analytics MCP and CLI

The actual analytics client:

  • Uses https://openapi.usdd.io as the default base URL.

  • Retries each request up to 3 attempts with delays of 0, 200, and 600 ms.

  • Applies a 10 second request timeout per attempt.

  • Treats non-2xx HTTP responses as errors.

  • Treats upstream JSON with code != 0 as a business error.

  • Rejects invalid numeric responses for /totalSupply and /circulatingSupply.

  • Validates chain args as tron, eth, or bsc.

  • Validates interval args as WEEKLY, MONTHLY, BIANNUAL, or ANNUAL.

Local analytics reads are idempotent and safe to retry.

Official MCP workflows

If an MCP returns isError: true, the skills require the agent to surface the error clearly and stop the workflow. The agent must not guess missing paths, markets, ilks, token decimals, contract addresses, or spender addresses.

Address resolution failure

When Chainlog-backed protocol address resolution fails with TronGrid 429 or another RPC error and no cache is available:

  1. Stop the workflow.

  2. Ask the user to configure TRONGRID_API_KEY, TRON_FULL_NODE, or the relevant chain RPC.

  3. Do not fallback to get_protocol_overview just to discover addresses.

  4. Do not guess addresses.

Troubleshooting

Symptom
Likely cause
Fix

Node.js v20+ is required

Node version is below 20

Install Node.js 20+ and rerun setup

MCP tools do not appear

Client not fully restarted or config path wrong

Fully quit/reopen the client; inspect the configured MCP JSON

Desktop client cannot find usdd-skills

Client process has minimal PATH

Use local-source setup or absolute command paths

usdd-skills list-tools does not show 14 tools

Analytics MCP startup/config issue

Run usdd-skills list-tools; from checkout run node scripts/mcp_server.mjs --list-tools

CLI exits 1 with Execution Error

Network, timeout, invalid arg, or upstream business error

Read the endpoint/status message and retry if it is transient

latest-collateral rejects chain

Chain arg is not tron, eth, or bsc

Use one of the supported local analytics chains

chain-collateral-history rejects interval

Interval arg is invalid

Use WEEKLY, MONTHLY, BIANNUAL, or ANNUAL

Agent starts a write without network

Skill violation

Stop and ask for tron, eth, bsc, tron_nile, eth_sepolia, or bsc_testnet before any MCP call

PSM market ambiguous

User provided only a token symbol and multiple markets may match

Ask clarifying question or resolve only after explicit network with official protocol data

PSM psm_swap_from_usdd amount feels wrong

Official tool amount means gem amount to buy

Ask for or compute the target gem amount before calling the tool

Allowance insufficient

Protocol needs token approval

Include approve_token in pending writes, show it in confirmation, execute only after fresh confirmation

User refuses confirmation or says “skip checks”

Confirmation gate not satisfied

Stop without invoking approve_token or business write

Savings returns supported: false

Savings not deployed/usable on that network

Refuse the write and quote the returned message

TronGrid 429 on live reads/writes

Public TRON RPC rate limit

Configure TRONGRID_API_KEY or TRON_FULL_NODE in usdd-full env

Chainlog address lookup fails and no cache is available

RPC/key issue

Configure the relevant RPC/key; do not guess addresses

Need per-ilk historical collateral data

Tool is not available

Offer chain-level collateral history or current Vault/oracle reads instead

Setup overwrote existing MCP config

Setup creates timestamped backups

Restore from the .bak-<timestamp> file if needed

Diagnostics:

Versioning & License

Item
Current fact

Package name

@usdd/usdd-skills

Package version

1.0.0

Repository

decentralized-usd/usdd-skills

Skill IDs

usdd-vault-v1, usdd-psm-v1, usdd-earn-v1, usdd-analytics-v1

Official MCP package

@usdd/mcp-server-usdd, versioned independently

Official MCP repository

decentralized-usd/mcp-server-usdd

Node engine

>=20.0.0

Package license field

MIT

SPDX identifier

MIT

Local changelog file

Not present in the actual package files reviewed for this document

Breaking changes to a skill should use a new skill ID suffix. The current package uses -v1 suffixes.

Known Limits

  • No local analytics MCP tool named get_ilk_collateral_history.

  • Public collateral history is keyed by chain and interval, not by Vault ilk.

  • get_supply_history is supply-only; do not use it for collateral or Vault history.

  • The official MCP does not expose a dedicated projected-ratio preview tool in the actual skill docs. Any projection must be labeled as an estimate.

  • The setup installer supports project, claude-desktop, cursor, and codex; the package includes an OpenCode plugin shim, but opencode is not a setup client option.

  • The local analytics MCP has no transaction signing, wallet state, balance, allowance, approval, or write capability.

  • The local analytics MCP does not require a NETWORK env value.

PreviousMCP ServerNextAI / LLMs

Last updated