---
doc_version: "1.0.0"
last_updated: "2026-10-19T08:44:17.368Z"
title: "How to close the documentation feedback loop with MCP"
description: "Connect Claude, ChatGPT or Claude Code to the ChatbotIQ Insights MCP server to review problem conversations and user content reports, find the page and section to fix, and mark items as addressed."
keywords: [MCP, Insights, negative feedback, user feedback, documentation owner, knowledge gaps, Claude, ChatGPT, Claude Code, OAuth, personal access token, ChatbotIQ]
---

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](/how-to/set-up-mcp-integration/). 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

```bash
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:

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

## Sitemap

Full documentation index: [sitemap.md](/sitemap.md) and [llms.txt](/llms.txt).