Algorand Remote MCP

March 13, 2026 · View on GitHub

A Model Context Protocol (MCP) server that provides tools and resources for AI agents to interact with the Algorand blockchain. Built on Cloudflare Workers with HashiCorp Vault-based wallet management and multi-provider OAuth authentication.

Overview

Algorand Remote MCP bridges AI agents and the Algorand blockchain ecosystem through a standardized MCP interface. It enables AI systems to manage wallets, create and submit transactions, swap tokens via DEX aggregators, and access blockchain data — all without requiring deep blockchain expertise.

This is a remote MCP implementation running on Cloudflare Workers with:

HashiCorp Vault for secure Ed25519 key storage and transaction signing
Multi-provider OAuth (Google, GitHub, Twitter, LinkedIn) for user authentication
algosdk v3.5.2 for Algorand SDK operations
Haystack Router for best-price DEX aggregation across Tinyman, Pact, Folks, and LST protocols
Tinyman SDK for direct DEX swap operations
Alpha Arcade SDK for prediction market trading (orderbooks, limit/market orders, positions)

Quick Start

Prerequisites: Node.js v16+, an OAuth account (Google, GitHub, Twitter, or LinkedIn)

Add to your MCP client configuration:

{
  "mcpServers": {
    "algorand-remote-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://algorandmcp.goplausible.xyz/sse"
      ]
    }
  }
}

Restart your LLM agent and prompt:

Read Algorand MCP skill.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI Agents / LLM Clients                       │
│                    (Claude, GPT, Cursor, Windsurf, etc.)                    │
└─────────────────────────────┬───────────────────────────────────────────────┘
                              │ MCP Protocol (SSE / Streamable HTTP)
                              ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     Cloudflare Workers — Edge Runtime                       │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                        OAuthProvider Layer                            │  │
│  │          Google · GitHub · Twitter · LinkedIn (Multi-provider)        │  │
│  └───────────────────────────┬───────────────────────────────────────────┘  │
│                              ▼                                              │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │              AlgorandRemoteMCP (McpAgent / McpServer)                 │  │
│  │                                                                       │  │
│  │  ┌─────────────── Tool Managers ───────────────────────────────────┐  │  │
│  │  │                                                                 │  │  │
│  │  │  walletManager ─── accountManager ─── utilityManager            │  │  │
│  │  │  transactionManager/                                            │  │  │
│  │  │    ├── generalTransaction   (pay, sign, submit, keyreg)         │  │  │
│  │  │    ├── assetTransactions    (ASA create, optin, transfer)       │  │  │
│  │  │    ├── appTransactions      (create, update, delete, call)      │  │  │
│  │  │    └── groupTransactions    (atomic groups)                     │  │  │
│  │  │  algodManager ─── knowledgeManager                              │  │  │
│  │  │  arc26Manager ─── receiptManager ─── ap2Manager                 │  │  │
│  │  │  tinymanManager ─── alphaArcadeManager                          │  │  │
│  │  │  apiManager/                                                    │  │  │
│  │  │    ├── algod/       (account, application, asset, txn queries)  │  │  │
│  │  │    ├── indexer/     (search & lookup across all data types)     │  │  │
│  │  │    ├── hayrouter/   (DEX aggregator — quote, swap, optin)      │  │  │
│  │  │    └── nfd/         (Algorand Name Service lookups)            │  │  │
│  │  └─────────────────────────────────────────────────────────────────┘  │  │
│  │                                                                       │  │
│  │  ┌─────────────── Resources ───────────────────────────────────────┐  │  │
│  │  │  algorand://remote-mcp-skill         (Skill definition)        │  │  │
│  │  │  algorand://knowledge/taxonomy       (Knowledge base)          │  │  │
│  │  │  algorand://knowledge/taxonomy/{cat} (Category docs)           │  │  │
│  │  └─────────────────────────────────────────────────────────────────┘  │  │
│  │                                                                       │  │
│  │  ┌─────────────── Utils ───────────────────────────────────────────┐  │  │
│  │  │  ResponseProcessor (pagination, BigInt-safe JSON)               │  │  │
│  │  │  vaultManager (Vault API client)                                │  │  │
│  │  │  Skill.js (skill content)                                       │  │  │
│  │  └─────────────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌─────────────── Cloudflare Bindings ────────────────────────────────────┐ │
│  │  Durable Objects (session state)  ·  KV (OAuth tokens, client reg)    │ │
│  │  R2 Bucket (knowledge documents)  ·  Service Bindings (Vault worker)  │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
└──────────┬──────────────────┬──────────────────┬──────────────────┬─────────┘
           │                  │                  │                  │
           ▼                  ▼                  ▼                  ▼
