Quicksilver MCP Server

Model Context Protocol (MCP) server that provides access to data sources with X402 payment support.

Table of Contents

• Features
• Architecture
• Installation
  • Prerequisites
    • Runtime Environment
    • MCP-Compatible Client
    • Wallet with USDC
  • Connect (MCP client configuration)
    • Runtime Option A: Node.js via npx
    • Runtime Option B: Docker
  • Wallet Configuration
    • Method 1: Private Key
    • Method 2: CDP Server Wallet
    • Useful Resources

Features

• List Sources: Enumerate available data sources
• Get Source Schema: Retrieve schema information for specific sources
• Query Tool: Execute queries against data sources
• X402 Payments: Supports X402 protocol for paying per query

Architecture

┌─────────────┐
│   Client    │
│(e.g. Claude)│
└──────┬──────┘
       │
       │ List Sources (Free)
       │ Get Source Schema (Free)
       │ Execute Query (Paid via X402)
       ▼
┌─────────────┐
│ MCP Server  │
│(Quicksilver)│
└──────┬──────┘
       │
       │ GET /api/x402/sources
       │ GET /api/x402/sources/{sourceId}
       │ POST /api/x402/sources/{sourceId}/query
       ▼
┌─────────────┐
│ Quicksilver │
│ Data Server │
└─────────────┘

Operations:

1. List Sources (Free): Client → MCP → Data Server
2. Get Schema (Free): Client → MCP → Data Server
3. Execute Query (Paid): Client → MCP → Data Server (with X-PAYMENT header)

Installation

Prerequisites

1. Runtime Environment (Choose One)

Option A: Node.js 20 or Higher

Install from the Node.js website if needed.

Verify your installation:

node --version

Option B: Docker

Install from the Docker website if needed.

Verify your installation:

docker --version

2. MCP-Compatible Client

Any client that supports the Model Context Protocol, such as:

• Claude Desktop
• Cursor IDE
• AI agents with MCP support

3. Wallet with USDC

• USDC on IoTeX (4689) or Base (8453) network is required for paid query operations
  • IoTeX USDC address: 0xcdf79194c6c285077a58da47641d4dbe51f63542
  • Base USDC address: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Chain selection: the server will choose the chain where balance of your wallet's USDC is the highest.
• Gas (IOTX) is not required — the X402 facilitator covers gas fees
• Free operations (listing sources, retrieving schemas) work without USDC

Connect (MCP client configuration)

This server implements the Model Context Protocol.

Two runtimes are supported:

• Node.js (via npx)
• Docker (via GHCR image)

Two wallet import methods are supported:

• Private Key (direct wallet access)
• CDP API (Coinbase Developer Platform Server Wallet)

All combinations of runtime and wallet method are supported.

Runtime Option A: Node.js via npx

With Private Key:

{
  "mcpServers": {
    "quicksilver": {
      "command": "npx",
      "args": ["-y", "quicksilver-mcp@latest"],
      "env": {
        "RESOURCE_SERVER_URL": "https://data.iotex.ai/",
        "PRIVATE_KEY": "0x123...",
        "QS_SOURCE_WHITELIST": "sourceID1,sourceID2"
      }
    }
  }
}

With CDP API:

{
  "mcpServers": {
    "quicksilver": {
      "command": "npx",
      "args": ["-y", "quicksilver-mcp@latest"],
      "env": {
        "RESOURCE_SERVER_URL": "https://data.iotex.ai/",
        "CDP_API_KEY_ID": "your-api-key-id",
        "CDP_API_KEY_SECRET": "your-api-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret",
        "CDP_ACCOUNT_NAME": "my-quicksilver-account",
        "QS_SOURCE_WHITELIST": "sourceID1,sourceID2"
      }
    }
  }
}

Runtime Option B: Docker (pull from GHCR)

With Private Key:

{
  "mcpServers": {
    "quicksilver": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "RESOURCE_SERVER_URL",
        "-e",
        "PRIVATE_KEY",
        "-e",
        "QS_SOURCE_WHITELIST",
        "ghcr.io/iotexproject/quicksilver-mcp:latest"
      ],
      "env": {
        "RESOURCE_SERVER_URL": "https://data.iotex.ai/",
        "PRIVATE_KEY": "0x123...",
        "QS_SOURCE_WHITELIST": "sourceID1,sourceID2"
      }
    }
  }
}

