Download

MCP Passthrough · Documentation

CLI Reference

Operator commands, flags, settings, and their effects.

For plugin v0.29.3 on eiou-docker v0.1.21-alpha. Plugin & downloads · Alpha pilot

Operate MCP Passthrough v0.29.3 from an eIOU node’s shell: configure inference providers, admit customers, inspect routing and manage balances. For the sequence that gets a node working, start with Setup and Provider access. The GUI guide covers the corresponding panel controls.

Contents

Running commands

Run eiou mcp-passthrough ... inside the eIOU container. From its Docker host, prefix it with docker exec <node-container>:

docker exec <node-container> eiou mcp-passthrough status
docker exec <node-container> eiou mcp-passthrough help

Replace angle-bracket placeholders before running a command; they are not literal shell arguments. The tables below omit the common eiou mcp-passthrough prefix. Flags require --name=value; --name value is not accepted. Quote labels, contact names and prompts containing spaces.

Configuration commands change the node immediately. deal, peers warm and refund can move eIOU value. Enabling automatic routing permits later requests and background maintenance to fund sellers. Read commands such as status, routing explain, usage and key list do not buy inference.

Use the panel to enter provider secrets when possible: --token=... can expose them in shell history and process arguments. Customer tokens are shown once at creation; listings never recover them. Operator CLI access is separate from the customer bearer key used by an MCP client.

Status and providers

Command Behavior
help or no command Print built-in command help. See release limitations below for differences from the implementation.
status Active provider/model, settlement currency and key count.
provider list Configured provider IDs, presets, endpoints, token presence and model count.
provider configure <id> --preset=<preset> --endpoint=<url> Create or update a provider. Also accepts --label=<label> and --token=<token>. Omitted fields retain existing values; an empty token also preserves it. --clear-token=1 explicitly removes the saved token.
provider test <id> Contact the configured upstream and test its connection. This is not a complete inference or billing test.
provider models <id> Fetch and save discovered models. New hosted-provider models start disabled; Ollama models require a capability check before enabling.
provider probe <id> <model> Run and save an Ollama capability check. This actually runs a small inference probe and may select the model when the previous active model is unavailable.
provider use <id> [model] Select the active provider and optional model. A new model ID creates a default enabled row with 25% markup; configure actual rates before serving it. A newly added Ollama row starts with its capability check pending and cannot serve inference until that check passes. Selecting a row is not proof that it is available.
provider model-price <id> <model> [flags] Update an existing model’s pricing and optional enabled state. These rates are also advertised to contacts.

provider model-price flags:

Flag Meaning
--mode=markup Set upstream cost rates and add --markup=<percentage> to compute the customer rate.
--mode=manual Set customer rates directly; upstream bookkeeping costs remain separate.
--in=<rate> Input price per 1 million tokens, in the node’s settlement currency. In markup mode this is the cost; in manual mode it is the customer rate.
--out=<rate> Output rate on the same basis.
--xfer=<rate> Transfer rate per GiB, on the same cost/customer basis.
--enabled=1 / --enabled=0 Enable or disable the model.

Omitted price flags preserve the current values for the selected pricing mode. In this release, invalid or negative numeric rate input becomes zero; verify the printed rates after changing them. Rates here must already be in the settlement currency: this command does not perform currency conversion.

A provider configured on your node may be an online API; “local provider” in routing means locally configured, not necessarily locally executed. Our hosted pilot servers use remote inference and do not run Ollama or other local-model sidecars.

Customer keys

Command Behavior
key create <label> --contact=<accepted-name-or-hash> [flags] Mint a zero-prepaid-balance customer key bound to an accepted contact. Prints its ID, expiry and once-only bearer token.
key list IDs, labels, balances, currencies, contact bindings, expiry and revoked/expired state.
key quota <id> <tokens> <window-seconds> Set a token allowance over a rolling window. Both numbers must be positive integers. Existing usage inside the window counts.
key quota <id> 0 0 Explicitly remove the token quota. Supplying only one value or one zero is rejected.
key revoke <id> Revoke the key. This does not refund its remaining balance.

