Algorand Remote

Algorand Remote MCP

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

Wallet Management

Transaction Operations

Asset Operations

Application (Smart Contract) Operations

DEX — Haystack Router (DEX Aggregator)

DEX — Tinyman

Algod API

Pera Wallet Asset Verification

Indexer API

NFD (Algorand Name Service)

TEAL Operations

Utility Tools

ARC-26 URI & Receipts

AP2 Protocol

Alpha Arcade (Prediction Markets)

Knowledge Base

Resources

Knowledge Resources

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

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

Usage Flows

Authentication

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

Individual Transactions

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

Atomic Transaction Groups

1. Create group (sdk_create_atomic_group)
2. Sign group (wallet_sign_atomic_group or sdk_sign_atomic_group)
3. Submit group (sdk_submit_atomic_group)

DEX Swaps via Haystack Router

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

DEX Swaps via Tinyman

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

Prediction Markets via Alpha Arcade

1. Browse markets (alpha_get_live_markets)
2. Check orderbook (alpha_get_orderbook)
3. Place order (alpha_create_limit_order or alpha_create_market_order)
4. Monitor positions (alpha_get_positions) and open orders (alpha_get_open_orders)
5. Manage orders — amend (alpha_amend_order) or cancel (alpha_cancel_order)
6. 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

Contributing

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

License

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