Algorand Remote MCP Lite (Wallet Edition)

Algorand Remote MCP Lite is a wallet-first Model Context Protocol server for Algorand. It is a trimmed version of the full remote MCP, focused on agentic wallet workflows with 46 tools covering wallet management, transactions, blockchain queries, DEX-aggregated swaps, and more. It runs on Algorand Mainnet by default and signs transactions server-side using HashiCorp Vault.

Architecture

• MCP server on Cloudflare Workers (Durable Object) that registers wallet, transaction, and API tools.
• OAuth 2.0 with PKCE and OIDC-compatible social login (Google, GitHub, Twitter/X, LinkedIn) for user identity.
• HashiCorp Vault transit signing via the HCV_WORKER service; private keys never leave the vault.
• Algod + Indexer APIs for on-chain state and transaction submission.
• KV namespaces for OAuth sessions, vault entity mapping, verified assets, ARC-26 QR/receipt caching, and AP2 storage.

Design

• Wallet edition: minimal, curated tool set that behaves like an agentic wallet.
• Server-side signing: the LLM never receives mnemonics or private keys.
• Mainnet-first: examples and defaults target mainnet assets and apps.
• Modular tooling: wallet, transactions, indexer, NFD, Pera verified assets, Haystack Router DEX swaps, and more are separate tool groups.

OAuth + OIDC and Agentic Wallets

• Users authenticate via OAuth/OIDC providers; approval and PKCE flows are handled in src/oauth-handler.ts and src/oauth-provider.ts.
• After login, ensureUserAccount binds the social identity (provider + email) to a Vault entity and transit key.
• The wallet address is derived from the Vault public key and used as the agent wallet.
• Signing tools (wallet_sign_transaction, wallet_sign_atomic_group) use Vault transit so signatures are produced inside Vault.

Features

• Agentic wallet operations: balance, assets, signing, and submission without exposing secrets.
• On-demand topup using Algorand ARC-26 QR codes (generate_algorand_qrcode).
• AP2 mandate generation for intent, cart, and payment flows (generate_ap2_mandate).
• Receipt generation with QR codes for payments and asset transfers (generate_algorand_receipt).
• Atomic transaction groups and asset workflows (opt-in, transfer, USDC opt-in).
• Verified asset discovery via Pera Wallet and NFD lookups.
• Best-price DEX swaps via Haystack Router (aggregates Tinyman, Pact, Folks, LST protocols).

Available Tools (46)

Wallet (4)

• wallet_get_info: Get the account information for the configured wallet (address, publicKey, balance, assets)
• wallet_get_assets: Get all asset holdings for the configured wallet
• wallet_get_role: Get wallet user role UUID (sensitive — warn users to protect it)
• wallet_reset_account: Reset/recreate wallet account with new keys (DESTRUCTIVE — transfer funds first!)

Account (1)

• sdk_check_account_balance: Check the ALGO balance of an Algorand account

Utility (5)

• sdk_validate_address: Check if an Algorand address is valid
• sdk_encode_address: Encode a public key to an Algorand address
• sdk_decode_address: Decode an Algorand address to a public key
• sdk_app_address_by_id: Get the escrow address for a given application ID
• algorand_mcp_skill: Access comprehensive skill/guide for using Algorand Remote MCP Lite, including workflows, examples, and best practices

Transactions (4)

• sdk_txn_payment_transaction: Create an ALGO payment transaction
• wallet_sign_transaction: Sign an Algorand transaction with the agent wallet (via Vault)
• sdk_submit_transaction: Submit a signed transaction to the Algorand network
• sdk_send_raw_transaction: Submit raw signed transaction bytes to the network

Asset Transactions (4)

• sdk_txn_asset_create: Create a new Algorand Standard Asset (ASA)
• sdk_txn_asset_optin: Opt-in to an Algorand Standard Asset (ASA)
• sdk_txn_asset_transfer: Transfer an Algorand Standard Asset (ASA)
• wallet_usdc_optin: One-step USDC opt-in for the agent wallet (builds, signs, submits)

Atomic Groups (5)

• sdk_assign_group_id: Assign a group ID to transactions for atomic execution
• sdk_create_atomic_group: Create an atomic transaction group from multiple transactions
• sdk_sign_atomic_group: Sign an atomic transaction group (SDK-level)
• wallet_sign_atomic_group: Sign an atomic transaction group (via wallet/Vault)
• sdk_submit_atomic_group: Submit a signed atomic transaction group to the network

Algod API (4)

• algod_get_account_info: Get current account balance, assets, and auth address from algod
• algod_get_account_asset_info: Get account-specific asset information from algod
• algod_get_asset_info: Get asset details (name, decimals, supply, creator) from algod
• algod_get_pending_txn_info: Get pending transaction details by transaction ID

Pera Asset Verification (2)

• pera_verified_asset_query: Get detailed information about an Algorand asset from Pera (includes verification tier)
• pera_verified_assets_search: Search Pera verified assets by asset name, unit name, or creator address

Indexer API (7)

• indexer_search: General search across accounts, transactions, assets, or applications
• indexer_search_for_accounts: Search for accounts with various criteria
• indexer_search_for_assets: Search for assets with various criteria
• indexer_lookup_account_assets: Get assets held by an account
• indexer_lookup_account_transactions: Get transaction history for an account
• indexer_lookup_asset_balances: Get accounts that hold a specific asset
• indexer_lookup_transaction_by_id: Get transaction details by ID

NFD API (2)

• api_nfd_get_nfd: Get NFD (.algo) domain information by name
• api_nfd_get_nfds_for_address: Get all NFD names owned by an Algorand address

Haystack Router — DEX Aggregator (3)

• haystack_get_swap_quote: Get best-price swap quote across multiple DEXes (Tinyman, Pact, Folks, LST protocols)
• haystack_execute_swap: All-in-one swap: quote + sign via wallet + submit + confirm
• haystack_needs_optin: Check if an address needs to opt into an asset before swapping

ARC-26 (1)

• generate_algorand_qrcode: Generate an ARC-26 URI and QR code for payment or asset transfer requests

Receipts (1)

• generate_algorand_receipt: Generate a transaction receipt with QR code for payments or asset transfers

AP2 (1)

• generate_ap2_mandate: Create an AP2 intent, cart, or payment mandate

Tinyman (2)

• tinyman_fixed_input_swap: Execute a swap with a fixed input amount
• tinyman_fixed_output_swap: Execute a swap with a fixed output amount

Resources (1)

• Algorand MCP Skill (algorand://remote-mcp-skill): Comprehensive skill definition for using Algorand Remote MCP tools.

Usage

Local development

1. Install dependencies: npm install
2. Configure wrangler.jsonc vars and secrets (Algod/Indexer URLs, OAuth client IDs/secrets, Vault worker URL/token).
3. Start the worker: npm run dev

OAuth flow (high level)

1. A client requests /authorize and chooses a social provider.
2. The user authenticates, then /callback exchanges the code for tokens.
3. The server binds the identity to a Vault keypair and exposes wallet tools.

Notes

• This server is configured for Algorand Mainnet by default; update ALGORAND_NETWORK, ALGORAND_ALGOD, and ALGORAND_INDEXER if you need to point elsewhere.
• ARC-26 QR codes are intended for on-demand topups and user-friendly funding flows.