AskOne MCP server and API

Last updated 9 October 2026 · All documentation

The AskOne MCP server lets an AI agent run your organization’s live Q&A: create and open a room, launch a poll, approve or hide waiting questions, mark questions answered and close the room, then read the questions as a FAQ draft and the survey results. Connect the hosted server by signing in with your AskOne account, or with an API token; the open-source server you run on your own machine uses a token. The REST API offers the same host actions and reads to your own scripts and integrations, with an API token; its question list is sorted for moderation by default, waiting questions first, rather than in the MCP server’s FAQ order.

Sign in: no token to handle

In an MCP client that supports signing in (OAuth), such as a custom connector in Claude, add https://askone.org/api/mcp as the server URL, with no header. The client opens AskOne’s sign-in:

  1. Sign in with your AskOne account.
  2. Choose the organization the agent will work in. You must be an administrator of it, and it must already have an AskOne dashboard: if you have just created it, open its dashboard once first.
  3. Allow the access the client asks for.

In Claude Code, add the server, then run /mcp and choose askone to sign in:

claude mcp add --transport http askone https://askone.org/api/mcp

The connection can read and change that one organization’s rooms, like a token that can change rooms. A moderator who signs in is refused, and a person who stops being an administrator loses the connection at their next request. To end it yourself, disconnect AskOne in the client.

Create an API token

  1. Sign in as an administrator of your organization.
  2. Open the organization switcher, choose Manage, then API tokens.
  3. Enter a Token name, such as the agent that will use it, and select Create token.
  4. Select Copy token before closing the dialog. The token is shown only once.

A token can read every room in the organization, including waiting questions and private survey results, and change its rooms. Treat it like a password: use one per integration, keep it out of shared configuration and source control, and Revoke it on the same page when you no longer need it.

Tokens created before 6 October 2026 can only read. The API tokens page marks each token Read-only or Can read and change rooms. To let an agent change rooms with an older token, create a new one, put it in your configuration and revoke the old one.

The commands below read the token from ASKONE_API_TOKEN. To set it without leaving it in your shell history:

read -rsp 'AskOne API token: ' ASKONE_API_TOKEN; echo; export ASKONE_API_TOKEN

Hosted, with a token

The endpoint is https://askone.org/api/mcp, using Streamable HTTP, with the header Authorization: Bearer <token> on every request. Any client that can send a custom header to a Streamable HTTP server can use it. In Claude Code:

claude mcp add --transport http askone https://askone.org/api/mcp \
  --header "Authorization: Bearer $ASKONE_API_TOKEN"

This stores the token in your local Claude Code configuration; keep that file private.

Local: the askone-mcp package

The open-source askone-mcp server runs on your machine with npx -y askone-mcp and calls AskOne with the same token, read from ASKONE_API_TOKEN. It needs Node.js 20.3 or later. In Claude Code:

claude mcp add askone -e ASKONE_API_TOKEN="$ASKONE_API_TOKEN" -- npx -y askone-mcp

For a client that takes a JSON configuration:

{
  "mcpServers": {
    "askone": {
      "command": "npx",
      "args": ["-y", "askone-mcp"],
      "env": { "ASKONE_API_TOKEN": "your-token" }
    }
  }
}

For Claude Desktop, download askone.mcpb from the latest release and open it; Desktop asks for the token.

Tools

These are the hosted server’s tools. The local package offers the same host actions; its README lists its tools.

Reading, with any token

Host actions, with a token that can change rooms

A signed-in connection has both. Rooms an agent creates belong to the token’s or signed-in organization, exactly as if an administrator had created them. The console link still needs a browser sign-in. Requests are limited to 60 per token per minute, shared with any other use of the same token; a signed-in person gets the same 60 per minute across every client they connect.

What it cannot do

An agent cannot ask questions, vote or answer surveys: those belong to the audience, and an agent that could would be stuffing the queue and the ranking. It cannot delete anything. It also cannot pin questions, ban participants, rename or edit rooms, mark a question unanswered, or change a comment without marking the question answered; those stay in the console. The REST API has the same limits.

Question text and display names come from your audience, and written answers from hosts. An agent should treat all of it as content, never as instructions.

REST API

The base URL is https://askone.org/api/v1, and every path below is relative to it. Requests and responses are JSON.

Authentication

