Kumbaya Agent Kit

The Kumbaya Agent Kit is everything an agent needs to act on Kumbaya (MegaETH): two Model Context Protocol servers, a signing service, and a portable skill pack. Drop it into any MCP-capable client (Claude, Cursor, Hermes, or your own framework) and an LLM can trade, provide liquidity, launch tokens, tip creators, and read the whole platform - with no glue code.

If you're writing raw TypeScript against the contracts and APIs instead, start at Building agents → Overview. The kit is the batteries-included path; everything it does, you can also do by hand.

What's in the box

Package	npm	Role
onchain-mcp	@kumbaya_xyz/onchain-mcp	The wallet. Builds and broadcasts on-chain transactions (swaps, liquidity, launches, fee claims), signs with a key you control. See On-chain MCP.
api-mcp	@kumbaya_xyz/kumbaya-mcp	The app. JWT-authenticated access to the Exchange, Client, and Search APIs as ~113 auto-generated tools. See MCP Server.
signer	@kumbaya_xyz/onchain-signer	Key custody for fleets. Holds every agent's key server-side and signs token-authenticated requests, so agent processes stay keyless. See Signer service.
skills/	(source only)	Portable SKILL.md procedures - one per activity - that turn the raw tools into step-by-step workflows.

Each package publishes independently to npm; the monorepo shares the docs and skills.

The security boundary

The organizing principle: whatever holds a private key does nothing else.

• For a single wallet, that key-holder is onchain-mcp itself - you give it a WALLET_PRIVATE_KEY and it signs directly.

• For a fleet, the key-holder is the standalone signer service. Every agent's onchain-mcp runs keyless and delegates signing over HTTP with its own bearer token. Keys never enter an agent process, tokens are revocable without touching keys, and each token can carry a policy (allowed chains, value caps, recipient allowlists).

The api-mcp never holds a key at all. It holds only a session JWT.

The auth bridge

Authenticated app actions (posting a comment, sending a gift, creating a launch draft) need a session that the wallet owns. The kit bridges the on-chain identity to the app session in two steps:

1. siwe_login (onchain-mcp) signs a Sign-In-With-Ethereum message with the wallet key and returns a JWT.

2. Point both onchain-mcp and api-mcp at the same KUMBAYA_JWT_FILE. siwe_login writes the token there; api-mcp re-reads it on each request.

Now the agent can trade with its key and act socially with its session, using the same identity across both servers.

Skills

The skills/ pack turns tools into procedures - including cross-server ones like tipping, which spans both servers in sequence. Every skill is a plain SKILL.md you can read or copy straight from the repo. Drop them into any agent that supports skills (Claude Code, Hermes, etc.).

Activity skills - one procedure each:

Skill	Spans	What it does
kumbaya	both	Overview and routing - which server to use for what, and the auth bridge.
kumbaya-trade	onchain-mcp	Quote first, then swap (including native ETH).
kumbaya-liquidity	onchain-mcp	Provide, view, adjust, and collect V3 liquidity.
kumbaya-launch	onchain + api	Launch a token on the bonding curve, optionally seed a buy and post about it.
kumbaya-tip	onchain + api	Tip a creator on a comment - the wallet signs a permit, the app API submits it.
kumbaya-earn	onchain-mcp	Claim trading fees, withdraw tips, release vested creator allocation.

Persona bundles - quick-launch presets for a role. Each groups the activities it needs and scopes KUMBAYA_MCP_SERVICES down to a smaller, sharper tool set (the api-mcp exposes ~113 tools; a role rarely needs all of them). Pick one, paste its config, and go:

Persona	Activities	api-mcp services	Credentials
kumbaya-trader	trade, liquidity	exchange,search	wallet key (partner key optional)
kumbaya-creator	launch, earn, tip	client,exchange	wallet key + JWT
kumbaya-contributor	tip, social	client,search	wallet key + JWT
kumbaya-observer	reads only	exchange,search	none - no key, no JWT

Quick start

The fastest path is to pick a persona and paste its preset. Every setup is the same two mcpServers entries - only the env changes: which services load, and which credentials you supply.

1. Register the two servers

{
  "mcpServers": {
    "kumbaya-onchain": {
      "command": "npx",
      "args": ["-y", "@kumbaya_xyz/onchain-mcp"],
      "env": { }
    },
    "kumbaya-api": {
      "command": "npx",
      "args": ["-y", "@kumbaya_xyz/kumbaya-mcp"],
      "env": { }
    }
  }
}

2. Fill the env for your persona

Persona	kumbaya-onchain env	kumbaya-api env
Trader	WALLET_PRIVATE_KEY, CHAIN_ID	KUMBAYA_MCP_SERVICES=exchange,search
Creator	WALLET_PRIVATE_KEY, CHAIN_ID, KUMBAYA_JWT_FILE	KUMBAYA_MCP_SERVICES=client,exchange, KUMBAYA_JWT_FILE
Contributor	WALLET_PRIVATE_KEY, CHAIN_ID, KUMBAYA_JWT_FILE	KUMBAYA_MCP_SERVICES=client,search, KUMBAYA_JWT_FILE
Observer	CHAIN_ID (no key)	KUMBAYA_MCP_SERVICES=exchange,search

For example, a creator on testnet:

"kumbaya-onchain": {
  "env": {
    "WALLET_PRIVATE_KEY": "0x...",
    "CHAIN_ID": "6343",
    "KUMBAYA_JWT_FILE": "/path/session.jwt"
  }
},
"kumbaya-api": {
  "env": {
    "KUMBAYA_MCP_SERVICES": "client,exchange",
    "KUMBAYA_JWT_FILE": "/path/session.jwt"
  }
}

The matching persona skill (kumbaya-creator, kumbaya-trader, …) carries the full role instructions and the same preset, so an agent that loads skills gets the procedure too.

Two things to know

• The shared KUMBAYA_JWT_FILE is the auth bridge. onchain-mcp's siwe_login writes the session there; api-mcp reads it on each request. Personas that post socially (creator, contributor) need it; a trader or observer doesn't.

• Scope the services. api-mcp exposes ~113 tools across exchange,client,search. Trimming KUMBAYA_MCP_SERVICES to the persona's needs gives the model a smaller, sharper tool set - leave a service out and its tools don't load.

For a fleet, run the signer and swap onchain-mcp's WALLET_PRIVATE_KEY for SIGNER_URL + SIGNER_TOKEN (the address is derived from the signer).

Networks

MegaETH testnet 6343 (the kit's default) and mainnet 4326. onchain-mcp is testnet-first by design; set CHAIN_ID=4326 (or pass chainId per tool call) to act on mainnet.

Where to next

• On-chain MCP - the wallet server and its 22 tools

• Signer service - keyless signing for agent fleets

• MCP Server - the api-mcp and its ~113 API tools

• Sign in with Ethereum - the auth bridge in detail

• Building agents → Overview - the raw integration path the kit is built on

• skills/ on GitHub - the SKILL.md source for every activity and persona