onesource-api-mcp

onesource-api-mcp

MCP server for OneSource blockchain data. 34 named tools for balances, NFTs, transactions, events, and live chain queries via x402 micropayments.

npx onesource-api-mcp

Install

# Claude Code
claude mcp add onesource-api -- npx onesource-api-mcp

# Claude Desktop / Cursor — add to MCP config:
{
  "mcpServers": {
    "onesource-api": {
      "command": "npx",
      "args": ["-y", "onesource-api-mcp"]
    }
  }
}

Tools (34)

Indexed Data (12 tools) — OpenSearch, cheaper, slight sync delay

Tool	Description
1s_address_txs	Address transaction history
1s_block	Block details by number
1s_contract_info	Contract metadata
1s_erc1155_balance	ERC1155 token balance
1s_erc20_balance	ERC20 token balance
1s_erc20_transfers	ERC20 transfer history
1s_events	Event log search
1s_nft_media	NFT processed media URLs
1s_nft_metadata	NFT metadata and traits
1s_nft_owner	NFT current owner
1s_tx_details	Transaction with decoded events
1s_wallet_nfts	Wallet NFT portfolio

Live Chain Data (12 tools) — Direct RPC, real-time

Tool	Description
1s_allowance_live	ERC20 allowance check
1s_contract_info_live	Contract type detection via ERC165
1s_erc1155_balance_live	ERC1155 balance via RPC
1s_erc20_balance_live	ERC20 balance via balanceOf
1s_erc20_transfers_live	ERC20 Transfer logs via eth_getLogs
1s_erc721_tokens_live	ERC721 token enumeration
1s_events_live	Event logs via eth_getLogs
1s_multi_balance_live	ETH + multiple ERC20 balances
1s_nft_metadata_live	NFT metadata via tokenURI
1s_nft_owner_live	NFT owner via ownerOf
1s_total_supply_live	Token total supply
1s_tx_details_live	Transaction + receipt via RPC

Chain Utilities (10 tools) — RPC only

Tool	Description
1s_contract_code	Contract bytecode
1s_ens_resolve	ENS name/address resolution
1s_estimate_gas	Gas estimation
1s_network_info	Chain ID, block number, gas price
1s_nonce	Transaction count
1s_pending_block	Pending block from mempool
1s_proxy_detect	Proxy contract detection
1s_simulate_call	Simulate eth_call
1s_storage_read	Read storage slot
1s_tx_receipt	Transaction receipt

Networks

All tools accept an optional network parameter:

Network	Description
ethereum	Ethereum mainnet (default)
sepolia	Ethereum Sepolia testnet
avax	Avalanche C-Chain

Payment (x402)

Endpoints are priced in USDC on Base via x402. When the backend has payments enabled, tool calls return a 402 with payment details. Agents using @x402/fetch handle this automatically.

Configuration

Variable	Default	Description
ONESOURCE_BASE_URL	https://skills.onesource.io	Skills API endpoint
ONESOURCE_ANALYTICS	true	Set false to disable analytics
ONESOURCE_ANALYTICS_URL	—	Dashboard endpoint for event ingestion
ONESOURCE_ANALYTICS_KEY	—	API key for the analytics dashboard

Transport Modes

# stdio (default — for MCP clients)
npx onesource-api-mcp

# HTTP (for testing or remote access)
npx onesource-api-mcp --http
npx onesource-api-mcp --http --port=8080

HTTP mode binds to 127.0.0.1 by default.

Adding a New Tool

When a new SKILL.md is added to skills/OneSource*/, a corresponding MCP tool file needs to be created here.

Step 1: Create the SKILL.md in the skills repo (see the skills README for format).

Step 2: Scaffold the tool file:

cd mcp/
npm run new-tool

This prompts for:

• Tool name — 1s_ prefix, snake_case (e.g. 1s_token_info)
• Category — indexed (OpenSearch), live (RPC with indexed counterpart), or chain (RPC-only utility)
• Description — one-liner for the tool
• Endpoint — REST API path (e.g. /api/chain/my-endpoint)
• Method — GET or POST

It generates a tool file in src/tools/{category}/ with TODO markers.

Step 3: Edit the generated file — fill in the Zod schema parameters and handler logic. Use the shared params from src/types.ts (addressParam, txHashParam, tokenIdParam, hexDataParam, networkParam, limitParam, blockNumberParam).

Step 4: Build:

npm run build

This auto-regenerates the tool index and compiles. The new tool is immediately available in the MCP server.

License

MIT