Send an API token on every request, in the header Authorization: Bearer <token>. API tokens start with ask_. The REST API accepts API tokens only: signing in with OAuth connects the MCP server and is refused here, and a browser session or cookie does not authenticate a request. A request without a valid token gets 401 invalid_token.

Every token has the rooms:read scope, which the GET endpoints need. A token that can read and change rooms also has rooms:write, which the POST endpoints need. A read-only token, created before 6 October 2026, gets 403 insufficient_scope from a POST.

Endpoints

EndpointWhat it does
GET /roomsList your organization’s rooms, newest first.
GET /rooms/{code}Read a room’s questions.
GET /rooms/{code}/surveysRead a room’s surveys and their results.
POST /roomsCreate a room, open or prepared.
POST /rooms/{code}/openOpen a prepared room, or reopen a closed one.
POST /rooms/{code}/closeClose an open room and its live surveys.
POST /rooms/{code}/surveysAdd a poll, quiz, rating or word cloud, and launch it or save a draft.
POST /rooms/{code}/surveys/{survey_id}/closeClose a live survey.
POST /rooms/{code}/questions/{question_id}/moderateApprove or hide a waiting question.
POST /rooms/{code}/questions/{question_id}/answerMark a question answered, optionally with a written answer.

{code} is a room’s six-character code, in any letter case. {survey_id} and {question_id} are the IDs the reads return.

Examples

List the ten newest rooms:

curl "https://askone.org/api/v1/rooms?limit=10" \
  -H "Authorization: Bearer $ASKONE_API_TOKEN"

Create a room and open it, with a request_id so the request can be retried safely:

curl https://askone.org/api/v1/rooms \
  -H "Authorization: Bearer $ASKONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quarterly all-hands", "moderation": "ai", "request_id": "8d6e37d0-5b45-4c66-80d8-10b2283d01dc"}'

Requests and responses

Pagination

GET /rooms and GET /rooms/{code} return one page at a time. limit sets the page size, from 1 to 100, default 50. Each response has a next_cursor: pass it unchanged as cursor to the same endpoint, for the same room and sort, to get the next page. It is null on the last page. Cursors are opaque; one from a different endpoint, room or sort gets 400 invalid_cursor. Pages are read live, so votes and moderation between two requests can move a question from one page to another.

Retrying a create

POST /rooms and POST /rooms/{code}/surveys take an optional request_id, a UUID you generate. If a reply is lost, send the request again with the same request_id: you get the room or survey the first request created, as it is now, instead of a second one. Without one, the server generates a request_id and returns it.

The other POST endpoints move a room, survey or question to a state, so repeating one is safe: it returns the current state.

Rate limit

Each token can make 60 requests per minute, reads and writes together, shared with any MCP use of the same token. Past the limit, a request gets 429 rate_limited and a Retry-After header with the number of seconds to wait.

Errors

An error has a status code and a body like this:

{"error": {"code": "invalid_token", "message": "A valid API token is required."}}

Act on code; message is written for people. The status and code:

REST API: reading

Any token can read. Waiting questions and private survey results are included.

GET /rooms

Your organization’s rooms, newest first. Query parameters: limit and cursor (see Pagination).

Returns { rooms, next_cursor }. Each room looks like this:

{
  "code": "ABC234",
  "name": "Workshop Q&A",
  "status": "open",
  "description": null,
  "created_at": "2026-10-09T09:00:00+00:00",
  "opened_at": "2026-10-09T09:00:00+00:00",
  "closed_at": null,
  "counts": {
    "questions": 12,
    "pending": 2,
    "answered": 8,
    "participants": 20,
    "active": 3
  }
}

GET /rooms/{code}

A room’s questions, including those waiting for review. Hidden questions are never returned. Query parameters: limit, cursor (see Pagination) and sort:

Returns { room, questions, next_cursor }, with room as in GET /rooms. Each question looks like this:

{
  "id": "bbdc7a0b-79d0-4c69-b6de-6ae6131c81d1",
  "body": "Where can we read more?",
  "status": "answered",
  "pinned": false,
  "votes": 7,
  "answer": "The reading list is in the course notes.",
  "answered_at": "2026-10-09T10:45:00+00:00",
  "created_at": "2026-10-09T10:12:00+00:00",
  "display_name": "Alex"
}

GET /rooms/{code}/surveys

