Configuration

Reference for everything you can configure on @one-source/mcp. See the install guide for the basic setup.

Environment variables

Variable	Default	Secret	Description
`ONESOURCE_API_KEY`	-	Yes	Bearer key from your OneSource subscription (`sk_…`). Primary auth mode.
`X402_PRIVATE_KEY`	-	Yes	EVM private key (`0x…`) for wallet-paid x402 access (USDC on Base). Used when `ONESOURCE_API_KEY` is not set.
`MPP_PRIVATE_KEY`	-	Yes	EVM private key (`0x…`) for wallet-paid MPP access (USDC.e / pathUSD on Tempo). Used when `ONESOURCE_API_KEY` is not set. If both wallet keys are set, x402 is the initial rail; switch with `1s_payment_mode`.
`ONESOURCE_BASE_URL`	`https://api.onesource.io`	No	API backend URL. Change only if directed by OneSource support.
`PORT`	`3000`	No	HTTP server port. Only applies in `--http` mode. Used by hosting platforms (Railway, Fly.io).
`ONESOURCE_PAYMENT_MODE`	rail default	No	Initial rail + scheme: `x402-exact`, `x402-batch`, `mpp-charge`, or `mpp-session`. Falls back to the enabled rail's own default. Switch in-session with `1s_payment_mode`.
`X402_PAYMENT_MODE`	`exact`	No	`batch` opens a payment channel (one deposit funds many calls); `exact` settles per call. Only applies in x402 mode. See Batch settlement.
`X402_CHANNEL_DIR`	- (in-memory)	No	Directory to persist batch channel + voucher state across restarts. Recommended whenever `X402_PAYMENT_MODE=batch`.
`X402_CHANNEL_SALT`	`0x00…00`	No	32-byte hex salt selecting which channel to use. Change it to open a fresh channel under the same wallet.
`X402_DEPOSIT_MULTIPLIER`	`10`	No	On channel open, deposit `price × this` (minimum 3), funding that many calls before a top-up. Higher means fewer re-deposits but more USDC locked up front. Any unused balance is reclaimable via the `1s_refund` tool or the gateway's idle auto-refund.
`X402_BATCH_PROMPT`	`ask`	No	How proactively the agent offers to switch to batch mode: `ask` (confirm with you first), `auto` (switch on its own), or `off` (only when you ask). Only applies in x402 mode.
`X402_BATCH_THRESHOLD`	`5`	No	Number of anticipated calls in a session at or above which the agent considers batch mode. Advisory: the agent estimates the count, it is not a hard runtime counter.
`X402_RPC_URL`	public Base RPC	No	Custom Base RPC endpoint. Used by batch mode for the on-chain deposit/claim reads.
`MPP_PAYMENT_MODE`	`charge`	No	Initial MPP scheme: `charge` (one payment per call) or `session` (voucher channel). Only applies in MPP mode. See MPP settlement.
`MPP_MAX_DEPOSIT`	`1`	No	`mpp-session`: the channel deposit, in token units (flat, not scaled by call price). Bounds the worst-case balance locked if the server is killed before it settles. Any unused balance is reclaimable via the `1s_refund` tool. Also settable live via `1s_batch_config`.
`MPP_RPC_URL`	public Tempo RPC	No	Custom Tempo RPC endpoint. Used by `mpp-session` to open and settle the channel (`mpp-charge` needs no RPC).
`ONESOURCE_CONFIG_DIR`	`~/.onesource`	No	Directory holding the server-managed payment config (`batch-config.json`) that `1s_batch_config` reads and writes.

The only variable you ever have to set yourself is the credential, ONESOURCE_API_KEY (or a wallet key: X402_PRIVATE_KEY for x402 on Base, or MPP_PRIVATE_KEY for MPP on Tempo). Everything else has a working default. The four batch knobs (X402_PAYMENT_MODE, X402_DEPOSIT_MULTIPLIER, X402_BATCH_PROMPT, X402_BATCH_THRESHOLD) don't need to be set as env vars at all: your assistant can set and persist them in-session with the 1s_batch_config tool. For each of those four, a value saved by 1s_batch_config takes priority over the env var, which in turn beats the built-in default.