┌──────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌───────────────┐
│  HashiCorp Vault │ │  Algorand Node │ │  DEX & Markets │ │  External APIs│
│  (CF Worker)     │ │  (Algod +      │ │                │ │               │
│                  │ │   Indexer)     │ │  Haystack      │ │  NFD API      │
│  Ed25519 keypair │ │                │ │  Router        │ │  Pera API     │
│  generation      │ │  Nodely.io /   │ │  ┌──────────┐  │ │  Alpha Arcade │
│  Transit engine  │ │  AlgoNode      │ │  │ Tinyman  │  │ │  API          │
│  signing         │ │                │ │  │ Pact     │  │ │               │
│  No private key  │ │  MainNet /     │ │  │ Folks    │  │ │               │
│  exposure        │ │  TestNet       │ │  │ LST      │  │ │               │
│                  │ │                │ │  └──────────┘  │ │               │
└──────────────────┘ └────────────────┘ │                │ └───────────────┘
                                        │  Tinyman SDK   │
                                        │  Alpha Arcade  │
                                        │  SDK           │
                                        └────────────────┘

Component Summary

AlgorandRemoteMCP: Main MCP agent extending McpAgent on Cloudflare Workers
OAuthProvider: Multi-provider authentication layer (Google, GitHub, Twitter, LinkedIn)
Tool Managers: 15 specialized managers covering accounts, wallets, transactions, assets, applications, APIs, DEX operations, prediction markets, ARC-26 URIs, receipts, AP2 protocol, and knowledge
Resource Providers: URI-based access to skill definition and knowledge base via R2
ResponseProcessor: Standardized response formatting with pagination and BigInt-safe serialization
HashiCorp Vault: Ed25519 keypair generation and secure signing via Transit engine — no private key exposure
Cloudflare Bindings: Durable Objects for session state, KV for OAuth, R2 for knowledge docs, Service Bindings for Vault worker

Tools

Account Management

Tool	Description
`sdk_create_algorand_keypair`	Create a new Algorand keypair (not wallet-linked)
`sdk_mnemonic_to_address_and_secretkey`	Get address and secret key from a mnemonic
`sdk_address_to_public_key`	Get the public key for an Algorand address
`sdk_check_account_balance`	Check account balance in ALGO

Wallet Management

Tool	Description
`wallet_get_info`	Get account information including address, publicKey, balance, and assets (replaces `wallet_get_address` and `wallet_get_publickey`)
`wallet_get_role`	Get the role UUID for the configured wallet to be used to login into Hashicorp Vault with OIDC
`wallet_get_assets`	Get assets held by the wallet
`wallet_reset_account`	Reset wallet and generate new keys (destructive)
`wallet_logout`	Logout from OAuth provider

Transaction Operations

Tool	Description
`sdk_txn_payment_transaction`	Create a payment transaction
`wallet_sign_transaction`	Sign a transaction using vault keys
`sdk_sign_transaction`	Sign a transaction using a mnemonic
`sdk_submit_transaction`	Submit a signed transaction to the network
`sdk_txn_key_registration_transaction`	Create a key registration transaction
`sdk_assign_group_id`	Assign group ID for atomic execution
`sdk_create_atomic_group`	Create an atomic transaction group (pay, axfer, acfg, appl, afrz, keyreg)
`wallet_sign_atomic_group`	Sign an atomic group using vault keys
`sdk_sign_atomic_group`	Sign an atomic group using a mnemonic
`sdk_submit_atomic_group`	Submit a signed atomic group
`sdk_send_raw_transaction`	Submit raw signed transactions

Asset Operations

Tool	Description
`sdk_txn_create_asset`	Create a new Algorand Standard Asset (ASA)
`sdk_txn_asset_optin`	Opt-in to an ASA
`wallet_usdc_optin`	Opt-in agent wallet to USDC (vault-signed)
`sdk_txn_transfer_asset`	Transfer an ASA

Application (Smart Contract) Operations

Tool	Description
`sdk_txn_create_application`	Create a new smart contract
`sdk_txn_update_application`	Update an existing smart contract
`sdk_txn_delete_application`	Delete a smart contract
`sdk_txn_closeout_application`	Close out from an application
`sdk_txn_clear_application`	Clear application state
`sdk_txn_call_application`	Call a smart contract (noop, optin, closeout, clear, delete)
`sdk_optin_application`	Opt-in to an application

DEX — Haystack Router (DEX Aggregator)

Tool	Description
`haystack_get_swap_quote`	Get best-price swap quote across multiple DEXes and LST protocols
`haystack_execute_swap`	Execute an optimized swap: quote, vault-sign, submit, confirm
`haystack_needs_optin`	Check if an address needs to opt-in to an asset before swapping

DEX — Tinyman

Tool	Description
`tinyman_fixed_input_swap`	Execute a swap with a fixed input amount
`tinyman_fixed_output_swap`	Execute a swap with a fixed output amount

