How to close the documentation feedback loop with MCP

Your chatbot already tells you where it struggles: thumbs-down answers, “I don’t know” replies, weak retrieval, unanswered turns, and pages that users and their AI agents report as wrong or outdated. The Insights MCP server hands that data to the AI assistant you write documentation with, so the loop from “user was unhappy” to “page updated and re-indexed” happens in one place.

This is a second, separate MCP server from the one described in Connect via MCP. That one exposes a bot’s knowledge base to end users. This one exposes a workspace’s feedback and conversations to its members.

What you get

Once connected, your assistant can:

• list problem conversations for the last week, month, quarter, year or a custom range of up to 400 days, and read full transcripts
• see which documentation pages users and their AI agents report most, and read each report together with the passage it quotes
• read the knowledge-gap clusters for longer horizons, and the most-asked questions of the last 90 days
• ask “where should this be fixed?” and get a diagnosed cause, a target page, the section heading to edit, and a suggested change
• read the current page text before drafting an edit, and search the docs exactly the way the bot does
• after you publish the fix: mark the item as addressed, close the user reports, queue a re-sync of the source, and verify the new text is retrievable

The server never edits your documentation. Writing happens in your own tool (Confluence, Notion, Git, a CMS), usually through that tool’s own connector in the same chat.

Prerequisites

• A ChatbotIQ workspace on a plan with API access (Personal, Standard or Business).
• Membership in that workspace. Any role can read; only owners and admins can grant the write scope (mark as addressed, close reports, re-sync).
• An MCP client: Claude.ai or Claude Desktop, ChatGPT, Claude Code, Cursor or any client that speaks MCP over HTTP.

Step 1: Find your endpoint

1. Open Analytics > Docs Insights.
2. In Connect your AI assistant, pick your client’s tab and copy the endpoint. It has the form https://app.chatbotiq.eu/v1/mcp/workspaces/<workspace-id>/mcp.

Every workspace has its own endpoint. A token issued for one workspace is rejected by another.

Step 2: Connect your client

When you connect a client that signs in with OAuth, a ChatbotIQ consent page opens. If you are not signed in to ChatbotIQ in that browser, you sign in first and then return to the consent page. It shows the account you are signed in with and where your browser returns after approval (for example claude.ai or chatgpt.com; for Claude Code, a local address on your computer). If the signed-in account is not a member of the workspace in the endpoint, click Use a different account and sign in with the right one.

Desktop clients such as Claude Code and Cursor open your default browser. If you are signed in to ChatbotIQ in another browser, click Copy link on the sign-in or consent page and open the link in that browser within 10 minutes.

Claude.ai and Claude Desktop

1. Go to Customize > Connectors, click +, then Add custom connector.
2. Paste the endpoint URL, click Add, then Connect.
3. A ChatbotIQ sign-in page opens. Sign in, check the workspace and the permissions, and click Allow access.
4. In a chat, click +, select Connectors and turn the connector on. The server’s prompts, such as Get started and Weekly documentation review, are listed under the connector in the same menu.

On Team and Enterprise plans, an owner adds the connector once in Organization settings > Connectors (Add, then Custom > Web). Each member then clicks Connect on it in Customize > Connectors and signs in with their own ChatbotIQ account.

ChatGPT

1. Turn on developer mode in ChatGPT’s settings. On Business and Enterprise plans, an admin may have to allow it first.
2. Open chatgpt.com/plugins and choose Add > New plugin.
3. Enter a name, paste the endpoint as the Server URL under Connection, and choose OAuth under Authentication.
4. Click I understand and want to continue on the risk notice, then Create.
5. Sign in to ChatbotIQ and click Allow access.

Claude Code

claude mcp add --transport http chatbotiq-insights https://app.chatbotiq.eu/v1/mcp/workspaces/<workspace-id>/mcp

Then run /mcp inside Claude Code, pick chatbotiq-insights and sign in when the browser opens. The server’s prompts become commands: type / to find them, or run /mcp__chatbotiq-insights__weekly_docs_review directly.

Cursor and other clients without OAuth

1. In Analytics > Docs Insights, create a personal access token. Give it a name and an expiry (30, 90 or 365 days). The token is shown once.
2. Add the server to the client’s MCP configuration with the token in the Authorization header:

