convez.ai
MCP Server
blockparty-global

1s-mcp

blockparty-global/1s-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server with 29 tools for block chain data — token lookups, wallet balances,live chain queries across 10+ networks using micro payment on x402, and full API documentation search.

Instalação

$npx convez-ai blockparty-global/1s-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
37%
Último commit
há 6 dias
Versão
—
Issues abertas
5
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

@one-source/mcp

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.

Quick Start

Claude Code

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

Claude Desktop / Cursor

Add to your MCP config:

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

Any MCP Client (stdio)

npx -y @one-source/mcp@latest

HTTP Server (self-hosted)

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

Tools (30)

Blockchain API — Live Chain (12 tools)

ToolDescription
1s_allowance_liveERC20 allowance check
1s_contract_info_liveContract type detection via ERC165
1s_erc1155_balance_liveERC1155 balance via RPC
1s_erc20_balance_liveERC20 balance via balanceOf
1s_erc20_transfers_liveERC20 Transfer logs via eth_getLogs
1s_erc721_tokens_liveERC721 token enumeration
1s_events_liveEvent logs via eth_getLogs
1s_multi_balance_liveETH + multiple ERC20 balances
1s_nft_metadata_liveNFT metadata via tokenURI
1s_nft_owner_liveNFT owner via ownerOf
1s_total_supply_liveToken total supply
1s_tx_details_liveTransaction + receipt via RPC

Blockchain API — Chain Utilities (13 tools)

RPC only.

ToolDescription
1s_block_by_numberBlock details by number via RPC
1s_block_numberLatest block number
1s_chain_idEIP-155 chain ID
1s_contract_codeContract bytecode
1s_ens_resolveENS name/address resolution
1s_estimate_gasGas estimation
1s_network_infoChain ID, block number, gas price
1s_nonceTransaction count
1s_pending_blockPending block from mempool
1s_proxy_detectProxy contract detection
1s_simulate_callSimulate eth_call
1s_storage_readRead storage slot
1s_tx_receiptTransaction receipt

Payments (2 tools)

ToolDescription
1s_payment_modeView or switch the x402 payment scheme — exact (per-call) vs batch (payment channel: one deposit funds many off-chain calls, settled with a single claim)
1s_refundRefund unused batch channel balance back to your wallet on demand

Setup & Ops (3 tools)

No authentication required.

ToolPurposeWhen to use
1s_setup_checkServer health, version, auth status, batch-settlement status, and setup instructionsFirst thing to call — checks if everything is configured
1s_batch_configView or change x402 batch-settlement preferences (autonomy, threshold, deposit multiplier, default mode) and persist them across restarts — no config editing requiredConfigure batch behaviour from the session
1s_report_bugReport bugs to Slack (or GitHub Issues fallback)When a tool errors or user wants to report an issue

Networks

All blockchain API tools accept an optional network parameter:

NetworkDescription
ethereumEthereum mainnet (default)
sepoliaEthereum Sepolia testnet

Authentication

Blockchain API tools require authentication. Two options are available — if both are set, API key takes priority.

MethodVariableDescription
API keyONESOURCE_API_KEYUnlimited calls, no per-call cost
x402 micropaymentsX402_PRIVATE_KEYPay-per-call via USDC on Base, no account required

Option 1: API Key

  1. Go to app.onesource.io and create an account.
  2. Subscribe to a developer plan (Stripe checkout).
  3. Navigate to API Keys and generate a key.
  4. Copy the key — it starts with sk_.

Claude Code

claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor

Add the env block to your MCP config:

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"],
      "env": {
        "ONESOURCE_API_KEY": "<key>"
      }
    }
  }
}

Any MCP Client (stdio)

ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest

After adding, reload the MCP server and call 1s_setup_check — it should show Status: Configured (API key).

Option 2: x402 Micropayments

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.

  1. Get an EVM private key — export one from MetaMask, Coinbase Wallet, or any EVM wallet, or generate a fresh one. The key is a 64-character hex string. The 0x prefix is optional — both formats are accepted.
  2. Pass the key to the server using one of the methods below.
  3. Reload and find your wallet address — reload the MCP server, then call 1s_setup_check. It will show the wallet address derived from your key under "Wallet address".
  4. Fund that address with USDC on Base — send USDC to the address shown in 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.
  5. Verify — call 1s_network_info for ethereum. If it returns chain data (block number, gas price), x402 payments are working end-to-end.

Claude Code

claude mcp add onesource -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor

Add the env block to your MCP config:

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"],
      "env": {
        "X402_PRIVATE_KEY": "<key>"
      }
    }
  }
}

