> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/building-agents/agent-kit/onchain-mcp.md). # On-chain MCP `@kumbaya_xyz/onchain-mcp` is the wallet half of the [Kumbaya Agent Kit](/developers/building-agents/agent-kit.md): an [MCP](https://modelcontextprotocol.io) 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](/developers/building-agents/agent-kit/signer.md). | Field | Value | | ------------- | --------------------------------------------------------------------------------------------------------------------------- | | Package | `@kumbaya_xyz/onchain-mcp` ([npm](https://www.npmjs.com/package/@kumbaya_xyz/onchain-mcp)) | | Bin | `kumbaya-onchain-mcp` | | Source | [github.com/Kumbaya-xyz/kumbaya-agent-kit](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/tree/main/packages/onchain-mcp) | | Transport | stdio | | Default chain | `6343` (MegaETH testnet) | | License | MIT | Unlike the [api-mcp](/developers/building-agents/agent-kit/mcp.md), 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): ```json { "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](/developers/building-agents/siwe.md) message and return a JWT. If `KUMBAYA_JWT_FILE` is set, writes the token there so [api-mcp](/developers/building-agents/agent-kit/mcp.md) 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](/developers/building-agents/agent-kit/signer.md). | 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](/developers/dex-integration/pool-init-code-hash.md), which is baked into `@kumbaya_xyz/v3-sdk`. ## Where to next * [**Kumbaya Agent Kit**](/developers/building-agents/agent-kit.md) - how this fits with api-mcp, the signer, and skills * [**Signer service**](/developers/building-agents/agent-kit/signer.md) - run keyless agents against a shared signer * [**Sign in with Ethereum**](/developers/building-agents/siwe.md) - the JWT the auth bridge produces * [**Launching a token (ignite)**](/developers/launchpad/launching.md) - what `ignite` does under the hood