> 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.md).

# Kumbaya Agent Kit

The [**Kumbaya Agent Kit**](https://github.com/Kumbaya-xyz/kumbaya-agent-kit) is everything an agent needs to act on Kumbaya (MegaETH): two [Model Context Protocol](https://modelcontextprotocol.io) 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](/developers/building-agents/overview.md). 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`](https://www.npmjs.com/package/@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](/developers/building-agents/agent-kit/onchain-mcp.md).   |
| **api-mcp**                                                                      | [`@kumbaya_xyz/kumbaya-mcp`](https://www.npmjs.com/package/@kumbaya_xyz/kumbaya-mcp)       | The app. JWT-authenticated access to the Exchange, Client, and Search APIs as \~113 auto-generated tools. See [MCP Server](/developers/building-agents/agent-kit/mcp.md).                                   |
| **signer**                                                                       | [`@kumbaya_xyz/onchain-signer`](https://www.npmjs.com/package/@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](/developers/building-agents/agent-kit/signer.md). |
| [**skills/**](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/tree/main/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](/developers/building-agents/siwe.md) 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/`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/tree/main/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`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya/SKILL.md)                     | both          | Overview and routing - which server to use for what, and the auth bridge.       |
| [`kumbaya-trade`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-trade/SKILL.md)         | onchain-mcp   | Quote first, then swap (including native ETH).                                  |
| [`kumbaya-liquidity`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-liquidity/SKILL.md) | onchain-mcp   | Provide, view, adjust, and collect V3 liquidity.                                |
| [`kumbaya-launch`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-launch/SKILL.md)       | onchain + api | Launch a token on the bonding curve, optionally seed a buy and post about it.   |
| [`kumbaya-tip`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-tip/SKILL.md)             | onchain + api | Tip a creator on a comment - the wallet signs a permit, the app API submits it. |
| [`kumbaya-earn`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-earn/SKILL.md)           | 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`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-trader/SKILL.md)           | trade, liquidity  | `exchange,search` | wallet key (partner key optional) |
| [`kumbaya-creator`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-creator/SKILL.md)         | launch, earn, tip | `client,exchange` | wallet key + JWT                  |
| [`kumbaya-contributor`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-contributor/SKILL.md) | tip, social       | `client,search`   | wallet key + JWT                  |
| [`kumbaya-observer`](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/blob/main/skills/kumbaya-observer/SKILL.md)       | reads only        | `exchange,search` | none - no key, no JWT             |

## Quick start

The fastest path is to pick a [persona](#skills) 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

```json
{
  "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:

```json
"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](/developers/building-agents/agent-kit/signer.md) 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**](/developers/building-agents/agent-kit/onchain-mcp.md) - the wallet server and its 22 tools
* [**Signer service**](/developers/building-agents/agent-kit/signer.md) - keyless signing for agent fleets
* [**MCP Server**](/developers/building-agents/agent-kit/mcp.md) - the api-mcp and its \~113 API tools
* [**Sign in with Ethereum**](/developers/building-agents/siwe.md) - the auth bridge in detail
* [**Building agents → Overview**](/developers/building-agents/overview.md) - the raw integration path the kit is built on
* [**skills/ on GitHub**](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/tree/main/skills) - the `SKILL.md` source for every activity and persona