/etherscan-mcp-skill

name: etherscan-mcp-skill
description: Use Etherscan MCP through UXC for address balance checks, token holder analysis, transaction inspection, and contract lookup tasks. Use when tasks need Etherscan MCP tools for onchain investigation with help-first schema inspection, bearer-key auth, and tier-aware read-first handling.

Etherscan MCP Skill

Use this skill to run Etherscan MCP operations through `uxc`.

Reuse the `uxc` skill for shared protocol discovery, output parsing, and generic auth/binding flows.

Prerequisites

• `uxc` is installed and available in `PATH`.
• Network access to `https://mcp.etherscan.io/mcp`.
• An Etherscan API key is available for authenticated calls.

Core Workflow

1. Confirm endpoint and protocol with help-first probing:

• `uxc https://mcp.etherscan.io/mcp -h`
• expected unauthenticated behavior today: `401 Unauthorized`

2. Configure credential/binding for repeatable auth:

• `uxc auth credential set etherscan-mcp --auth-type bearer --secret-env ETHERSCAN_API_KEY`
• `uxc auth credential set etherscan-mcp --auth-type bearer --secret-op op://Engineering/etherscan/api-key`
• `uxc auth binding add --id etherscan-mcp --host mcp.etherscan.io --path-prefix /mcp --scheme https --credential etherscan-mcp --priority 100`

3. Use fixed link command by default:

• `command -v etherscan-mcp-cli`
• If missing, create it: `uxc link etherscan-mcp-cli https://mcp.etherscan.io/mcp`
• `etherscan-mcp-cli -h`

4. Inspect operation schema before execution:

• `etherscan-mcp-cli balance -h`
• `etherscan-mcp-cli tokenTopHolders -h`
• `etherscan-mcp-cli getContractAbi -h`
• `etherscan-mcp-cli transaction -h`

5. Prefer read operations first, then any workflow that could trigger heavy data pulls or follow-up automation.

Capability Map

• Address investigation:
• `balance`
• `tokenHoldings`
• `fundedBy`
• `getAddressMetadata`
• Token holder analysis:
• `balanceERC20`
• `balanceERC20Historical`
• `tokenTopHolders`
• `getTokenInfo`
• Transaction investigation:
• `txList`
• `internalTxsByAddress`
• `erc20Transfers`
• `erc721Transfers`
• `erc1155Transfers`
• `transaction`
• `checkTransaction`
• Contract research:
• `getContractAbi`
• `getContractSourceCode`
• `getContractCreation`
• Verification:
• `verifySourceCode`
• `checkVerifyStatus`

Inspect `etherscan-mcp-cli -h` after auth setup for the current full tool list. Etherscan can expand MCP tools independently of this wrapper skill.

Recommended Usage Pattern

1. Start from a read-only investigation goal:

• balance or holdings for an address
• holder concentration for a token
• transaction inspection for a hash
• source/metadata lookup for a contract

2. Run `-h` on the specific tool before the first real call. 3. Prefer one chain/address/token at a time before broadening the scope. 4. Parse the JSON envelope first, then inspect `data`.

Guardrails

• Keep automation on JSON output envelope; do not rely on `--text`.
• Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.
• Use `etherscan-mcp-cli` as default command path.
• `etherscan-mcp-cli <operation> ...` is equivalent to `uxc https://mcp.etherscan.io/mcp <operation> ...`.
• If unauthenticated probe or runtime call returns `401 Unauthorized`:
• confirm auth binding matches endpoint with `uxc auth binding match https://mcp.etherscan.io/mcp`
• confirm credential shape with `uxc auth credential info etherscan-mcp`
• reset credential as bearer if needed: `uxc auth credential set etherscan-mcp --auth-type bearer --secret-env ETHERSCAN_API_KEY`
• Use `key=value` only for simple scalar inputs.
• Prefer positional JSON when an operation accepts nested objects, arrays, or optional flags that may evolve.
• Do not assume tool argument names from memory; inspect `<operation> -h` first because Etherscan may revise MCP schemas independently of this skill.
• Some MCP tools are tier-gated by Etherscan plan. Today `getTokenInfo` can return `NOTOK` with an API Pro upgrade message on non-Pro keys.
• Treat `verifySourceCode` as a write-like action requiring explicit user confirmation.

References

• Invocation patterns:
• `references/usage-patterns.md`