# MCP server

Unibot runs a Model Context Protocol server so an AI agent can manage and ask bots directly.

- Endpoint: `https://mcp.theunibot.com/mcp`
- Transport: Streamable HTTP (POST for messages; the server answers with JSON)
- Protocol versions: the current MCP specification versions are negotiated at `initialize`

## Authentication

`initialize`, `tools/list` and `ping` need no credentials. Tools that act on your account need your Unibot token as a bearer token:

```
Authorization: Bearer <token>
```

Get a token from `POST https://theunibot.com/api/collections/users/auth-with-password` or `auth-with-otp` (see [Authentication](/docs/auth)). A bearer token that is present but invalid is refused with HTTP 401. A tool called without any token returns an error result asking for one.

## Tools

| Tool | Needs a token | Arguments | Result |
| --- | --- | --- | --- |
| `list_bots` | yes | none | `{"bots": [{id, slug, name, greeting, public}]}` |
| `create_bot` | yes | `name`, optional `slug`, `greeting`, `public` (default true) | `{"bot": {...}}` |
| `add_answer` | yes | `bot` (slug or id), `question`, `answer` | `{"id", "bot", "question"}` |
| `ask_bot` | only for private bots | `bot` (slug), `q` | the same result as the public ask route |

Tools only ever act on bots you own. `ask_bot` also answers for any public bot, with or without a token.

## Example session

Initialize:

```bash
curl -i -X POST https://mcp.theunibot.com/mcp \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1"}}}'
```

Take the `Mcp-Session-Id` response header and send it on every later request, after a `notifications/initialized` message. Then call a tool:

```bash
curl -X POST https://mcp.theunibot.com/mcp \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session id>" -H "authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ask_bot","arguments":{"bot":"quillfeather-books","q":"do you ship books"}}}'
```

## Client configuration

Most MCP clients accept a URL and headers:

```json
{
  "mcpServers": {
    "unibot": {
      "type": "http",
      "url": "https://mcp.theunibot.com/mcp",
      "headers": {"Authorization": "Bearer <token>"}
    }
  }
}
```

## Notes

- Sessions are held in memory and expire after 30 minutes without traffic. If the server answers 404 to a session id, initialize again.
- The MCP endpoint answers only on the MCP host; the main site host does not serve `/mcp`.
