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:3000/` (or your `--port` value, e.g. `8080` in the second example above).

Health check: `GET http://localhost:3000/health` (substitute your port).

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


### Setup & Ops (3 tools)

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      |


## Networks

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


| Network     | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `ethereum`  | Ethereum mainnet (default)                                      |
| `sepolia`   | Ethereum Sepolia testnet                                        |
| `robinhood` | Robinhood Chain, chain 4663 (Arbitrum Orbit L2) — live-RPC only |


## Authentication

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_check` tool — 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 |


### 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` — under **Current configuration** it should report **Active auth method: API key** (with the first 6 characters of your 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`. Under **Current configuration** it lists your **x402 (Base) wallet** — the address derived from your key.
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
```

### Option 3: MPP Micropayments (Tempo)

Blockchain API endpoints can also be paid on the [Tempo](https://docs.onesource.io) 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.

1. **Get an EVM private key** — same format as x402 (64-char hex, `0x` optional). Export one or generate a fresh key.
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`. Under **Current configuration** it lists your **MPP (Tempo) wa