OneSource MCP

@one-source/mcp Unified MCP server for OneSource — 31 tools for blockchain data, live chain queries, and API documentation in a single server.

CommunityOnlineNo sign-inGlobalFreeRead-only

What it can do

  • 1s Address Txs: Get transaction history for an address (sent and received). Sorted by block number descending. Use from_block/to_block to narrow the range.
  • 1s Block: Get indexed block details by block number. Returns block metadata including timestamp, transaction count, and gas used. For the latest pending block, use 1s_pending_block instead.
  • 1s Contract Info: Get indexed contract metadata including deployment info and detected standards. Use this for enriched contract data; use 1s_contract_info_live for real-time ERC standard detection vi

What data it sees

Do you need an account

No: the server works without sign-in

@one-source/mcp

Unified MCP server for OneSource — 31 tools for blockchain data, live chain queries, and API documentation in a single server.

Combines @one-source/api-mcp (22 tools) and @one-source/docs-mcp (9 tools) so your AI assistant gets full access to OneSource with one MCP connection.

What is MCP? The Model Context Protocol lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.

Quick Start

Claude Code

claude mcp add onesource -- npx @one-source/mcp

Claude Desktop / Cursor

Add to your MCP config:

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp"]
    }
  }
}

Any MCP Client (stdio)

npx @one-source/mcp

HTTP Server (self-hosted)

npx @one-source/mcp --http
npx @one-source/mcp --http --port=8080

Then connect your MCP client to http://localhost:3000/.

Tools (31)

Blockchain API — Live Chain (12 tools)

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

Blockchain API — Chain Utilities (10 tools)

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

Documentation (9 tools)

Read-only, no API key required.

Tool Purpose When to use
search_docs Keyword search across all documentation Finding guides, concepts, or API patterns
get_query_reference Full reference for a root GraphQL query Building a specific query with correct args/filters
get_type_definition Schema definition for any type/enum/input Understanding field shapes and return types
list_examples Browse or search working GraphQL examples Finding ready-to-use query patterns
list_supported_chains All supported blockchain networks + endpoints First question: "What chains are supported?"
get_filter_reference Filter fields and operators for a list query Building filtered queries with correct syntax
get_pagination_guide Cursor-based pagination pattern with examples Implementing pagination for list queries
get_schema_overview High-level summary of the entire schema Exploring the API surface before diving in
get_authentication_guide API key format, headers, and endpoints Setting up authentication for the first time

Networks

All blockchain API tools accept an optional network parameter:

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

Payment (x402)

Blockchain API 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.

Documentation tools are always free — no API key or authentication needed.

License

Apache 2.0

Server tool list (43)

Raw names from tools/list. Only developers need these.