Setting environment variables

Let the server configure itself

You rarely need to set these by hand. Once the server is installed with any credential, run the 1s_setup_check tool: it walks you through every option interactively, applies what it can live (rail, scheme, batch knobs), and hands you a single ready-to-run command for anything that needs a restart, without echoing secrets or editing config files. The manual reference below is for the initial install and for self-hosted (--http) deployments.

How you pass env vars depends on your MCP client:

Claude Code:

claude mcp add onesource -e ONESOURCE_API_KEY=sk_… -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor / Windsurf:

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

VS Code:

{
  "servers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"],
      "env": { "ONESOURCE_API_KEY": "sk_…" }
    }
  }
}

Shell (for --http mode or testing):

ONESOURCE_API_KEY=sk_… npx -y @one-source/mcp@latest

Transport modes

Stdio (default)

The standard mode used by every MCP client. The server reads from stdin, writes to stdout, and runs for the lifetime of the session.

ONESOURCE_API_KEY=sk_… npx -y @one-source/mcp@latest

No additional flags: this is what every client-specific guide sets up.

HTTP (self-hosted)

For remote deployments, shared servers, or clients that support HTTP transport.

ONESOURCE_API_KEY=sk_… npx -y @one-source/mcp@latest --http
ONESOURCE_API_KEY=sk_… npx -y @one-source/mcp@latest --http --port=8080

Endpoints:

Endpoint	Method	Description
`/mcp`	POST	MCP protocol handler
`/health`	GET	Returns server status, version, and tool count
`*`	OPTIONS	CORS preflight (allows cross-origin requests)

Port priority: PORT env var → --port flag → default 3000.

Health check:

curl http://localhost:3000/health

Notes:

HTTP mode is stateless: each request gets a fresh server instance.
The server binds to 0.0.0.0 for deployment compatibility.
CORS is enabled for all origins.

Batch settlement (payment channels)

In x402 mode, the server can pay through a payment channel instead of settling every call on-chain: one deposit funds many off-chain signed vouchers, which OneSource redeems in batched on-chain claims. For a burst of calls this amortizes settlement gas. See x402 on Base → Batch settlement for the model, and Build an x402 batch-settlement client for the equivalent standalone client.

Start in batch mode, or flip it mid-session with the 1s_payment_mode tool:

X402_PRIVATE_KEY=0x… X402_PAYMENT_MODE=batch X402_CHANNEL_DIR=./channel-storage \
  npx -y @one-source/mcp@latest

Requires the long-lived stdio transport (the default). The --http transport is stateless (each request gets a fresh server instance), so it cannot hold channel state; batch mode there falls back to per-call behavior.
Set X402_CHANNEL_DIR to persist the channel across restarts. Without it, channel state lives only in the running process and is lost on exit.
The first paid call opens the channel with one on-chain deposit (price × X402_DEPOSIT_MULTIPLIER, default 10), so a session usually over-funds the channel.
Reclaim the unused deposit with the 1s_refund tool when you're done making batch calls: it returns the full remaining channel escrow to your wallet on Base right away. Idle channels are also auto-refunded by the gateway after a few hours, so the residual is always recoverable; 1s_refund just gets it back immediately instead of waiting.

Configure batch behavior from your assistant

Tuning batch mode used to mean editing your MCP client config and restarting. It no longer does: the 1s_batch_config tool lets your assistant read and change the batch preferences in-session, and persists them to a server-owned file (batch-config.json under ONESOURCE_CONFIG_DIR, default ~/.onesource) so they survive restarts without touching the client config.

1s_batch_config covers these settings:

Setting	Values	Default	What it controls
`mode`	`x402-exact` / `x402-batch` / `mpp-charge` / `mpp-session`	rail default	The default rail + scheme the session starts in. Also switched live when that rail is active.
`deposit_multiplier`	number ≥ 3	`10`	x402 channel deposit = call price × this.
`mpp_max_deposit`	token amount	`1`	`mpp-session` channel deposit, in tokens (flat, not scaled by call price).
`prompt`	`ask` / `auto` / `off`	`ask`	How proactively the agent offers to switch to a channel mode.
`threshold`	integer > 0	`5`	Anticipated call count at or above which a channel mode is worth considering.

