30 tools for blockchain data and live chain queries
This is a well-structured MCP server for blockchain data access with proper authentication mechanisms and appropriate permission scoping. The code demonstrates good security practices: credentials are handled via environment variables only (no hardcoding), sensitive data is properly redacted in logs and error messages, and dangerous operations are carefully managed. Minor code quality concerns around broad exception handling and use of `any` types do not significantly impact security. The server's permissions (network_http, env_vars) directly align with its stated purpose as a blockchain API client. Supply chain analysis found 2 known vulnerabilities in dependencies (2 critical, 0 high severity). Package verification found 1 issue.
3 files analyzed · 7 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: X402_PRIVATE_KEY
Environment variable: ONESOURCE_API_KEY
Add this to your MCP configuration file:
{
"mcpServers": {
"io-onesource-mcp": {
"env": {
"X402_PRIVATE_KEY": "your-x402-private-key-here",
"ONESOURCE_API_KEY": "your-onesource-api-key-here"
},
"args": [
"-y",
"@one-source/mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
Unified MCP server for OneSource — 30 tools for blockchain data and live chain queries in a single server.
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.
claude mcp add onesource -- npx -y @one-source/mcp@latest
Add to your MCP config:
{
"mcpServers": {
"onesource": {
"command": "npx",
"args": ["-y", "@one-source/mcp@latest"]
}
}
}
npx -y @one-source/mcp@latest
npx -y @one-source/mcp@latest --http
npx -y @one-source/mcp@latest --http --port=8080
Then connect your MCP client to http://localhost:8080/.
Health check: GET http://localhost:8080/health
| 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 |
RPC only.
| Tool | Description |
|---|---|
1s_block_by_number | Block details by number via RPC |
1s_block_number | Latest block number |
1s_chain_id | EIP-155 chain ID |
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 |
| Tool | Description |
|---|---|
1s_payment_mode | View or switch the payment rail + scheme across all four modes: x402-exact / x402-batch (USDC on Base) and mpp-charge / mpp-session (USDC.e / pathUSD on Tempo). batch and session open a channel that funds many calls. |
1s_refund | Reclaim an open payment channel's unspent deposit on demand — works for both an x402 batch channel (Base) and an MPP session voucher channel (Tempo) |
No authentication required.
| Tool | Purpose | When to use |
|---|---|---|
1s_setup_check | Interactive setup & health check. Walks the user through every configuration choice for both rails (auth method, x402, MPP, payment modes, channel prefs) one decision at a time — every run, even when already configured — plus version, auth status, channel status, and connectivity | First thing to call — to set up, change configuration, or troubleshoot |
1s_batch_config | View or change payment-channel preferences (autonomy, threshold, x402 deposit multiplier, MPP session deposit cap, default mode) and persist them across restarts — no config editing required | Configure channel behaviour from the session |
1s_report_bug | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
All blockchain API tools accept an optional network parameter:
| Network | Description |
|---|---|
ethereum | Ethereum mainnet (default) |
sepolia | Ethereum Sepolia testnet |
Blockchain API tools require authentication. Three options are available — if an API key is set alongside a wallet key, the API key takes priority and the wallet is ignored.
Tip: the fastest way to configure any of these is the
1s_setup_checktool — it walks you through every option interactively and hands you a ready-to-run command, so you never have to hand-edit env vars or config files. The manual instructions below are the reference.
| Method | Variable | Description |
|---|---|---|
| API key | ONESOURCE_API_KEY | Unlimited calls, no per-call cost |
| x402 micropayments | X402_PRIVATE_KEY | Pay-per-call via USDC on Base, no account required |
| MPP micropayments | MPP_PRIVATE_KEY | Pay-per-call via USDC.e / pathUSD on Tempo, no account required |
sk_.claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
Add the env block to your MCP config:
{
"mcpServers": {
"onesource": {
"command": "npx",
"args": ["-y", "@one-source/mcp@latest"],
"env": {
"ONESOURCE_API_KEY": "<key>"
}
}
}
}
ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
After adding, reload the MCP server and call 1s_setup_check — under Current configuration it should report Active auth method: API key (with the first 6 characters of your key).
Blockchain API endpoints are priced in USDC on Base via x402. When you set X402_PRIVATE_KEY, the server automatically handles payments — tool calls are paid and retried transparently without any extra work from the agent.
0x prefix is optional — both formats are accepted.1s_setup_check. Under Current configuration it lists your x402 (Base) wallet — the address derived from your key.1s_setup_check, on the Base network. A few dollars ($1–5 USDC) is enough for hundreds of calls. If your USDC is on Ethereum mainnet, bridge it using the Base Bridge.1s_network_info for ethereum. If it returns chain data (block number, gas price), x402 payments are working end-to-end.claude mcp add onesource -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest
Add the env block to your MCP config:
{
"mcpServers": {
"onesource": {
"command": "npx",
"args": ["-y", "@one-source/mcp@latest"],
"env": {
"X402_PRIVATE_KEY": "<key>"
}
}
}
}
X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
Blockchain API endpoints can also be paid on the Tempo network via MPP — an alternative to x402 on Base. When you set MPP_PRIVATE_KEY, the server handles payments automatically; tool calls are paid and retried transparently.
0x optional). Export one or generate a fresh key.1s_setup_check. Under Current configuration it lists your MPP (Tempo) wallet — the address derived from your key.1s_network_info. If it returns chain data, MPP payments are working end-to-end.claude mcp add onesource -e MPP_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest
{
"mcpServers": {
"onesource": {
"command": "npx",
"args": ["-y", "@one-source/mcp@latest"],
"env": {
"MPP_PRIVATE_KEY": "<key>"
}
}
}
}
MPP_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
By default MPP pays per call (mpp-charge). For a burst of calls, switch to a Tempo voucher channel with 1s_payment_mode { "mode": "mpp-session" } (or set MPP_PAYMENT_MODE=session) — one deposit funds many off-chain calls; reclaim the unspent balance any time with 1s_refund, or it settles automatically on clean shutdown.
If you prefer editing the config file directly instead of using CLI commands:
| Client | Config file path |
|---|---|
| Claude Code | Run claude mcp get onesource to see the file path |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor (macOS) | ~/.cursor/mcp.json |
| Cursor (Windows) | %USERPROFILE%\.cursor\mcp.json |
Add the onesource entry inside "mcpServers" using the JSON block shown above.
Instead of the env config block, you can set any of these variables as a shell or system environment variable: export ONESOURCE_API_KEY=<key> (bash/zsh) or $env:ONESOURCE_API_KEY = "<key>" (PowerShell). Set it at the OS level for persistence across sessions.
By default each paid call signs one payment per call (x402-exact on Base, mpp-charge on Tempo). For a burst of calls, open a payment channel — one on-chain deposit funds many off-chain calls, settled together — which is cheaper than paying per call:
x402-batch with 1s_payment_mode { "mode": "x402-batch" } (or X402_PAYMENT_MODE=batch). The first call deposits price × X402_DEPOSIT_MULTIPLIER (default 10).mpp-session with 1s_payment_mode { "mode": "mpp-session" } (or MPP_PAYMENT_MODE=session). The first call deposits up to MPP_MAX_DEPOSIT (default 1).Reclaim the unused balance any time with the 1s_refund tool (works for both rails); the residual is always recoverable on-chain. An idle x402 channel also auto-refunds after a few hours, and an MPP session settles automatically on clean shutdown.
When paying via a wallet, the agent receives channel guidance in its system prompt at startup, so it can manage this for you rather than leaving it as a manual step: when it anticipates a burst of calls it offers to switch to the channel mode for the active rail and reminds you to 1s_refund when finished. Control how proactive it is with X402_BATCH_PROMPT (ask / auto / off) and X402_BATCH_THRESHOLD (how many anticipated calls count as a burst — shared across both rails) — see Environment Variables. 1s_setup_check reports your current mode, whether the channel is available, and all settings.
Never commit keys to source control. Use environment variables, a .env file (excluded from git), or a secrets manager.
After any config change: Run
/reload-pluginsin Claude Code, or restart Claude Desktop / Cursor. The MCP server must be reloaded to pick up new environment variables.
Set one to access the blockchain API tools. Without any, only the no-auth Setup & Ops tools work. The API key takes priority when set alongside a wallet key.
| Variable | Default | Description |
|---|---|---|
ONESOURCE_API_KEY | — | OneSource API key for Bearer token auth. Takes priority over the wallet rails. |
X402_PRIVATE_KEY | — | EVM private key (64-char hex, 0x prefix optional) for automatic x402 USDC payments on Base. |
MPP_PRIVATE_KEY | — | EVM private key for automatic MPP payments (USDC.e / pathUSD) on Tempo. |
All have sensible defaults — channel modes run out of the box. Set these only to override an endpoint, tune how channel modes behave, or adjust analytics. Payment modes can also be switched at runtime with the 1s_payment_mode tool. The channel knobs below (X402_PAYMENT_MODE, X402_DEPOSIT_MULTIPLIER, MPP_PAYMENT_MODE, MPP_MAX_DEPOSIT, X402_BATCH_PROMPT, X402_BATCH_THRESHOLD) can be set and persisted from a session with the 1s_batch_config tool — no config editing or restart required; a saved config takes priority over these env vars.
| Variable | Default | Description |
|---|---|---|
ONESOURCE_BASE_URL | https://api.onesource.io | API base URL. |
X402_PAYMENT_MODE | exact | Initial x402 scheme: exact (per-call) or batch (payment channel). Switch in-session with 1s_payment_mode. |
X402_RPC_URL | Base default | Base RPC endpoint used to submit channel deposits in batch mode. |
X402_DEPOSIT_MULTIPLIER | 10 | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via 1s_refund. |
X402_CHANNEL_DIR | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
X402_CHANNEL_SALT | zero | Batch mode: 32-byte hex salt to derive the starting channel id. The client auto-rotates to the next salt when a channel is exhausted or refunded. |
MPP_PAYMENT_MODE | charge | Initial MPP scheme: charge (per-call) or session (Tempo voucher channel). Switch in-session with 1s_payment_mode. |
MPP_MAX_DEPOSIT | 1 | Session mode: max USDC.e / pathUSD locked per Tempo voucher channel. Unused balance is reclaimable via 1s_refund. |
MPP_RPC_URL | Tempo default | Tempo RPC endpoint used to submit channel deposits in session mode. |
X402_BATCH_PROMPT | ask | How the agent handles switching to a channel mode (both rails): ask (confirm before switching), auto (switch on its own), or off (only switch when explicitly asked). |
X402_BATCH_THRESHOLD | 5 | Number of anticipated calls in a session at/above which the agent considers a channel mode (both rails). Advisory — the agent estimates the call count; it is not a hard runtime counter. |
ONESOURCE_CONFIG_DIR | ~/.onesource | Directory holding the server-managed channel config (batch-config.json) written by 1s_batch_config. |
ONESOURCE_ANALYTICS | true | Set to false to disable analytics. |
ONESOURCE_ANALYTICS_URL | https://1s-analytics.vercel.app | Dashboard endpoint for analytics. |
X402_ANALYTICS_KEY | onesource-mcp | API key for dashboard analytics. |
1s_setup_check shows "Active auth method: none" (blockchain tools locked)
Under Current configuration, "Active auth method: none" means no authentication is set. Set one of ONESOURCE_API_KEY (API key), X402_PRIVATE_KEY (x402 on Base), or MPP_PRIVATE_KEY (MPP on Tempo) — or just run 1s_setup_check and let it walk you through it. Reload the MCP server after setting any variable (see note above). If the key still isn't reaching the server, set it as a shell environment variable directly.
Getting 403 / wrong key active despite correct setup
A key set in your shell profile (e.g. ~/.zshrc, ~/.bash_profile) is picked up by the MCP server process even if it isn't in your Claude MCP config. Run echo $ONESOURCE_API_KEY in your terminal to check. If it prints a value you didn't intend, unset it (unset ONESOURCE_API_KEY) or explicitly clear it when adding the server: claude mcp add onesource -e ONESOURCE_API_KEY= -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest. 1s_setup_check shows the first 6 characters of whichever key is active so you can confirm which one the server is using.
Instructions show wrong auth method after reinstall
/reload-plugins in Claude Code reconnects tools but may not refresh the system prompt the LLM sees. If you switch auth method (e.g. API key → x402), do a full Claude Code restart to ensure the instructions reflect the new auth.
"MCP server onesource already exists" error
Run claude mcp remove onesource first, then re-add with your updated config.
Windows: npx requires cmd /c wrapper
Claude Code's /doctor command may warn about this. Update your MCP config to use "command": "cmd" with "args": ["/c", "npx", "-y", "@one-source/mcp@latest"].
**npx hangs with no output**
That's normal — stdio mode waits for JSON-RPC input on stdin. Use --http if you want an HTTP server you can curl.
Port already in use
Specify a different port: npx -y @one-source/mcp@latest --http --port=8080
This package is listed on the official MCP Registry under the verified namespace io.onesource/mcp and on Glama. When releasing a new version, update both registries.
Download the installer for your platform from go.dev/dl and run it. Verify:
go version
go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest
If the Go module path has changed and the command fails, download the binary directly from the mcp-publisher GitHub releases page instead.
On Windows, add Go's bin directory to your PATH if the command isn't recognized:
$env:PATH += ";$env:USERPROFILE\go\bin"
Verify:
mcp-publisher --help
The onesource.io domain has a DNS TXT record that proves ownership of the io.onesource namespace. This is already configured — you don't need to redo it.
The record is on the root domain (onesource.io, not _mcp-registry.onesource.io):
v=MCPv1; k=ed25519; p=7D3U5rufgNXb/lH2MthTRZdDzEGeE7/Jvg8YkiArQc8=
You can verify it resolves:
nslookup -type=TXT onesource.io 8.8.8.8
Authentication requires the ed25519 private key in hex format that corresponds to the public key in the DNS record. Ask the team lead for this key — it's stored in the team's password manager / vault.
If you need to regenerate the keypair (this invalidates the current DNS record and requires updating it):
openssl genpkey -algorithm Ed25519 -out key.pem) openssl pkey -in key.pem -outform DER | tail -c 32 | xxd -p -c 32
openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
onesource.io with the new public key: v=MCPv1; k=ed25519; p=<base64-public-key>
Use the release script. Releases are normally run via the coordinated release script in the sre-services repo (
scripts/release-mcp.mjs— seesre-services/RELEASING.md), which performs all of the steps below across both@one-source/api-mcpand@one-source/mcpin the correct order, including theserver.jsonbump andmcp-publisher publish. The First-Time Setup above is still the prerequisite for the registry step. The manual steps below are the fallback for registry-only fixes or when the script can't run.
Every time you release a new npm version, update the MCP Registry:
npm run build
npm publish --access public
server.json — set both version fields to match the new npm version: {
"version": "x.y.z",
...
"packages": [{ "version": "x.y.z", ... }]
}
The mcpName field in package.json must be "io.onesource/mcp" and must match the name field in server.json. This is already set — don't remove it.
3. Authenticate (tokens expire, so do this each time):
mcp-publisher login dns --domain onesource.io --private-key <ed25519-hex-private-key>
mcp-publisher publish
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=onesource"
Glama auto-syncs from the GitHub repo daily. No manual steps needed after a release — just make sure changes are pushed to main. The glama.json file in the repo root controls ownership. Manual re-sync is available from the Glama admin panel after claiming the server.
Apache 2.0 — see LICENSE for details.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.