{
  "mcpServers": {
    "chatbotiq-insights": {
      "url": "https://app.chatbotiq.eu/v1/mcp/workspaces/<workspace-id>/mcp",
      "headers": { "Authorization": "Bearer mcpu_..." }
    }
  }
}

Keep the configuration file private. You can revoke the token at any time in Analytics > Docs Insights.

Step 3: Run a review

If you are new to the server, start with the Get started prompt, or just ask “what can this do?”. The assistant takes a snapshot of what is waiting (problem turns from the last 7 days, new user reports, the most-reported pages, active knowledge gaps) and suggests a next step.

For the full loop, run the Weekly documentation review prompt: in Claude.ai pick it from the connector in the + menu; in Claude Code run /mcp__chatbotiq-insights__weekly_docs_review, optionally followed by a period such as last_30d. In any client you can also simply ask:

What did users complain about in the docs bot last week, and where should I fix it?

The assistant will:

1. call list_problem_conversations for the period, and get_content_hotspots for the pages users report most,
2. group the items by topic,
3. call get_doc_recommendation for the main topics,
4. show you a table: topic, number of turns, user reports on the same page (and how many a person asked their agent to file), cause, page and section, proposed change, link to the conversation,
5. stop and ask which items you want to work on.

User reports

When a bot’s MCP server uses an API key, the AI agents connected to it get a submit_feedback tool. Users and their agents use it to report a page or passage as incorrect, outdated, confusing or incomplete, usually quoting the exact passage. Identical reports within 24 hours are merged, and times_reported counts the repeats. Each report says whether a person asked their agent to file it (human) or the agent judged it on its own (agent); the reporting client sets that label and ChatbotIQ cannot verify it.

get_content_hotspots ranks pages by report count; list_user_feedback returns the reports themselves. The same reports are listed on the bot’s Deploy tab under AI assistants, and owners and admins get a daily email when new ones arrive (Account > Notifications, User feedback digest).

Longer horizons

Declined and low-confidence turns, and the most-asked questions, come from query analytics, which is kept for 90 days. Thumbs-down and unanswered turns and full conversations reach further back. For a quarter or a year, ask for knowledge gaps instead of raw conversations: clustered gaps are what make a long horizon readable.

Step 4: Read the recommendation correctly

Every recommendation starts with a cause. Only one of them means the documentation must change:

Cause	Meaning	What to do
content_gap	The docs do not contain what the user needed, or it is wrong or outdated.	Update the target page and section, or create a new page where suggested.
retrieval_failure	The answer exists in the docs but the bot did not find it.	Nothing in the docs. Tell the workspace admin; this is a bot or indexing problem.
answer_quality	The bot had the right material and still answered poorly.	Usually nothing in the docs. If the section is genuinely confusing, tighten it.
out_of_scope	The question is not about this product.	Ignore, or add an FAQ entry if it keeps coming up.

The target page and section are always chosen from pages that are actually indexed, and the section heading is copied from that page’s outline. The signals field explains why a page was chosen: the bot cited it, retrieval returned it, its heading matches the question, and so on. If a heading the model suggested does not exist on the page, it is dropped rather than invented.

The recommendation for a thumbs-down answer is computed automatically shortly after the rating. For other turns the assistant computes it on demand, capped at 30 per workspace per hour.

User reports get no recommendation of their own. For those, the assistant reads the reports with list_user_feedback: the quoted passage tells it which paragraph to fix, not just which page.

Step 5: Fix, then close the loop

1. Ask the assistant to read the target page with get_page and draft the change. It will tell you when a fact needs to come from a subject-matter expert instead of being invented.
2. Apply the change in your documentation tool.
3. Ask the assistant to mark the item as addressed (mark_feedback_addressed, outcome docs_updated), to close the matching user reports (update_user_feedback, status resolved) and to queue a re-sync of the source (trigger_source_resync). All three need the write scope.
4. When the sync has finished, ask it to verify with search_docs using the original user question.

Re-sync works for website, Confluence and Notion sources. For uploaded sources (PDF, files, spreadsheets, Q&A, OpenAPI), upload the updated file in the dashboard instead.

Addressed thumbs-down answers show Docs updated (or Not a docs issue, Won’t fix) in the Negative Feedback card on Analytics > Overview, together with the suggested fix and who addressed it. Resolved user reports leave the bot’s list of new reports under Deploy > AI assistants. The rest of the team sees the state without opening a chat.

Tools reference

