# Build your own agent

> Point your own AI agent at the KickBot MCP server with an API key, and follow an example flow that sets up commands, timed messages and TTS for a channel.

Source: https://kickbot.com/docs/api/start/build-an-agent

Any agent framework that supports remote MCP servers over Streamable HTTP can use KickBot. Give the agent the server URL and an API key, and it gets one tool for each KickBot action.

- **Server URL:** `https://kickbot.com/api/v1/mcp`
- **Header:** `Authorization: Bearer kb_live_...` (an [API key](https://kickbot.com/docs/api/start/api-keys))

The server sends short instructions to the agent when it connects. A longer guide for agents, with every tool and field, is at [kickbot.com/api/v1/mcp.md](https://kickbot.com/api/v1/mcp.md). You can give that file to an agent as context.

## How the server works

- MCP is JSON-RPC 2.0 over HTTP `POST`. The server is stateless and answers with JSON (no server-sent event stream). A `GET` request returns HTTP 405.
- Supported protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`.
- Supported methods: `initialize`, `ping`, `tools/list` and `tools/call`. The server has no resources or prompts (the lists are empty).
- Each tool has MCP annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`. An agent can use them to ask you before a destructive change.
- To load fewer tools, add `?areas=` to the URL, for example `?areas=commands,timers`. See [Connect an AI app](https://kickbot.com/docs/api/start/connect-ai-apps).

## Example agent flow

A request like "Set up my channel for a chill Minecraft stream" usually goes like this:

1. **`get_account_overview`.** The agent learns the plan, the limits and the areas it can use. If KickBot is not a moderator yet, it asks you to type `/mod KickBot` in your Kick chat and then calls `check_moderator_status`.
2. **`list_commands`, `list_timers`, `get_tts_settings`.** The agent reads what exists before it changes anything. `get_channel_activity` shows what your viewers use most.
3. **`set_command_by_name`** for `discord`, `socials` and `lurk`. Running it again later does not make duplicates.
4. **`create_timer`** with a follow reminder every 30 minutes.
5. **`update_tts_settings`** to set the maximum message length and the cooldowns.
6. The agent reports what it changed. You can check the same list in **Recent API activity** on the **API & MCP** page.

## Test the server with curl

You can try the server without an agent. List the tools:

```bash
curl https://kickbot.com/api/v1/mcp \
  -H "Authorization: Bearer $KICKBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Call a tool:

```bash
curl https://kickbot.com/api/v1/mcp \
  -H "Authorization: Bearer $KICKBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_account_overview","arguments":{}}}'
```

A successful tool call returns the data twice: as JSON text in `content`, and as `structuredContent`.

A tool error comes back as a normal result with `isError: true` and the same `error` object as the REST API, so the agent can read it and react. For example, `limit_reached` means the plan limit blocks the change. See [Errors and limits](https://kickbot.com/docs/api/start/errors-and-limits).

## Tips for reliable agents

- Use a **read-only key** for agents that only report on your channel.
- Keep the key in an environment variable or a secret store, never in the prompt.
- Prefer `set_command_by_name` and the `update_*` tools. They are safe to run again.
- Respect `rate_limited` errors. Wait `retry_after_seconds`, then try again.
- Do not retry `limit_reached` or `premium_required`. Tell the user instead.
- Changes apply to the live channel at once. Ask the agent to confirm big changes with you first.