Nebula MCP Environment Variable Configuration Guide

Nebula is configured entirely through environment variables passed in the env block of your MCP server config — no config files, no CLI flags. Every capability (wallet, spending policy, treasury, identity) has corresponding variables you can tune without changing code. This page documents all available variables, their defaults, and when to use them.

Required variables

STELLAR_SECRET_KEY

string

required

The Stellar secret key for your agent’s wallet. Must start with S and be 56 characters long. This key controls all funds held by the wallet — keep it secret and never commit it to version control.Generate a new keypair at laboratory.stellar.org under Account Creator.

Network

NETWORK

string

default:"testnet"

Which Stellar network to connect to. Accepted values: testnet or mainnet.On testnet, Friendbot is available for free XLM funding and all contracts use testnet deployments. Set to mainnet only when you are ready for production with real funds.

Switching from testnet to mainnet means your agent will use real XLM and real USDC. Double-check your spending limits before going live on mainnet.

Spending limits

Nebula enforces limits before signing any transfer, x402 payment, or MPP session open. You can enforce limits off-chain (via environment variables) or on-chain (via a Soroban smart contract). Treasury rebalancing is never subject to spending limits.

MAX_PER_CALL

number

Maximum amount (in stroops for XLM, or USDC base units) your agent can spend in a single transfer, x402_fetch, or mpp_open_session call. Required when POLICY_CONTRACT_ID is not set.Example: "1000" caps each individual payment at 1,000 units.

MAX_PER_DAY

number

Rolling 24-hour spending cap across all outgoing payments. Required when POLICY_CONTRACT_ID is not set.Example: "10000" allows up to 10,000 units of total outgoing spend in any 24-hour window.

POLICY_CONTRACT_ID

string

The address (C...) of a deployed nebula-policy Soroban contract. When set, all spending limits are enforced on-chain by the contract — MAX_PER_CALL and MAX_PER_DAY env vars are ignored for enforcement purposes.Deploy a new policy contract from chat using:

Use deploy_policy from Nebula

Copy the returned contract address into this variable and restart Claude.

POLICY_WASM_PATH

string

Path to a custom policy.wasm binary to use when deploying the nebula-policy contract with deploy_policy. Leave unset to use the WASM bundled inside the npm package — this is the right choice for almost all users.Only set this if you have compiled a custom fork of the policy contract and want to deploy that version instead.

When POLICY_CONTRACT_ID is set, your agent’s spending limits are enforced by the Stellar blockchain itself — not a config file. The chain rejects overspend. Use set_policy_limits to update caps without redeploying.

Treasury

The treasury engine runs a background rebalancer that deposits excess funds into Blend lending pools for yield and withdraws them automatically when your liquid balance drops below the threshold.

TREASURY_ASSET

string

default:"xlm"

Which asset the treasury engine manages. Accepted values: xlm or usdc.When set to xlm, Nebula manages your XLM balance in Blend (keeping XLM_FEE_BUFFER liquid for fees). When set to usdc, Nebula manages your USDC balance.

LIQUIDITY_THRESHOLD

number

default:"10"

Minimum liquid balance (in the treasury asset) to keep on hand at all times. Any balance above this threshold is automatically deposited into Blend to earn yield. When your liquid balance drops below this threshold, Blend withdraws funds to top it back up.Example: "10" keeps 10 XLM (or USDC) liquid and deposits the rest.

REBALANCE_INTERVAL_SECONDS

number

default:"60"

How often (in seconds) the background treasury loop runs to check and rebalance your position. Lower values react faster to balance changes; higher values reduce Stellar transaction frequency.

XLM_FEE_BUFFER

number

default:"5"

XLM amount reserved exclusively for transaction fees when TREASURY_ASSET=xlm. This buffer is excluded from treasury rebalancing — your agent always keeps at least this much XLM liquid to pay fees.

TREASURY_MAX_PER_REBALANCE

number

Optional cap on the amount moved in a single treasury rebalance transaction. Leave unset (or set to 0) to move the full excess or deficit in one transaction. Useful if you want to limit the size of individual Blend interactions.

MPP sessions

MPP_RECIPIENT

string