Algod API

Tool	Description
`algod_get_account_info`	Get account balance, assets, and auth address
`algod_get_account_application_info`	Get account-specific application info
`algod_get_account_asset_info`	Get account-specific asset info
`algod_get_application_info`	Get application details
`algod_get_application_box_value`	Get application box contents
`algod_get_application_boxes`	List application boxes
`algod_get_application_state`	Get application global state
`algod_get_asset_info`	Get asset details
`algod_get_asset_holding`	Get asset holding for an account
`algod_get_pending_txn_info`	Get pending transaction details
`algod_get_pending_transactions`	Get pending transactions from mempool

Pera Wallet Asset Verification

Tool	Description
`pera_asset_verification_status`	Get verification status of an asset
`pera_verified_asset_details`	Get detailed asset information from Pera
`pera_verified_asset_search`	Search verified assets by name, unit name, or creator

Indexer API

Tool	Description
`indexer_lookup_account_assets`	Get account assets
`indexer_lookup_account_app_local_states`	Get account app local states
`indexer_lookup_account_created_apps`	Get applications created by an account
`indexer_lookup_account_transactions`	Get transactions for an account
`indexer_search_for_accounts`	Search accounts with filters
`indexer_lookup_application_logs`	Get application log messages
`indexer_search_for_applications`	Search applications
`indexer_lookup_asset_balances`	Get holders of a specific asset
`indexer_search_for_assets`	Search assets
`indexer_lookup_transaction_by_id`	Get transaction details
`indexer_search_for_transactions`	Search transactions

NFD (Algorand Name Service)

Tool	Description
`api_nfd_get_nfd`	Get NFD domain information by name
`api_nfd_get_nfds_for_address`	Get all NFD domains owned by an address

TEAL Operations

Tool	Description
`sdk_compile_teal`	Compile TEAL source code
`sdk_disassemble_teal`	Disassemble TEAL bytecode

Utility Tools

Tool	Description
`sdk_validate_address`	Check if an Algorand address is valid
`sdk_encode_address`	Encode a public key to an address
`sdk_decode_address`	Decode an address to a public key
`sdk_app_address_by_id`	Get the address for an application ID
`sdk_verify_bytes`	Verify a signature against bytes
`sdk_sign_bytes`	Sign bytes with a secret key
`algorand_mcp_skill`	Access comprehensive Algorand MCP skill

ARC-26 URI & Receipts

Tool	Description
`generate_algorand_uri`	Generate an ARC-26 compliant URI
`generate_algorand_qrcode`	Generate a QR code for an Algorand URI
`generate_algorand_receipt`	Generate a transaction receipt

AP2 Protocol

Tool	Description
`generate_ap2_mandate`	Create an AP2 intent, cart, or payment mandate with verifiable credentials

Alpha Arcade (Prediction Markets)

Tool	Description
`alpha_get_live_markets`	Fetch all live prediction markets (title, prices, volume, multi-choice options)
`alpha_get_reward_markets`	Fetch markets with liquidity rewards
`alpha_get_market`	Get full details for a single market (on-chain + API)
`alpha_get_orderbook`	Unified YES-perspective orderbook with spread calculation
`alpha_get_open_orders`	Fetch open orders for a wallet on a specific market
`alpha_get_positions`	Fetch all YES/NO token positions across markets
`alpha_create_limit_order`	Place a limit order (price & quantity in microunits)
`alpha_create_market_order`	Place a market order with auto-matching and slippage
`alpha_cancel_order`	Cancel an open order and refund collateral
`alpha_amend_order`	Edit an existing unfilled order in-place
`alpha_propose_match`	Propose a match between a maker order and your wallet
`alpha_split_shares`	Split USDC into equal YES + NO outcome tokens
`alpha_merge_shares`	Merge YES + NO tokens back into USDC
`alpha_claim`	Claim USDC from a resolved market by redeeming outcome tokens

Knowledge Base

Tool	Description
`get_knowledge_doc`	Get markdown content for knowledge documents
`list_knowledge_docs`	List available knowledge documents by category

Resources

Knowledge Resources

URI	Description
`algorand://knowledge/taxonomy`	Full taxonomy of knowledge resources
`algorand://knowledge/taxonomy/{category}`	Category-specific resources (arcs, sdks, algokit, puya, etc.)

Skill

URI	Description
`algorand://remote-mcp-skill`	Comprehensive Algorand MCP skill

Development

Prerequisites

Node.js v16+
Cloudflare Workers account
Algorand node access (e.g., Nodely.io / AlgoNode)
OAuth credentials (Google, GitHub, Twitter, and/or LinkedIn)
HashiCorp Vault worker for secure key management

Environment Variables

