Skip to main content

Configuration

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

Environment variables​

VariableDefaultSecretDescription
ONESOURCE_API_KEY-YesBearer key from your OneSource subscription (sk_…). Primary auth mode.
X402_PRIVATE_KEY-YesEVM private key (0x…) for wallet-paid x402 access. Used if ONESOURCE_API_KEY is not set.
ONESOURCE_BASE_URLhttps://api.onesource.ioNoAPI backend URL. Change only if directed by OneSource support.
PORT3000NoHTTP server port. Only applies in --http mode. Used by hosting platforms (Railway, Fly.io).
X402_PAYMENT_MODEexactNobatch 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)NoDirectory to persist batch channel + voucher state across restarts. Recommended whenever X402_PAYMENT_MODE=batch.
X402_CHANNEL_SALT0x00…00No32-byte hex salt selecting which channel to use. Change it to open a fresh channel under the same wallet.
X402_DEPOSIT_MULTIPLIER10NoOn 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_PROMPTaskNoHow 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_THRESHOLD5NoNumber 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_URLpublic Base RPCNoCustom Base RPC endpoint. Used by batch mode for the on-chain deposit/claim reads.
ONESOURCE_CONFIG_DIR~/.onesourceNoDirectory holding the server-managed batch 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 X402_PRIVATE_KEY for wallet-paid access). 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​

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:

EndpointMethodDescription
/mcpPOSTMCP protocol handler
/healthGETReturns server status, version, and tool count
*OPTIONSCORS 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 four settings:

SettingValuesDefaultWhat it controls
modeexact / batchexactThe payment scheme the session starts in.
depositMultipliernumber ≥ 310Channel deposit = call price × this.
promptask / auto / offaskHow proactively the agent offers to switch to batch mode.
thresholdinteger > 05Anticipated call count at or above which batching is worth considering.

Call it with no arguments to see the current values and the config file path, with a patch (for example { "mode": "batch", "depositMultiplier": 20 }) to change them, or ask the assistant to reset to 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.

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.

Networknetwork valueEIP-155 chain id
Ethereum mainnetethereum (default)1 (0x1)
Sepolia testnetsepolia11155111 (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:

  1. ONESOURCE_API_KEY → Bearer mode (subscription API key).
  2. X402_PRIVATE_KEY → wallet-paid mode (signs x402 payments per call).
  3. Neither set → server starts but every paid tool call will return Payment required (402). 1s_setup_check will report Status: Not configured.

If both are set, the API key takes precedence.

MPP on Tempo is not available through the MCP server

The MCP server's only wallet-paid mode is x402 on Base (X402_PRIVATE_KEY); it has no MPP/Tempo key, env var, or code path. To pay per call with MPP on Tempo (USDC.e / pathUSD, cheaper gas, optional sessions), call the REST API directly with an MPP client (AgentCash, the Tempo CLI, or mpp-go). Inside the MCP server, x402 is the only pay-per-call option.