With CDP API:

{
  "mcpServers": {
    "quicksilver": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "RESOURCE_SERVER_URL",
        "-e",
        "CDP_API_KEY_ID",
        "-e",
        "CDP_API_KEY_SECRET",
        "-e",
        "CDP_WALLET_SECRET",
        "-e",
        "CDP_ACCOUNT_NAME",
        "-e",
        "QS_SOURCE_WHITELIST",
        "ghcr.io/iotexproject/quicksilver-mcp:latest"
      ],
      "env": {
        "RESOURCE_SERVER_URL": "https://data.iotex.ai/",
        "CDP_API_KEY_ID": "your-api-key-id",
        "CDP_API_KEY_SECRET": "your-api-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret",
        "CDP_ACCOUNT_NAME": "my-quicksilver-account",
        "QS_SOURCE_WHITELIST": "sourceID1,sourceID2"
      }
    }
  }
}

Environment variables:

• RESOURCE_SERVER_URL: Base URL for the Quicksilver data server (example: https://data.iotex.ai/)
• QS_SOURCE_WHITELIST: Comma-separated list of source IDs allowed for paid queries.
  • Default behavior: If unset or empty, all paid queries are refused (default-deny).
  • Explicit allowlist: Set to comma-separated source IDs (e.g., "fbbbb1111-0000-1111-2222-300ba9e2a912,fbbbb1111-0000-1111-2222-300ba9e2a913"). Only these sources can be queried via the paid query-source tool.
  • Allow-all option: Set to "*" to allow queries to all sources. Use this only if you understand and accept the trade-offs (for example, querying sources you haven't reviewed, or returning large responses).

Why whitelist sources?

1. Security: Sources can be added by anyone. Default-deny ensures you only query sources you've verified.
2. Data bloat: Some sources return large datasets that can bloat LLM context. Whitelisting lets you control which sources are accessible.

Note: Free tools (list-available-sources, get-source-schema) work without QS_SOURCE_WHITELIST and don't require wallet credentials. Use them to discover sources before whitelisting.

Wallet Configuration

The server supports two wallet import methods for paid queries. Choose one:

Method 1: Private Key

Use a raw private key for direct wallet access:

• PRIVATE_KEY: Wallet private key used to sign X402 payments (hex string starting with 0x)

Method 2: CDP Server Wallet

Use Coinbase Developer Platform (CDP) Server Wallet for managed wallet infrastructure.

Required environment variables:

• CDP_API_KEY_ID: API key ID from the CDP Portal
• CDP_API_KEY_SECRET: API key secret from the CDP Portal
• CDP_WALLET_SECRET: Wallet encryption secret from the CDP Portal
• CDP_ACCOUNT_NAME: Name of the CDP account to use (preferred, will be created if it doesn't exist), OR
• CDP_ACCOUNT_ADDRESS: Address of an existing CDP account to use (alternative)

Important:

• If using CDP_ACCOUNT_NAME, the account will be created automatically if it doesn't exist. You'll need to fund it with USDC before making paid queries.
• If using CDP_ACCOUNT_ADDRESS, the account must already exist and have USDC funds.
• See Managing Accounts for more details.

Security Tip: CDP Server Wallets support policies to control transaction signing behavior. You can configure allowlists, denylists, transaction limits, and other restrictions to secure your wallet operations.

Priority: If both PRIVATE_KEY and CDP credentials are provided, PRIVATE_KEY takes precedence.

Useful Resources

• IoTeX Hub — Swap and bridge tokens including USDC
• USDC Contract on IoTeXScan — View USDC token details and transactions on IoTeX network
• USDC Contract on BaseScan — View USDC token details and transactions on Base network
• ioPay Wallet — Mobile wallet for managing IoTeX assets
• IoTeX Official Website — Learn more about the IoTeX ecosystem
• CDP Server Wallet Documentation — Complete guide to Coinbase Developer Platform Server Wallets
• CDP Wallet Policies — Configure transaction signing restrictions and security policies