1s-mcp

# @one-source/mcp

Unified MCP server for [OneSource](https://docs.onesource.io) — 30 tools for blockchain data and live chain queries in a single server.

> **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) 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

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

### Claude Desktop / Cursor

Add to your MCP config:

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

### Any MCP Client (stdio)

```bash
npx -y @one-source/mcp@latest
```

### HTTP Server (self-hosted)

```bash
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)


| 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 (13 tools)

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               |


### Payments (2 tools)


| Tool              | Description                                                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `1s_payment_mode` | View 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_refund`       | Refund unused `batch` channel balance back to your wallet on demand                                                                                           |


### Setup & Ops (3 tools)

No authentication required.


| Tool              | Purpose                                                 | When to use                                              |
| ----------------- | ------------------------------------------------------- | -------------------------------------------------------- |
| `1s_setup_check`  | Server health, version, auth status, batch-settlement status, and setup instructions | First thing to call — checks if everything is configured |
| `1s_batch_config` | View or change x402 batch-settlement preferences (autonomy, threshold, deposit multiplier, default mode) and persist them across restarts — no config editing required | Configure batch 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      |


## Networks

All blockchain API tools accept an optional `network` parameter:


| Network    | Description                |
| ---------- | -------------------------- |
| `ethereum` | Ethereum mainnet (default) |
| `sepolia`  | Ethereum Sepolia testnet   |


## Authentication

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


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


### Option 1: API Key

1. Go to [app.onesource.io](https://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

```bash
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:

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

#### Any MCP Client (stdio)

```bash
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](https://github.com/coinbase/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](https://base.org) 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](https://bridge.base.org).
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

```bash
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:

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

#### Any MCP Client (stdio)

```bash
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:


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

### 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_B