1s-mcp

# @one-source/mcp

Unified MCP server for [OneSource](https://docs.onesource.io) — 83 tools for blockchain data, live chain queries, Deepstate market data, The Standard Reserve, and REST API documentation 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 (83)

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


### Deepstate Market Data (8 tools)

Deepstate is an on-chain order-book protocol on Robinhood Chain (chain 4663). These tools read market data — order books, trades, candles, stats, maker analytics, and gas/depth analytics. They're ordinary tools on the same API and take no `network` parameter — always Robinhood Chain — and are paid like every other tool: API key, x402, or MPP.


| Tool                    | Description                                                                                          |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `1s_ds_markets`         | List the Deepstate markets (order books) this API serves, with each market's slug, token layout, and pool/router addresses |
| `1s_ds_book`            | Order-book snapshot for a market — bids descending, asks ascending, with each price level's resting size |
| `1s_ds_trades`          | Trade tape for a market, newest first — each fill's price, size, side, and block                     |
| `1s_ds_candles`         | OHLCV candles for a market at a given timeframe                                                       |
| `1s_ds_stats`           | Rolling 24h / 7d / 30d volume and price change for a market, plus the latest traded price             |
| `1s_ds_makers`          | Per-maker analytics for a market — time at top of book, resting notional, fill count/rate, and DEEP rewards |
| `1s_ds_cost_to_quote`   | Gas spent resting and cancelling orders on a market, bucketed over time                                |
| `1s_ds_depth_history`   | Depth heatmap for a market — resting order size by price level over time                              |

Every Deepstate tool except `1s_ds_markets` takes a `book` parameter: the market's canonical uppercase slug (e.g. `NVDA-USDG`) or its 32-byte `book_id`. Call `1s_ds_markets` first for the full list.


### The Standard Reserve (37 tools)

The Standard Reserve is an on-chain central-bank protocol on Robinhood Chain (chain id 4663). These tools read the deployed contracts' state as indexed and served by OneSource, with `basis`, `as_of_block`, and `serving_state` on every response. `1s_std_addresses` and `1s_std_genesis_live` are free; every other tool here is paid the same way as the rest of this API: API key, x402, or MPP. Several tools (`1s_std_supply`, `_vaults`, `_pool`, `_exit_pressure`, `_backing`, `_policy_current`) also take an `atBlock` param to read that state as of a past block instead of the latest one.


| Tool                        | Description                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `1s_std_addresses`          | Verified registry of TSR contracts and pool, with a verification status per entry. Free, no payment required. |
| `1s_std_auction_days`       | Per-day auction history for the license or charter auction: open/floor/close price, sold vs. offered, time to sell out |
| `1s_std_auction_sales`      | Recent sales for the license or charter auction, newest first: buyer, unit price, count, and block. Filter by kind, page with before/limit |
| `1s_std_auctions_current`   | Current state of the daily license auction and charter auction: price, floor, sold/remaining today, phase, and last sale |
| `1s_std_backing`            | Reserve backing: vault ETH balances, unpriced reserve-asset holdings, and ETH-per-STANDARD backing ratio (excluding and including protocol-owned liquidity). Current, history, or as of a past block |
| `1s_std_branch_auction_live`| Raw head-fresh state of the Branch license auction: phase, price, today's sold/remaining counts, and recent sale velocity |
| `1s_std_branches_doi`       | Days of Issuance for the Branch license auction, plus a buy-now-vs-wait table                          |
| `1s_std_branches_summary`   | Summary across TSR's active Branches: count, issuance per Branch per day, and license price in days of issuance |
| `1s_std_buyback_readiness`  | Contraction-vault buyback-tick readiness: this tick's ETH capacity, binding constraint, cooldown, TWAP deviation, and recent executed ticks |
| `1s_std_candles`            | OHLC price candles for the ETH/STANDARD pool in ETH per STANDARD, with swap counts and volume. Set tf for candle width (1m to 1d) and from/to for the window |
| `1s_std_charter`            | One charter by id, or charters filtered by owner: holder, branch count, mint kind, owed production, and branch history |
| `1s_std_decision_branch`    | Composite: should I buy a Branch/license right now. Bundles Days of Issuance, license cost vs. the charter auction, recent auction history, policy outlook, and pending governance changes |
| `1s_std_decision_charter`   | Composite: should I buy into a new charter right now. Bundles charter-auction state, license-cost cheapest path, Days of Issuance, backing ratio, and holder concentration |
| `1s_std_decision_exit`      | Composite: should I exit a charter's branches right now. Bundles the exit quote, fee curve, fee forecast, tax schedule, pool state, policy outlook, and pending governance changes |
| `1s_std_decision_plan`      | Simulate three Branch-buying strategies (keep, selective, aggressive) over a horizon, seeded from live prices, issuance, and license cost unless overridden. A planning tool, not a forecast: it never names a winning strategy |
| `1s_std_dormancy`           | Wallets past their reportable dormancy window, or the full tracked wallet list                        |
| `1s_std_dormancy_bounties`  | Dormancy bounty board: wallets already past their reportable window, ranked by estimated bounty        |
| `1s_