Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

On-chain MCP

@kumbaya_xyz/onchain-mcp is the wallet half of the Kumbaya Agent Kit: an MCP server that builds, signs, and broadcasts on-chain transactions on MegaETH. It covers trading, liquidity, launchpad token launches, creator earnings, and the reads that support them. It signs either with a local key you control or by delegating to a remote signer.

Field
Value

Package

@kumbaya_xyz/onchain-mcp (npm)

Bin

kumbaya-onchain-mcp

Source

github.com/Kumbaya-xyz/kumbaya-agent-kit

Transport

stdio

Default chain

6343 (MegaETH testnet)

License

MIT

Unlike the api-mcp, this server holds a key (or reaches one). It's built from contract calldata and the @kumbaya_xyz SDKs (sdk-core, v3-sdk, router-sdk) plus viem for signing and broadcasting.

Install

Register it with an MCP client. Local-key mode (single wallet, testnet):

{
  "mcpServers": {
    "kumbaya-onchain": {
      "command": "npx",
      "args": ["-y", "@kumbaya_xyz/onchain-mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "CHAIN_ID": "6343",
        "KUMBAYA_JWT_FILE": "/path/session.jwt"
      }
    }
  }
}

Reads work without a key - omit WALLET_PRIVATE_KEY and the server runs read-only. For fleets, replace the key with the remote-signer variables below.

Tools

22 tools, testnet-first. Most tools accept an optional chainId (4326 mainnet, 6343 testnet) that overrides the configured default (get_address takes no inputs). Amounts are in human units (e.g. "0.5"), not wei.

Reads (no key required)

Tool
Purpose
Key inputs

get_address

Your wallet address (the account the signer holds).

(none)

get_balance

ETH and optional ERC-20 balance for an address (defaults to the wallet).

address?, token?

list_balances

All ERC-20 balances for an address plus ETH; discovered via the block explorer and verified on-chain.

address?, tokens?

get_token

ERC-20 metadata: symbol, name, decimals, total supply.

token

get_pool

V3 pool state for a pair + fee tier: address, price, tick, liquidity.

tokenA, tokenB, fee

quote

Best route and amounts from tokenIn to tokenOut. Provide exactly one of amountIn / amountOut.

tokenIn, tokenOut, amountIn?, amountOut?

list_positions

V3 liquidity positions (NFTs) for an address: range, amounts, uncollected fees, in-range status.

address?

get_tips

FuelVault balances for a token: your spendable tip credits and creator earnings (liquid / vested).

token, user?

get_vesting

Creator vesting schedule for a launchpad token: total, vested, released, releasable-now.

token

token_status

Your full stake in a token — balance, tip credits, creator earnings, liquidity, vesting — with isCreator / isDisposable flags.

token, address?

Writes (signing required, real transactions)

Tool
Purpose
Key inputs

swap

Swap tokens on the V3 DEX. Use the WETH address to pay/receive native ETH; ERC-20 inputs are auto-approved. Provide one of amountIn / amountOut.

tokenIn, tokenOut, amountIn?, amountOut?, slippageBps?

add_liquidity

Mint a V3 position. Full range by default; pass tickLower/tickUpper for a concentrated range.

tokenA, tokenB, fee, amountA, amountB, tickLower?, tickUpper?, slippageBps?

remove_liquidity

Withdraw percent of a position's principal plus all fees. percent=100 also burns the NFT.

tokenId, percent?, slippageBps?

collect_fees

Collect a position's accrued fees without removing liquidity.

tokenId

ignite

Launch a token on the bonding curve. Mines a CREATE2 salt so the token sorts as token0 vs WETH, applies standard curve params, returns the token + pool addresses. No ETH required.

name, symbol, totalSupply?

claim_fees

Claim your creator trading fees. You earn only post-graduation via stream (FireStream pays the streaming recipients and sends you the remainder). The pre-graduation graduator path collects bonding-curve fees to the protocol, not you. auto tries graduator then stream.

token, source? (auto/stream/graduator)

withdraw_tips

Withdraw your unlocked creator tips from the FuelVault to your wallet.

token

release_vested

Release your vested creator token allocation.

token

swap, add_liquidity, and deposit_credits operate only on launchpad, bluechip, or verified tokens (per the search directory), plus a token launched in the same session. Unrecognized tokens are rejected, and the check fails closed if the directory is unreachable. Set KUMBAYA_TOKEN_ALLOWLIST=off to operate on any token.

Wallet (auth + signing)

Tool
Purpose
Key inputs

siwe_login

Sign a Sign-In-With-Ethereum message and return a JWT. If KUMBAYA_JWT_FILE is set, writes the token there so api-mcp picks it up automatically. Run before any authenticated app action.

chainId?

sign_typed_data

Sign EIP-712 typed data (e.g. a gift permit from an api-mcp prepare step) so it can be submitted.

typedData

sign_token_claim

Sign the EIP-712 ClaimListing proof to claim an unclaimed token listing as its on-chain creator. Pass the returned fields straight to the api-mcp app_post_tokens_by_mint_address_claim tool.

mintAddress, chainId?

deposit_credits

Deposit a launched token into your FuelVault credit balance (approve + depositFrom). Credits are spent when tipping.

token, amount

Write and wallet tools return a txHash, status, and an explorer link where applicable.

Configuration

Signing: local key

Env var
Purpose

WALLET_PRIVATE_KEY

Hex private key used to sign. Omit for read-only mode. (AGENT_WALLET_KEY is accepted as a fallback name.)

Signing: remote signer (fleets)

Set these instead of WALLET_PRIVATE_KEY and the process holds no key - it delegates every signature to a signer service.

Env var
Purpose

SIGNER_URL

Base URL of the signer service (e.g. http://localhost:8787).

SIGNER_TOKEN

This agent's bearer token at the signer.

SIGNER_ADDRESS

This agent's public address. Optional: derived from the signer's /v1/address at startup when omitted.

Chain and API

Env var
Default
Purpose

CHAIN_ID

6343

Default chain: 4326 mainnet or 6343 testnet. Overridable per tool via chainId.

KUMBAYA_JWT_FILE

(none)

Path shared with api-mcp. siwe_login writes the session JWT here; api-mcp reads it.

KUMBAYA_EXCHANGE_URL

https://exchange.kumbaya.xyz

Exchange API base, used for the public pools/admitted routing endpoint.

KUMBAYA_CLIENT_URL

https://clients.kumbaya.xyz

Client API base, used only for SIWE wallet auth.

KUMBAYA_TOKEN_ALLOWLIST

on

Set to off to disable the token allowlist and operate on any token.

KUMBAYA_SEARCH_URL

https://search.kumbaya.xyz

Search API base, used to classify tokens as launchpad, bluechip, or verified.

KUMBAYA_BLOCKSCOUT_4326

https://megaeth.blockscout.com/api

Mainnet block explorer used to discover an address's token holdings.

KUMBAYA_BLOCKSCOUT_6343

https://megaeth-testnet-v2.blockscout.com/api

Testnet block explorer used to discover an address's token holdings.

Routing

quote and swap discover routes from the public pools/admitted endpoint on the Exchange API, and fall back to on-chain pool probing for freshly launched tokens that aren't admitted yet. Pool addresses are computed with Kumbaya's custom init code hash, which is baked into @kumbaya_xyz/v3-sdk.

Where to next

PreviousKumbaya Agent KitNextMCP Server (APIs)

Last updated