ALGORAND_NETWORK=mainnet
ALGORAND_ALGOD=https://your-algod-node.com
ALGORAND_INDEXER=https://your-indexer-node.com
ALGORAND_TOKEN=your-api-token
NFD_API_URL=https://api.nf.domains
HAYSTACK_API_KEY=your-haystack-api-key
ALPHA_API_KEY=your-alpha-arcade-api-key           # Optional, enables richer market data
ALPHA_API_BASE_URL=https://platform.alphaarcade.com/api  # Optional, default shown
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
HCV_WORKER_URL=https://your-hashicorp-vault-worker.workers.dev

Scripts

npm run dev          # Start local development server
npm run type-check   # Run TypeScript type checking
npm run deploy       # Deploy to Cloudflare Workers
npm run format       # Format code with Biome
npm run lint:fix     # Lint and auto-fix with Biome

Deployment

Clone the repository
Install dependencies: npm install
Configure environment variables in wrangler.toml
Deploy: npm run deploy

Usage Flows

Authentication

User authenticates via OAuth (Google, GitHub, Twitter, or LinkedIn)
Server creates or retrieves wallet credentials from HashiCorp Vault
User accesses tools and resources through the MCP interface
User can logout using wallet_logout

Individual Transactions

Create transaction (e.g., sdk_txn_payment_transaction)
Sign with vault (wallet_sign_transaction) or mnemonic (sdk_sign_transaction)
Submit to network (sdk_submit_transaction)

Atomic Transaction Groups

Create group (sdk_create_atomic_group)
Sign group (wallet_sign_atomic_group or sdk_sign_atomic_group)
Submit group (sdk_submit_atomic_group)

DEX Swaps via Haystack Router

Get best-price quote (haystack_get_swap_quote)
Execute swap — quotes, vault-signs, submits, and confirms in one call (haystack_execute_swap)

DEX Swaps via Tinyman

Execute fixed-input or fixed-output swap (tinyman_fixed_input_swap / tinyman_fixed_output_swap)

Prediction Markets via Alpha Arcade

Browse markets (alpha_get_live_markets)
Check orderbook (alpha_get_orderbook)
Place order (alpha_create_limit_order or alpha_create_market_order)
Monitor positions (alpha_get_positions) and open orders (alpha_get_open_orders)
Manage orders — amend (alpha_amend_order) or cancel (alpha_cancel_order)
Claim winnings from resolved markets (alpha_claim)

Project Structure

src/
├── index.ts                      # Main entry point
├── types.ts                      # Type definitions
├── oauth-handler.ts              # OAuth authentication handler
├── workers-oauth-utils.ts        # OAuth utilities
├── resources/
│   ├── skill/                    # Skill resource
│   └── knowledge/                # Knowledge base resources
├── tools/
│   ├── accountManager.ts         # Account management
│   ├── algodManager.ts           # Algorand node tools
│   ├── ap2Manager.ts             # AP2 protocol tools
│   ├── arc26Manager.ts           # ARC-26 URI and QR tools
│   ├── knowledgeManager.ts       # Knowledge base tools
│   ├── receiptManager.ts         # Transaction receipt tools
│   ├── tinymanManager.ts         # Tinyman DEX tools
│   ├── alphaArcadeManager.ts     # Alpha Arcade prediction market tools
│   ├── utilityManager.ts         # Utility tools
│   ├── walletManager.ts          # Wallet management tools
│   ├── apiManager/
│   │   ├── algod/                # Algod API tools (account, application, asset, transaction)
│   │   ├── hayrouter/            # Haystack Router DEX aggregator tools
│   │   ├── indexer/              # Indexer API tools (account, application, asset, transaction)
│   │   └── nfd/                  # NFD name service tools
│   └── transactionManager/
│       ├── generalTransaction.ts # Payment, signing, submission, key registration
│       ├── appTransactions.ts    # Application (smart contract) transactions
│       ├── assetTransactions.ts  # Asset create, optin, transfer
│       └── groupTransactions.ts  # Atomic transaction groups
└── utils/
    ├── Skill.js                  # Skill content
    ├── vaultManager.ts           # HashiCorp Vault integration
    └── responseProcessor.ts      # Response formatting and pagination

Key Dependencies

Package	Version	Purpose
`algosdk`	^3.5.2	Algorand JavaScript SDK
`@txnlab/haystack-router`	^2.0.5	DEX aggregator for best-price swaps
`@tinymanorg/tinyman-js-sdk`	^5.1.2	Tinyman DEX SDK
`@alpha-arcade/sdk`	latest	Prediction market trading SDK
`@modelcontextprotocol/sdk`	^1.12.1	MCP protocol SDK
`agents`	^0.0.95	Cloudflare Agents SDK
`algo-msgpack-with-bigint`	^2.1.1	MessagePack with BigInt support

Contributing

Fork the repository
Create your feature branch: git checkout -b feature/my-new-feature
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.