Any MCP Client (stdio)

X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest

Config File Locations

If you prefer editing the config file directly instead of using CLI commands:

ClientConfig file path
Claude CodeRun 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.

Alternative: Set as an Environment Variable

Instead of the env config block, you can set either variable 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.

Batch payments (optional)

By default each paid call signs one USDC payment (exact). For a burst of calls, switch to a batch payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling 1s_payment_mode with { "mode": "batch" } (or setting X402_PAYMENT_MODE=batch). The first batch call deposits price × X402_DEPOSIT_MULTIPLIER (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the 1s_refund tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.

When paying via x402, the agent receives batch guidance in its system prompt at startup, so it can manage this for you rather than leaving batching as a manual step: when it anticipates a burst of calls it offers to switch to batch mode 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) — see Environment Variables. 1s_setup_check reports your current mode, whether batch is available, and both settings.

Security

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-plugins in Claude Code, or restart Claude Desktop / Cursor. The MCP server must be reloaded to pick up new environment variables.

Environment Variables

Required

Set one to access the blockchain API tools. Without either, only the no-auth Setup & Ops tools work. API key takes priority when both are set.

VariableDefaultDescription
ONESOURCE_API_KEY—OneSource API key for Bearer token auth. Takes priority over x402.
X402_PRIVATE_KEY—EVM private key (64-char hex, 0x prefix optional) for automatic x402 USDC payments on Base.

Optional / Advanced

All have sensible defaults — batch mode runs out of the box. Set these only to override an endpoint, tune how batch mode behaves, or adjust analytics. Payment modes can also be switched at runtime with the 1s_payment_mode tool. The batch knobs below (X402_PAYMENT_MODE, X402_DEPOSIT_MULTIPLIER, 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.

VariableDefaultDescription
ONESOURCE_BASE_URLhttps://api.onesource.ioAPI base URL.
X402_PAYMENT_MODEexactInitial x402 scheme: exact (per-call) or batch (payment channel). Switch in-session with 1s_payment_mode.
X402_RPC_URLBase defaultBase RPC endpoint used to submit channel deposits in batch mode.
X402_DEPOSIT_MULTIPLIER10Batch 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_SALTzeroBatch 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.
X402_BATCH_PROMPTaskHow the agent handles switching to batch mode: ask (confirm before switching), auto (switch on its own), or off (only switch when explicitly asked).
X402_BATCH_THRESHOLD5Number of anticipated calls in a session at/above which the agent considers batch mode. Advisory — the agent estimates the call count; it is not a hard runtime counter.
ONESOURCE_CONFIG_DIR~/.onesourceDirectory holding the server-managed batch config (batch-config.json) written by 1s_batch_config.
ONESOURCE_ANALYTICStrueSet to false to disable analytics.
ONESOURCE_ANALYTICS_URLhttps://1s-analytics.vercel.appDashboard endpoint for analytics.
X402_ANALYTICS_KEYonesource-mcpAPI key for dashboard analytics.

Troubleshooting

**1s_setup_check shows "Not configured"** Set either ONESOURCE_API_KEY or X402_PRIVATE_KEY. Reload the MCP server after setting either 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

Registry Publishing

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.

MCP Registry

First-Time Setup

1. Install Go

Download the installer for your platform from go.dev/dl and run it. Verify:

go version
2. Install mcp-publisher
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
3. DNS Authentication (already done)

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
4. Get the Private Key

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):

  1. Generate a new ed25519 keypair (e.g., openssl genpkey -algorithm Ed25519 -out key.pem)
  2. Extract the raw 32-byte private key seed and convert to hex:
 openssl pkey -in key.pem -outform DER | tail -c 32 | xxd -p -c 32
  1. Extract the public key in base64 for the DNS TXT record:
 openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
  1. Update the DNS TXT record on onesource.io with the new public key:
 v=MCPv1; k=ed25519; p=<base64-public-key>
  1. Wait for DNS propagation before attempting to log in.

Publishing a New Version

Use the release script. Releases are normally run via the coordinated release script in the sre-services repo (scripts/release-mcp.mjs — see sre-services/RELEASING.md), which performs all of the steps below across both @one-source/api-mcp and @one-source/mcp in the correct order, including the server.json bump and mcp-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:

  1. Publish to npm (the registry validates the package exists, so this must happen first):
 npm run build
 npm publish --access public
  1. Update 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>
  1. Publish to the registry:
 mcp-publisher publish
  1. Verify:
 curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=onesource"

Glama

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.

License

Apache 2.0 — see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados