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

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:

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:

{
  "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.