Default recipient address (G...) for MPP payment channel payouts. When set, mpp_open_session uses this address automatically — your agent doesn’t need to specify a recipient each time.Can be overridden per-call by passing recipient directly to mpp_open_session.

MPP_CHANNEL_WASM_PATH

string

Path to a custom channel.wasm binary to use when deploying an MPP payment channel contract via mpp_open_session. Leave unset to use the WASM bundled inside the npm package — the right choice for almost all users.Only set this if you have compiled a custom fork of the channel contract.

Agent identity (Stellar8004)

These variables pre-populate the metadata for your agent’s on-chain identity when you call register_identity. All are optional — identity registration works without them, but setting them makes your agent’s profile more useful to services that read on-chain reputation.

AGENT8004_NAME

string

Human-readable display name for your agent’s on-chain identity. Example: "My Research Agent".

AGENT8004_DESCRIPTION

string

Short description of what your agent does. Shown in reputation lookups by other agents and services.

AGENT8004_IMAGE_URL

string

URL to an avatar or logo image for your agent’s on-chain profile.

Complete configuration example

The following shows every variable in a single MCP config block. Copy it, remove what you don’t need, and fill in your values.

mcp-config.json

{
  "mcpServers": {
    "nebula": {
      "command": "npx",
      "args": ["-y", "nebula-mcp"],
      "env": {
        "STELLAR_SECRET_KEY": "YOUR_STELLAR_SECRET_KEY",

        "NETWORK": "testnet",

        "MAX_PER_CALL": "1000",
        "MAX_PER_DAY": "10000",
        "POLICY_CONTRACT_ID": "",
        "POLICY_WASM_PATH": "",

        "TREASURY_ASSET": "xlm",
        "LIQUIDITY_THRESHOLD": "10",
        "REBALANCE_INTERVAL_SECONDS": "60",
        "XLM_FEE_BUFFER": "5",
        "TREASURY_MAX_PER_REBALANCE": "",

        "MPP_RECIPIENT": "",
        "MPP_CHANNEL_WASM_PATH": "",

        "AGENT8004_NAME": "",
        "AGENT8004_DESCRIPTION": "",
        "AGENT8004_IMAGE_URL": ""
      }
    }
  }
}

POLICY_CONTRACT_ID overrides off-chain MAX_PER_CALL and MAX_PER_DAY for enforcement. When a contract address is present, set your limits on-chain using set_policy_limits — changes to MAX_PER_CALL and MAX_PER_DAY in the env block will have no effect on what the blockchain allows.

Variable summary

Variable	Required	Default	Purpose
`STELLAR_SECRET_KEY`	Yes	—	Wallet secret key (`S...`)
`NETWORK`	No	`testnet`	`testnet` or `mainnet`
`MAX_PER_CALL`	Off-chain mode	—	Per-payment spend cap
`MAX_PER_DAY`	Off-chain mode	—	Rolling 24h spend cap
`POLICY_CONTRACT_ID`	No	—	On-chain Soroban policy (`C...`)
`POLICY_WASM_PATH`	No	bundled	Custom policy WASM path (advanced)
`TREASURY_ASSET`	No	`xlm`	Asset managed by treasury engine
`LIQUIDITY_THRESHOLD`	No	`10`	Min liquid balance before depositing to Blend
`REBALANCE_INTERVAL_SECONDS`	No	`60`	Background treasury loop interval
`XLM_FEE_BUFFER`	No	`5`	XLM reserved for fees
`TREASURY_MAX_PER_REBALANCE`	No	—	Cap per single treasury move
`MPP_RECIPIENT`	MPP	—	Default channel payout address
`MPP_CHANNEL_WASM_PATH`	No	bundled	Custom channel WASM path (advanced)
`AGENT8004_NAME`	No	—	Agent display name for on-chain identity
`AGENT8004_DESCRIPTION`	No	—	Agent description for on-chain profile
`AGENT8004_IMAGE_URL`	No	—	Agent avatar URL for on-chain profile

​Required variables

​Network

​Spending limits

​Treasury

​MPP sessions

​Agent identity (Stellar8004)

​Complete configuration example

​Variable summary

Required variables

Network

Spending limits

Treasury

MPP sessions

Agent identity (Stellar8004)

Complete configuration example

Variable summary