Creation flags:

  • --contact=<name-or-pubkey-hash> identifies an accepted contact on this node. Required in default pilot federation mode. Owning the node does not create a self-use key or a self-contact; arrange the billing contact as described in Setup.
  • --pubkey=<PEM> or --pubkey-hash=<hash> binds inbound sender payments for automatic top-up matching. The hash flag takes precedence if both are given. Without either, the accepted contact’s hash is used. This funding binding and admission to the node are related but distinct.
  • --ttl=<lifetime> accepts positive <n>d, <n>h, <n>m, or bare days, up to 366 days. Omitted TTL uses key_default_ttl; if both are blank the key has no expiry. 0 is not a valid explicit TTL.

There is no CLI --currency override: keys use the node’s settlement currency. A key needs sufficient prepaid balance or available credit extended to its bound contact before billed calls can proceed. A funded customer key alone does not fund your node’s separate purchases from network sellers.

The creation output gives mcp-topup:<key-id> for an inbound eIOU payment’s description. Use the actual ID from that node. See Provider access for the separate customer and seller funding relationships.

Usage and refunds

Command Behavior
usage [--limit=<count>] [--key=<id>] Recent usage records as one JSON object per line. Default 50; stored query limit clamps to 1–500.
topups [--limit=<count>] [--key=<id>] Recorded inbound top-ups, with the same filtering and limits.
refund <inbound-txid> [--amount=<amount>] Return a recorded top-up to its original sender through the wallet’s refund service, and debit the corresponding key.

A refund is a real wallet operation and needs the wallet_refund_return_to_sender permission. The default is the full original top-up amount. An explicit amount must be positive, no greater than the original top-up, and covered by the key’s remaining balance. This version marks the top-up refunded even for a partial amount, so it cannot be refunded again through this command. It does not accept an arbitrary destination.

Directory and routing

Command Behavior
directory sync Pull contact catalogs now and persist the learned directory. The manifest schedules this every 10 minutes; a bounded pass may continue across later runs. It does not buy inference.
routing status or routing Effective mode, ranking, limits, today’s UTC spend, funding target and managed peer count. Pending payments may not yet include final routing fees.
routing enable Set mode to auto. Later calls may select and fund network sellers.
routing disable Set mode to manual: use the active configured provider, without automatic alternatives.
routing policy <policy> Accepts local_first, cheapest_advertised, or manual. Does not itself turn automatic routing on.
routing explain [model] Dry-run route selection. Prints estimates, readiness and rejected candidates without sending prompts, minting credentials or paying sellers.

Before enabling routing, choose finite spending ceilings and a peer funding target suitable for your currency and budget. Defaults are not a spending recommendation. The CLI’s routing explain uses default input/output estimates; the MCP tool permits explicit estimates.

cheapest_advertised compares advertised inference rates. It does not guarantee the cheapest total including eIOU payment-route fees. A request’s routing constraints can reduce remote access, hop horizon or price, but cannot raise operator limits. See API.

Managed peers and deals

Command Behavior
peers list or peers Managed seller credentials, cached balances, status and cooldowns; never plaintext tokens.
peers health Route reliability over the last 24 hours. Skips for readiness/budget do not count as provider failures.
peers attempts [--limit=<count>] [--seller=<seller-onion>] Recent attempts, newest first; default 20, clamped to 1–500.
peers warm [--max=<count>] Prepare credentials and fund eligible sellers selected by automatic routing. May send payments. Default maximum is 3; zero/negative input falls back to 3.
peers forget <seller-onion> Delete the local managed credential. Already-paid remote balance remains with the seller and is abandoned by this node; future selection can mint and fund a new credential.
deal <endpoint> <model> <minimum-remote-balance> <prompt...> Run a paid federated model request using a reusable managed seller credential. The amount is a minimum target balance, not a fixed inference price.

deal can fund a seller and disclose the prompt to it. If a routed top-up has not settled, the job can return in_use and resume in the background after credit arrives. Inspect the Network panel’s job ledger. Do not repeat a pending deal merely because it has not returned output yet.

Settings reference

Use set <key> <value> with the names below. These are plugin settings; they do not enable the host’s Public routes switch or grant plugin permissions. The operator REST configure action can apply multiple settings together; see API.

Admission and capacity