Call it with no arguments to see the current values and the config file path, with a patch (for example { "mode": "x402-batch", "deposit_multiplier": 20 }) to change them, or pass { "reset": true } to restore defaults (which deletes the file and falls back to env vars, then built-in defaults). A saved value takes priority over the matching env var. To switch the live payment scheme for the current session without persisting a default, use 1s_payment_mode instead.

In x402 mode the agent receives batch guidance in its system prompt at startup, scaled by prompt and threshold: when it anticipates a burst of calls it can offer (or, on auto, perform) the switch to batch mode and remind you to 1s_refund when finished. 1s_setup_check reports your current mode, whether batch is available, and both settings.

MPP settlement (Tempo)

With MPP_PRIVATE_KEY set, the server pays per call over MPP on Tempo instead of x402 on Base. MPP settles in USDC.e or pathUSD, and Tempo gas is materially cheaper than Base. It has two schemes, switchable mid-session with 1s_payment_mode:

mpp-charge (default): one signed Tempo payment per call. Simplest; needs no RPC.
mpp-session: a voucher channel. The first call opens an on-chain channel for a flat deposit, MPP_MAX_DEPOSIT (default 1 token, not scaled by call price), then subsequent calls are signed off-chain as cumulative vouchers and settled together. Materially cheaper for a burst of calls.

Start in a given mode, or flip it mid-session with 1s_payment_mode:

MPP_PRIVATE_KEY=0x… MPP_PAYMENT_MODE=session npx -y @one-source/mcp@latest

The unspent mpp-session deposit is settled and reclaimed automatically when the server shuts down cleanly (SIGINT / SIGTERM), and you can also reclaim it on demand any time with the 1s_refund tool. 1s_refund is rail-neutral: it returns the remaining escrow of an open x402 batch channel on Base or an mpp-session channel on Tempo. A hard kill before either settles leaves the deposit locked on-chain until reclaimed later, so MPP_MAX_DEPOSIT bounds the worst case.
Like x402 batch mode, mpp-session needs the long-lived stdio transport to hold channel state; under stateless --http it falls back to per-call (mpp-charge) behavior.
x402 and MPP are separate rails with separate wallets (USDC on Base vs USDC.e / pathUSD on Tempo). If both keys are set, x402 is the initial rail, and 1s_payment_mode switches between all four schemes.

Networks

The OneSource REST API runs against Ethereum mainnet and the Sepolia testnet. Every chain tool takes an optional network argument; it defaults to ethereum. Pass network: "sepolia" on any call to target Sepolia instead.

Network	`network` value	EIP-155 chain id
Ethereum mainnet	`ethereum` (default)	`1` (`0x1`)
Sepolia testnet	`sepolia`	`11155111` (`0xaa36a7`)

1s_list_networks returns the current list, and /api/chain/network-info reports it live. Additional networks land here as OneSource expands its coverage.

Auth precedence

The server picks an auth mode at startup using this order:

ONESOURCE_API_KEY → Bearer mode (subscription API key).
X402_PRIVATE_KEY → wallet-paid mode, x402 on Base (USDC).
MPP_PRIVATE_KEY → wallet-paid mode, MPP on Tempo (USDC.e / pathUSD).
None set → server starts but every paid tool call returns Payment required (402). 1s_setup_check reports Status: Not configured.

The API key always takes precedence over a wallet key. If both X402_PRIVATE_KEY and MPP_PRIVATE_KEY are set, x402 is the initial rail; switch to MPP in-session with 1s_payment_mode.

Wallet-paid modes are for the server you run yourself

Both wallet rails sign payments from a single private key the server holds, so they apply to the local (stdio) or self-hosted server you run. A shared, multi-tenant deployment holds no wallet and authenticates each request with a Bearer API key instead.

Environment variables​

Setting environment variables​

Transport modes​

Stdio (default)​

HTTP (self-hosted)​

Batch settlement (payment channels)​

Configure batch behavior from your assistant​

MPP settlement (Tempo)​

Networks​

Auth precedence​