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

# MCP Server (APIs)

`kumbaya-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the Kumbaya platform as tools for any MCP client (Claude, Cursor, Hermes, and custom AI agents). It turns the Exchange, Client, and Search APIs into callable tools an LLM can use directly, with no glue code.

| Field     | Value                                                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| Package   | `@kumbaya_xyz/kumbaya-mcp` ([npm](https://www.npmjs.com/package/@kumbaya_xyz/kumbaya-mcp))                              |
| Source    | [github.com/Kumbaya-xyz/kumbaya-agent-kit](https://github.com/Kumbaya-xyz/kumbaya-agent-kit/tree/main/packages/api-mcp) |
| Transport | stdio                                                                                                                   |
| License   | MIT                                                                                                                     |

The server is generated directly from Kumbaya's OpenAPI specs, so its tools stay in lockstep with the live APIs.

> This is the **API** server - the app half of the [Kumbaya Agent Kit](/developers/building-agents/agent-kit.md). It reads and writes over HTTP and never holds a wallet. For on-chain actions (swaps, liquidity, launches) that need a key, pair it with the [on-chain MCP](/developers/building-agents/agent-kit/onchain-mcp.md).

## What it covers

| Service  | Tool prefix | Scope                                                                                  | Tools |
| -------- | ----------- | -------------------------------------------------------------------------------------- | ----- |
| Exchange | `dex_`      | Swap quotes, pools, tokens, stats, positions                                           | 29    |
| Client   | `app_`      | Launchpad, tokens, comments, gifts and fuel, feed, content, competition, badges, users | 76    |
| Search   | `search_`   | Token and pool full-text search                                                        | 8     |

Each tool maps one-to-one to an API endpoint and is named `<prefix>_<operation>`, for example `dex_get_quote`, `app_post_comments`, or `search_get_search_tokens`.

## Install

Run it directly:

```bash
npx @kumbaya_xyz/kumbaya-mcp
```

Or register it with an MCP client:

```json
{
  "mcpServers": {
    "kumbaya": {
      "command": "npx",
      "args": ["-y", "@kumbaya_xyz/kumbaya-mcp"],
      "env": {
        "KUMBAYA_API_KEY": "partner-key-for-quotes",
        "KUMBAYA_JWT": "user-jwt-for-authenticated-actions"
      }
    }
  }
}
```

## Configuration

| Env var                | Default                        | Purpose                                                                                               |
| ---------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `KUMBAYA_MCP_SERVICES` | all                            | Comma-separated services to expose, e.g. `exchange,search`. Trims the tool count for focused clients. |
| `KUMBAYA_API_KEY`      | (none)                         | Partner API key, sent as `x-api-key`. Required for the quote endpoints.                               |
| `KUMBAYA_JWT`          | (none)                         | User JWT, sent as `Authorization: Bearer`. Required for authenticated client-api actions.             |
| `KUMBAYA_EXCHANGE_URL` | `https://exchange.kumbaya.xyz` | Exchange base URL                                                                                     |
| `KUMBAYA_CLIENT_URL`   | `https://clients.kumbaya.xyz`  | Client base URL                                                                                       |
| `KUMBAYA_SEARCH_URL`   | `https://search.kumbaya.xyz`   | Search base URL                                                                                       |

DEX and search tools take a `chainId` (`4326` mainnet, `6343` testnet).

## Credentials, by tier

Tool descriptions carry a tag telling the client which credential a tool needs.

* **Public.** Most reads (pools, tokens, stats, positions, feed, content, search). No credentials.
* **Partner key.** The four quote tools (`dex_get_quote`, `dex_post_quote`, `dex_post_quote_open`, `dex_get_quote_tokens`). Set `KUMBAYA_API_KEY`. Request a key from the Kumbaya team.
* **User JWT.** Authenticated client-api actions (create a launch, post a comment, send a gift, edit a profile). Set `KUMBAYA_JWT`.

The server is keyless by design: it never holds a wallet or signs. It uses a JWT you supply. Agents obtain that JWT with their own wallet via [Sign-In With Ethereum](/developers/building-agents/siwe.md) and pass it in as `KUMBAYA_JWT`. Internal and administrative endpoints are not exposed.

## Example

Once connected, a client can ask in natural language and the model selects the right tool:

> "What's trending on Kumbaya mainnet, and how deep is the top pool's liquidity?"

resolves to `dex_get_tokens_trending` followed by `dex_get_pools_metrics`, with the results returned as structured JSON.

## Staying in sync

The bundled OpenAPI specs are Kumbaya's live documents. Contributors refresh them with `npm run refresh-spec`, which re-pulls each spec so the generated tools match the current API.

## See also

* [**Kumbaya Agent Kit**](/developers/building-agents/agent-kit.md) - this server plus the on-chain wallet, the fleet signer, and the skill pack
* [**On-chain MCP**](/developers/building-agents/agent-kit/onchain-mcp.md) - the key-holding counterpart for swaps, liquidity, and launches
* [**Sign in with Ethereum**](/developers/building-agents/siwe.md) - how an agent obtains the JWT this server consumes
* [**Exchange API**](/developers/apis/exchange-api.md), [**Client API**](/developers/apis/client-api.md), [**Search Service**](/developers/apis/search-service.md) - the REST endpoints these tools are generated from