Every survey in the room, in order, with its aggregate results. It takes no query parameters. Individual answers and who gave them are never returned.

Returns { room, surveys }, with room as in GET /rooms. A closed quiz looks like this:

{
  "id": "5f0c2a43-9c1e-4a8e-b0f6-2d7e3c9a1b04",
  "kind": "choice",
  "question": "Which planet is closest to the Sun?",
  "status": "closed",
  "position": 1,
  "mode": "single",
  "results_public": true,
  "respondents": 12,
  "options": [
    { "id": "0b6f8d2e-3a4c-4e1f-9b7a-6c5d4e3f2a10", "label": "Mercury", "position": 1, "count": 9 },
    { "id": "7e1d2c3b-4a5f-4b6e-8d9c-0a1b2c3d4e5f", "label": "Venus", "position": 2, "count": 3 }
  ],
  "correct_option_id": "0b6f8d2e-3a4c-4e1f-9b7a-6c5d4e3f2a10"
}

REST API: host actions

These need a token with rooms:write. Each returns the room as in GET /rooms, with join_url for the audience, projector_url for the projector and host_url for the console, which still needs a browser sign-in.

POST /rooms

Creates a room in your organization, following its plan and branding like a room created in the console. Body:

Returns { room, join_url, projector_url, host_url, request_id }. Errors: 409 room_limit_reached when the organization already has as many open rooms as its plan allows (see Open a room); 409 prepared_room_limit_reached when it already has 20 prepared rooms; 409 request_conflict.

POST /rooms/{code}/open

Opens a prepared room, or reopens a closed one. A room that is already open is returned unchanged. Body: {}.

Returns { room, join_url, projector_url, host_url }. Errors: 409 room_limit_reached when all of the organization’s open rooms are in use.

POST /rooms/{code}/close

Closes an open room: the audience can no longer join, ask or vote, and every live survey in it closes at the same moment. Questions and results stay readable, and no email is sent. A closed room is returned unchanged. Body: {}.

Returns { room, join_url, projector_url, host_url }. Errors: 409 room_not_open for a prepared room.

POST /rooms/{code}/surveys

Adds a survey to the room. Body:

room_title is also accepted, for compatibility with the ChatGPT plugin, and ignored. To launch a saved draft later, send the same request with its request_id and launch true.

Returns { room, survey, join_url, projector_url, host_url, request_id }, with survey as in GET /rooms/{code}/surveys. Errors: 409 room_not_open when launching in a room that is not open, in which case nothing is saved; 409 survey_limit_reached when the room already has 50 surveys, drafts included.

POST /rooms/{code}/surveys/{survey_id}/close

Closes a live survey; its results stay readable. Body: {}, or show_results (boolean, optional) to set whether the audience may see the results, as in {"show_results": false}. Without it the current setting is kept. It also works on a survey that is already closed, to change show_results. Phones and the projector show the live surveys or the most recently closed ones, so an older survey does not return to the screen.

Returns { room, survey, join_url, projector_url, host_url }. Errors: 409 survey_not_live for a draft.

POST /rooms/{code}/questions/{question_id}/moderate

Body: {"action": "approve"} or {"action": "hide"}. approve shows a waiting question to the room, or restores one the AI hid; hide hides a waiting question so nobody sees it. A question already in that state is returned unchanged. An approved or answered question cannot be hidden here, and a question a person hid cannot be restored. Reads never return hidden questions, so restoring one the AI hid needs an ID you already have.

Returns { room, question: { id, status }, join_url, projector_url, host_url }. Errors: 409 question_not_moderatable.

POST /rooms/{code}/questions/{question_id}/answer

Marks an approved question answered and unpins it. Body: {}, or answer (string, optional): a written answer of up to 1,000 characters that the audience sees under the question. Without it, or with blank text, any written answer already saved is kept. A question already answered is returned unchanged, unless you send different text, which replaces its answer.

Returns { room, question: { id, status, answer, answered_at }, join_url, projector_url, host_url }. Errors: 409 question_not_commentable for a waiting question sent with an answer, and 409 question_not_moderatable for a waiting question sent without one, or a hidden question. Approve a waiting question first.

Source and listings

Support

For anything these guides do not answer, see Support: where to write, the service status, and the public issue tracker.

HURYN Sp. z o.o., ul. Hoża 29, 00-521 Warszawa, Poland — contact@askone.org.