1s_address_txsGet transaction history for an address (sent and received). Sorted by block number descending. Use from_block/to_block to narrow the range.
1s_blockGet indexed block details by block number. Returns block metadata including timestamp, transaction count, and gas used. For the latest pending block, use 1s_pending_block instead.
1s_contract_infoGet indexed contract metadata including deployment info and detected standards. Use this for enriched contract data; use 1s_contract_info_live for real-time ERC standard detection via RPC.
1s_erc1155_balanceGet indexed ERC1155 token balance. Use this for cached lookups; use 1s_erc1155_balance_live for real-time data. Requires the contract address and specific token ID.
1s_erc20_balanceGet indexed ERC20 token balance for a wallet. Use this for historical or cached balance lookups; use 1s_erc20_balance_live for real-time data. Returns token metadata (name, symbol, decimals) alongside the balance.
1s_erc20_transfersGet ERC20 transfer history filtered by token and/or wallet. Use this for indexed transfer records; use 1s_erc20_transfers_live for raw Transfer event logs. Sorted by block number descending.
1s_eventsSearch indexed event logs by contract address and/or event name. Use this for decoded, searchable events; use 1s_events_live for raw eth_getLogs against the node. Sorted by block number descending.
1s_nft_mediaGet processed media files (images, videos, thumbnails) for an NFT. Use this to get optimized media URLs with dimensions and content types. Only returns successfully processed media (status=OK).
1s_nft_metadataGet NFT metadata including name, description, image URL, and traits from the index. Use this for enriched metadata; use 1s_nft_metadata_live to fetch directly from the token's URI. Excludes records with fetch errors.
1s_nft_ownerGet the current owner of an NFT from the index. Use this for quick ownership checks; use 1s_nft_owner_live for guaranteed real-time data. Filters out zero-balance holders automatically.
1s_tx_detailsGet indexed transaction details with decoded event logs. Use this for rich transaction data; use 1s_tx_details_live for unindexed or very recent transactions. Returns both the transaction and up to 100 associated events.
1s_wallet_nftsGet a wallet's complete NFT portfolio with metadata enrichment. Returns ERC721 and ERC1155 tokens with names, images, and collection info. Results sorted by most recently updated.
1s_allowance_liveCheck ERC20 token allowance (approved spending amount) via the allowance(owner,spender) RPC call. Use this before executing transferFrom or to verify approvals. Returns the allowance amount in raw token units.
1s_contract_info_liveDetect contract type and supported interfaces via eth_getCode and ERC165 supportsInterface. Use this for real-time standard detection; use 1s_contract_info for indexed metadata. Returns detected standards (ERC20, ERC721, ERC1155, ERC165).
1s_erc1155_balance_liveGet real-time ERC1155 token balance via balanceOf(address,uint256) RPC call. Use this when you need guaranteed current balance; use 1s_erc1155_balance for cached lookups. Returns the raw balance as a numeric string.
1s_erc20_balance_liveGet real-time ERC20 token balance directly from the blockchain via balanceOf. Use this for pre-transaction checks or when zero indexing delay is needed; use 1s_erc20_balance for cheaper cached lookups. Returns raw token units (divide by 10^decimals); non-standard tokens may return empty name/symbol.
1s_erc20_transfers_liveQuery ERC20 Transfer event logs via eth_getLogs. Use this for real-time transfer monitoring; use 1s_erc20_transfers for indexed transfer history. Block params are hex-encoded.
1s_erc721_tokens_liveEnumerate ERC721 tokens owned by an address via ERC721Enumerable. Only works for contracts that implement the Enumerable extension. Returns token IDs owned by the address.
1s_events_liveQuery raw event logs via eth_getLogs directly from the node. Use this for real-time or unindexed events; use 1s_events for decoded, searchable indexed events. Block params are hex-encoded (e.g. 0x1234).
1s_multi_balance_liveGet ETH and multiple ERC20 balances in a single batched RPC call. Use this to check a wallet's holdings across multiple tokens efficiently. Individual token errors are returned per-token without failing the entire request.
1s_nft_metadata_liveFetch NFT metadata directly from the blockchain via tokenURI/uri RPC call. Resolves all URI formats: ipfs://, ar://, data: URIs, bare CIDs, and ERC1155 {id} templates. Use this for freshest metadata; use 1s_nft_metadata for cached lookups.
1s_nft_owner_liveGet the current NFT owner via ownerOf(tokenId) RPC call. Use this for real-time ownership verification; use 1s_nft_owner for cached lookups. Only works for ERC721 tokens.
1s_total_supply_liveGet the total supply of an ERC20 or ERC721 token via totalSupply() RPC call. Use this for real-time supply data. Returns raw token units for ERC20 (divide by 10^decimals) or total count for ERC721.
1s_tx_details_liveGet full transaction data and receipt directly from the RPC node. Use this for very recent or unindexed transactions; use 1s_tx_details for enriched indexed data. Returns both transaction fields and receipt (status, gas used, logs).
1s_contract_codeGet the deployed bytecode of a contract via eth_getCode. Returns '0x' for EOA (non-contract) addresses. Use this to verify whether an address is a contract before interacting with it.
1s_ens_resolveResolve ENS names to addresses (forward) or addresses to ENS names (reverse). Accepts either a .eth name or a 0x address. Only works on networks with ENS registry deployed (mainnet, sepolia).
1s_estimate_gasEstimate gas required for a transaction via eth_estimateGas. Use this before sending transactions to set appropriate gas limits. Returns the estimated gas as a hex value; reverts return the revert reason.
1s_network_infoGet basic network information: chain ID, latest block number, and current gas price. Use this to verify which chain you are connected to or to check current gas conditions. Returns hex-encoded values; gas price is in wei.
1s_nonceGet the transaction count (nonce) for an address via eth_getTransactionCount. Use this to set the correct nonce when constructing transactions. Returns the count as a hex value.
1s_pending_blockGet the current pending block from the mempool. Use this to see transactions waiting for inclusion. Not all nodes expose pending block data; results vary by RPC provider.
1s_proxy_detectDetect if a contract is a proxy and read its implementation address. Checks EIP-1967 (transparent/UUPS/beacon) storage slots. Returns the proxy type, implementation address, and admin if applicable.
1s_simulate_callSimulate a contract call via eth_call without sending a transaction. Use this to preview call results, decode return data, or check for reverts before sending. Returns the raw hex result or revert reason.
1s_storage_readRead a raw storage slot from a contract via eth_getStorageAt. Use this for low-level state inspection (e.g. reading proxy implementation slots, packed storage). Slot must be a hex-encoded 32-byte value.
1s_tx_receiptGet a transaction receipt via RPC. Returns status (1=success, 0=revert), gas used, logs, and contract address if deployment. Use 1s_tx_details_live for both transaction data and receipt together.
search_docsSearch OneSource documentation by keyword. Returns the top 5 matching sections.
get_query_referenceGet full reference for a OneSource root GraphQL query — arguments, filters, return type. There are 12 root queries: address, addresses, block, blocks, contract, contracts, nft, nfts, token, tokens, transaction, transactions.
get_type_definitionGet the schema definition for a GraphQL type, enum, scalar, input, or interface. Returns fields, values, and descriptions.
list_examplesList or search working GraphQL examples. Without a topic, returns a summary of all available examples. With a topic, returns full example content matching that keyword.
list_supported_chainsList all blockchain networks supported by OneSource with endpoint URLs.
get_filter_referenceGet all filter fields and operators for a list query (e.g. transactions, tokens).
get_pagination_guideGet the cursor-based pagination pattern with examples for a list query.
get_schema_overviewGet a high-level summary of the entire GraphQL schema — all queries, types, enums, and scalars.
get_authentication_guideGet the authentication guide — API key format, endpoints, headers, and common mistakes.