Tool	Purpose	Scope
list_problem_conversations	Thumbs-down, declined, low-confidence and unanswered turns for a period, paginated; each turn listed once, pasted code never counted as low confidence	read
get_conversation	Full redacted transcript with citations, feedback and review state	read
search_conversations	Conversations matching a text fragment or a feedback filter	read
get_content_hotspots	Pages ranked by how many user reports landed on them, with breakdowns by issue type, reporter and review status	read
list_user_feedback	User reports with the quoted passage, who reported it and how often; filter by page, status, reporter or client	read
list_knowledge_gaps	Clustered gaps with finding, recommendation, per-gap confidence and decline rate, paginated (default 20, up to 8 sample questions each)	read
get_top_queries	Most-asked questions with retrieval score and decline rate (last 90 days; short replies and pasted material excluded)	read
get_doc_recommendation	Cause, action, target page and section, suggested change	read
search_docs	Search the indexed docs with the bot’s own retrieval	read
get_page	Full page markdown plus its heading outline	read
list_bots, list_sources	Workspace inventory	read
mark_feedback_addressed	Record the outcome for a problem turn	write
update_user_feedback	Set a user report to new, reviewed, resolved or dismissed	write
resolve_knowledge_gap	Close a gap cluster	write
trigger_source_resync	Queue a refresh crawl or API sync	write

list_problem_conversations and search_conversations take an optional origin (widget, dashboard, api or slack) to separate end users from the playground and integrations.

Prompts: get_started (no arguments), weekly_docs_review (period, optional bot) and triage_one (a single message id).

Security and privacy

• Sign-in, not shared keys. Claude and ChatGPT connect through OAuth with PKCE; the sign-in page is ChatbotIQ’s own login. Personal access tokens exist only for clients that cannot run OAuth, expire, and are shown once.
• Bound to a member. Every token belongs to a user and a workspace. Membership and role are re-checked on every call, so removing a member cuts their access immediately and a role downgrade removes the write scope.
• Least privilege. Read access is the default. The write scope is only granted to owners and admins, and only when the client asks for it; they can untick it on the consent page to connect read-only.
• Redaction. Emails, phone numbers, card numbers and similar personal data are masked in every text field before it leaves ChatbotIQ. Contact emails, page origins, session ids and IP addresses are never included.
• Untrusted content. User questions, comments and reports are data, not instructions. That includes the quoted passage in a user report: the reporting client wrote it, even though it looks like your own documentation. The server tells the assistant so on every call and flags items that look like prompt-injection attempts. Treat flagged items with care.
• Audit trail. Every tool call is recorded with who, which token, which tool and which conversation. Owners and admins can see all active connections on the Docs Insights page and revoke any of them.
• Rate limits. Per token and per workspace, with an extra cap on on-demand recommendation computations.

Troubleshooting

The consent page says “This account can’t approve the connection”. You are signed in to ChatbotIQ with a different account than the one that belongs to the workspace, for example a work account instead of a personal one. Click Use a different account on the consent page and sign in with the account that is a member, or ask a workspace owner to invite the account you use. Cancel stops the connection attempt so you can start again from your MCP client.

The consent page says “This authorization request has expired”. The consent link is valid for 10 minutes. Start the connection again from your MCP client.

The connector asks me to sign in again and again. Access tokens live one hour and are refreshed silently. A connector left unused for 30 days has to sign in again. If refresh fails sooner, someone may have revoked the connection on the Docs Insights page, or your membership changed. Reconnect the connector.

The consent page says “MCP access requires a paid plan for this workspace”. The workspace is on the Free plan, so Allow access stays disabled. Upgrade, or ask the owner to. If the plan changes to Free after you connected, tool calls fail with “MCP access is not included in the free plan”.

A tool answers insufficient_scope. Your token or connection only has read access. Owners and admins can reconnect and grant the write scope; members cannot.

trigger_source_resync answers resync_unsupported. The source is an upload, not a website, Confluence or Notion source. Upload the updated file in the dashboard, then verify with search_docs.

The recommendation says retrieval_failure but I am sure the page is wrong. The bot found a page that appears to cover the topic. Open it with get_page and read the matched section; if the text really is wrong, edit it anyway and mark the item as docs_updated. If the page is right, report the retrieval problem to the workspace admin.

Claude.ai cannot reach the endpoint. The endpoint must be reachable from the public internet. Custom-domain and staging setups behind an access proxy are not reachable by Anthropic’s or OpenAI’s servers.