Setting Default / accepted value Effect
currency Host wallet default; VWL fallback Settlement denomination, from wallet allowed currencies. Changing it is refused while live keys use another denomination.
federation_access_mode pilot; or open Pilot requires accepted-contact admission for inference and restricts federation access. Open permits unbound self-service keys.
key_default_ttl Blank Default lifetime for new keys, including federation bootstrap; same syntax and 366-day maximum as --ttl. Does not change existing expiry dates.
mcp_default_max_output_tokens 1024 Default maximum output allowance used for balance preflight and inference; nonpositive values fall back to 1024. Model/caller limits may lower it.
total_capacity_tokens_per_window 0 Node-wide token capacity; only active with a positive window.
capacity_window_seconds 0 Capacity rolling-window duration; only active with positive token capacity.
operator_reserved_fraction 0 Fraction held out of customer capacity, clamped to 0–0.9. Sellable allowance is capacity × (1 − fraction).
mcp_default_allowed_origins Empty Browser-origin allow-list, as a JSON array or comma/whitespace-separated values. Non-browser requests may omit Origin; loopback origins are implicit, but matching the request Host is not enough. Entries match scheme and hostname without restricting ports in v0.29.3. Per-key overrides take precedence.

Automatic routing

Setting Default / limits Effect
routing_mode manual; auto, network_only network_only considers only directory sellers; use it only when that is the desired routing scope.
routing_policy local_first; cheapest_advertised, manual Ranking preference.
routing_remote_allowed 1 Permit directory sellers when automatic routing is enabled.
routing_max_hops 3; clamped 1–3 Discovery hop horizon, not a promise of seller admission or a payment route.
routing_max_candidates 3; clamped 1–10 Maximum candidates attempted.
routing_failover_enabled 1 Permit retrying another eligible route after a failure. This can change prompt recipients.
routing_max_price_per_request 0 Estimated per-request charge ceiling; zero means no ceiling.
routing_daily_spend_limit 0 UTC daily seller-funding ceiling; zero means no ceiling. Settled fees can make actual spend exceed the initial estimate.
routing_markup_pct 0 Routing markup percentage applied to network inference.
routing_seller_cooldown_seconds 300; clamped 0–86400 Cooldown for failed sellers.
routing_offer_max_age_seconds 21600; clamped 60–604800 Maximum age considered for offers; directory cleanup also removes stale rows.
peer_balance_low_watermark 0.10 Parsed by the policy but not used as a funding trigger in v0.29.3. Do not rely on it to limit top-ups.
peer_balance_target 1.00 Desired prepaid balance on a managed seller credential.

Amounts are nonnegative decimals in the node’s currency. Routing booleans accept 1, true, yes, on as true. The generic set command stores unrecognized keys too; success is not proof that an arbitrary name does anything. Currency, federation mode and default TTL have explicit validation; routing reads normalize/clamp values. Recheck routing status after changing routing settings.

Sessions and local discovery

Command Behavior
sessions list or sessions Open session IDs, associated key, age since activity and client name/version.
sessions terminate <session-id> End a specific MCP session. The client must initialize again.
sessions sweep Remove sessions idle for more than 30 minutes.
ollama detect Probe usual Ollama endpoints; show reachability, timing and failure kinds. Does not install Ollama.
sidecar detect [--preset=<id>] Probe all supported local discovery presets, or one of ollama, lmstudio, vllm, llamacpp, tgi. Does not install a runtime.

Local discovery applies to infrastructure you operate that can run local inference. Our hosted pilot nodes use online providers instead. See GUI for discovery and linking controls.

Credential vault

Command Behavior
vault status or vault Report master-key availability and sealed/plaintext/invalid provider and pending-job token counts.
vault migrate Seal legacy plaintext provider/job tokens using the host-provided master key. Idempotent for already sealed tokens; requires a functioning vault.
vault reset --confirm=1 Destructive recovery: erase stored provider/pending-job tokens and legacy migration sources. Use only after loss of the master key; re-enter provider credentials afterward.

Reset is not customer-key revocation, a refund, or erasure of the node’s full database. Vault encryption protects persisted secrets; a running node must be able to use them. See Architecture for the trust boundary.

Release-specific limitations

The v0.29.3 implementation differs from some built-in help text:

  • vault reset --confirm is not parsed as a flag. The working form is --confirm=1.
  • The advertised --no-retry discovery flag is ineffective: the parser normalizes hyphens to underscores but discovery checks the hyphenated name. Neither spelling disables retries in this release.
  • key quota and provider model-price --xfer=... are supported even though the main help omits them.
  • The directory cron interval is 10 minutes, not the hourly interval described in CLI help comments.

Verified against CliRouter.php, SettingsOps.php, KeyOps.php, RoutingPolicy.php, Service.php, State.php, the dispatcher, and plugin.json. For navigation, return to the documentation introduction.

Source: docs/CLI.md at revision 07476eedee57.