# MCP tool reference

_Category: AI agents and MCP_

Every tool of the HelpCenter.io MCP server at `https://mcp.helpcenter.io`: what it does, its arguments, the permission it needs, the REST API endpoint behind it and what it returns. To connect a client first, see [Connect an AI assistant to your help center](https://developers.helpcenter.io/content/connect-an-ai-assistant-to-your-help-center). For plans, sign-in and the security model, see [The HelpCenter.io MCP server](https://developers.helpcenter.io/content/the-mcp-connector-for-ai-agents).

## How to read this reference

- **Permission** is the OAuth permission (scope) the tool needs. An API key covers the same ground: a **Read only** key holds `content.read` and `analytics.read`, a **Read & write** key adds `content.write`, and the team notes tools need a key created with team notes access (a **Read only** key can then read notes, a **Read & write** key can also reply and resolve). See [Scopes](https://developers.helpcenter.io/content/scopes).
- **Read-only** tools change nothing. **Destructive** tools can throw work away or change what readers see, and carry `destructiveHint: true` so MCP clients can ask you first. Every tool's annotations are in `tools/list`.
- **Arguments are strict.** An argument a tool does not list is refused before any request is made, with `Input validation error` and `Unrecognized key(s) in object: '<name>'`. No tool takes a help center argument: the connection decides the help center.
- **Per-language fields** (`title`, `content` and `slug` of articles, `name` and `description` of categories) are objects keyed by language code, for example `{"en": "Getting started"}`. Keys must be two letters, optionally followed by a hyphen and two more letters, such as `en` or `de-AT`, so the tools refuse `zh-Hans`, `zh-Hant`, `fil` and `mul` today, although help centers can publish in those languages. A language your help center does not publish in is refused with `Unsupported language key "de" provided.`

### What tools return

- Every successful call returns the API's response in `structuredContent`.
- Read tools take `response_format`: `markdown` (the default) puts a short readable summary in the text, without article bodies; `json` puts the full response in the text. Write tools always return the response as JSON text.
- The four list tools (`helpcenter_search_articles`, `helpcenter_list_articles`, `helpcenter_list_categories`, `helpcenter_list_comments`) wrap the API's list in `{total, count, page, per_page, total_pages, has_more, items}`.
- In `json` format, a list longer than 25,000 characters is cut to half its items and gains `"truncated": true` and a `truncation_message`. The next `page` starts after the full page, so the items cut this way are never returned: when you see `truncated`, ask again with a smaller `limit` instead of paging on.
- A failed call returns `isError: true` and a text that says what went wrong and what to do, usually starting with `Error:`. The common ones are in the troubleshooting section of [Connect an AI assistant to your help center](https://developers.helpcenter.io/content/connect-an-ai-assistant-to-your-help-center).

## All tools

| Tool | What it does | Permission | Kind |
| --- | --- | --- | --- |
| `helpcenter_search_articles` | Search published articles | `content.read` | Read-only |
| `helpcenter_list_articles` | List every article, drafts included | `content.read` | Read-only |
| `helpcenter_get_article` | Read one article | `content.read` | Read-only |
| `helpcenter_create_article` | Create an article, or update the one with the same `external_id` | `content.write` | Writes |
| `helpcenter_update_article` | Change an article, live | `content.write` | Writes |
| `helpcenter_bulk_create_articles` | Create or update up to 50 articles | `content.write` | Writes |
| `helpcenter_get_staged_changes` | Read the unpublished edits on an article | `content.read` | Read-only |
| `helpcenter_stage_article_changes` | Stage an edit to a published article | `content.write` | Writes |
| `helpcenter_publish_staged_changes` | Publish staged edits | `content.write` | Writes |
| `helpcenter_discard_staged_changes` | Throw staged edits away | `content.write` | Destructive |
| `helpcenter_list_article_versions` | List earlier published versions | `content.read` | Read-only |
| `helpcenter_restore_article_version` | Put an earlier version back live | `content.write` | Destructive |
| `helpcenter_list_categories` | List categories | `content.read` | Read-only |
| `helpcenter_create_category` | Create a category | `content.write` | Writes |
| `helpcenter_update_category` | Change a category or move it | `content.write` | Writes |
| `helpcenter_delete_category` | Delete a category and re-file what it holds | `content.write` | Destructive |
| `helpcenter_reorder_categories` | Set the order of categories | `content.write` | Writes |
| `helpcenter_reorder_category_articles` | Set the order of articles in a category | `content.write` | Writes |
| `helpcenter_list_comments` | List reader comments, the moderation queue | `content.read` | Read-only |
| `helpcenter_get_article_comments` | Read one article's comment threads | `content.read` | Read-only |
| `helpcenter_moderate_comment` | Approve or unpublish a comment | `content.write` | Writes |
| `helpcenter_reply_to_comment` | Post a reply or a comment | `content.write` | Writes |
| `helpcenter_get_analytics_summary` | Traffic, ratings and activity for a period | `analytics.read` | Read-only |
| `helpcenter_get_content_performance` | Views and ratings per article | `analytics.read` | Read-only |
| `helpcenter_get_search_queries` | What readers searched for and did not find | `analytics.read` | Read-only |
| `helpcenter_list_article_notes` | Read team notes on an article | `notes.read` | Read-only |
| `helpcenter_reply_to_article_note` | Reply to a team note | `notes.write` | Writes |
| `helpcenter_resolve_article_note` | Mark a team note resolved | `notes.write` | Writes |
| `helpcenter_list_sites` | List the help centers the connection can reach | `content.read` | Read-only |
| **29 tools** |  |  |  |

## Articles

Article objects are the REST API's, with every language in per-language maps. See [Articles](https://developers.helpcenter.io/content/articles-api) for every field.

### `helpcenter_search_articles`

Searches article titles and content by keyword. Calls `GET /v1/articles?search=`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `query` | string | Required. The words to search for. |
| `lang` | string | The help center's default language when omitted. The language to search in. |
| `category_id` | integer | Only articles in this category. |
| `limit` | integer, 1-100 | Default `100`. Results per page. |
| `page` | integer, 1 or more | Default `1`. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns the list envelope with full article objects in `items`. Search finds what an anonymous reader could find: published, public articles in public categories, and released translations. It returns at most 15 matches whatever `limit` says, and `total` then reports 15 even when more articles match. On a help center whose default language is not English, it finds only articles that also have a released English translation. To go through every article, use `helpcenter_list_articles`.

### `helpcenter_list_articles`

Lists every article that is not in the Trash: drafts, private and link-only articles included. Calls `GET /v1/articles`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `category_id` | integer | Only articles in this category. |
| `order_by` | `views` | Most recently updated first when omitted. `views` orders by view count. |
| `order_type` | `asc` or `desc` | Default `desc`. Direction for `order_by`. |
| `lang` | string | Has no effect on a list: every article comes back with all its languages. |
| `limit` | integer, 1-100 | Default `100`. |
| `page` | integer, 1 or more | Default `1`. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

The tool cannot filter by status or by date. The REST API can, with `status` and `updated_since`.

### `helpcenter_get_article`

Reads one article, including whether staged edits are waiting on it (`has_staged_changes`, `staged_locales`, `staged_updated_at`). Calls `GET /v1/articles/{id}`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `response_format` | `markdown` or `json` | Default `markdown`, a summary without the body. Use `json`, or `structuredContent`, for the content. |

Returns `{status, article}`. The API counts this read against the 120-a-minute write limit.

### `helpcenter_create_article`

Creates an article. With an `external_id` it is an upsert: the same key again updates the article it created. Calls `POST /v1/articles`.

| Argument | Type | Description |
| --- | --- | --- |
| `title` | per-language object | Required. For example `{"en": "Close your account"}`. |
| `content` | per-language object | The body, in HTML or Markdown (see `content_format`). |
| `slug` | per-language object | Made from the title when omitted. |
| `category_id` | integer, 0 or more | The primary category. `0` leaves the article uncategorized. |
| `categories` | array of integers | Leave it out: a new article sent with `categories` is not saved. Create it with `category_id`, then put it in several categories with `helpcenter_update_article`. |
| `type` | `article` or `faq` | Default `article`. |
| `visibility` | `public`, `private` or `link_only` | Default `public`. `link_only` is not kept on create: see below. |
| `published` | boolean | Default `false`: the article is saved as a draft. |
| `external_id` | string, up to 191 characters | A stable key you own, such as a file path or a CMS id. |
| `content_format` | `html` or `markdown` | Default `html`. Send `markdown` with Markdown content and it is converted to HTML; without it, the Markdown is stored as it is. |

Returns `{status, action, article}`, plus `images` when you send `content`. `action` is `created`, or `updated` when the `external_id` matched an article. This is the `images` report of an article with one embedded image and one image on a private address:

```
{
  "rehosted": 1,
  "reused": 0,
  "failed": [
    {
      "src": "http://127.0.0.1:9/nothing.png",
      "reason": "the host resolves to a private or reserved address"
    }
  ],
  "failed_count": 1
}
```

- **Images are copied in.** Images in `content` that point to other websites, or are embedded as `data:` URLs, are copied into your help center's storage, up to 25 per article, and `images` reports what happened. An image that cannot be copied keeps its original address and is listed in `failed` with a reason.
- **`link_only` is lost on create.** The article is saved `public`, with a share token. For a link-only article, create it as a draft (leave out `published`), then send `visibility: "link_only"` and `published: true` together in one `helpcenter_update_article` call, so readers never see it without the link.
- **Use `external_id` for anything that may run twice.** Without it, every retry creates another article.

### `helpcenter_update_article`

Changes an article. Calls `PATCH /v1/articles/{id}`. On a published article, readers see the change at once: stage it instead to review it first.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `title`, `content`, `slug`, `category_id`, `categories`, `type`, `visibility`, `published`, `external_id`, `content_format` | as in `helpcenter_create_article` | All optional. Only what you send changes. `published: false` unpublishes the article. `categories` puts the article in exactly the categories you list, and it then reports `"category_id": -1`. |

Returns `{status, article}`, plus `images` when you send `content`. An `external_id` that already belongs to another article is refused with `That external_id already belongs to another article.`

### `helpcenter_bulk_create_articles`

Creates or updates several articles in one request, for imports and migrations. Calls `POST /v1/articles/bulk`.

| Argument | Type | Description |
| --- | --- | --- |
| `articles` | array of article objects | Required. Each item takes the arguments of `helpcenter_create_article`. Send at most 50: see below. |

Returns `{status, results, meta}`, where `meta` counts `total`, `created`, `updated` and `failed`. Each result is `{index, status, article, images}` with `status` `created` or `updated`, or `{index, status: "error", external_id, error}` for an item that failed (`external_id` when the item had one), with `error.code` one of `invalid_item`, `validation_error`, `invalid_argument`, `external_id_busy` and `persist_failed` (for example a new article sent with `categories`). One failed item does not stop the others.

The tool accepts up to 100 items, but the API takes at most 50. A call with 51 to 100 items fails as a whole, and the agent only reads `The request could not be accepted.` Keep batches at 50 or fewer, each item with an `external_id`.

## Staged changes and versions

Staging lets an agent prepare an edit to a published article without readers seeing it. Staging an edit needs staged changes on the help center, part of the Catalyst plan in early preview; otherwise `helpcenter_stage_article_changes` is refused with `STAGING_UNAVAILABLE`. Staged edits are kept per language. See [Staged changes and versions](https://developers.helpcenter.io/content/staged-changes-api) for the objects and errors.

### `helpcenter_get_staged_changes`

Reads the unpublished edits waiting on an article, with the `etag` to pass when you stage again. Calls `GET /v1/articles/{id}/staged`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `locale` | string | One language. Every staged language when omitted. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, staged}`: one object when you name a `locale`, otherwise an array. Each has `article_id`, `locale`, `fields`, `shared`, `release_translation`, `etag`, `shared_etag`, `base_signature`, `updated_at` and `_links`. The API counts this read against the write limit.

### `helpcenter_stage_article_changes`

Saves an edit to a published article without readers seeing it. Calls `PATCH /v1/articles/{id}/staged`.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. A published article. |
| `locale` | string | Required. The language of this edit, one of your help center's language codes, for example `en` or `de`. |
| `title`, `content`, `slug` | string | Plain strings for this language, not per-language objects. `content` is HTML. A new title does not change the URL: send `slug` to do that. |
| `category_id`, `categories`, `visibility` | as in `helpcenter_create_article` | Shared by every language of the article. |
| `release_translation` | boolean | `true` releases this language to readers when the edit is published. |
| `etag` | string | The `etag` from your last read. When someone else changed the staged copy since, the call is refused with `STALE_ETAG` instead of overwriting their edit. |

Returns `{status, staged}`. On an article that isn't published, the call is refused with `NOT_PUBLISHED`, and the agent is told to use `helpcenter_update_article`.

### `helpcenter_publish_staged_changes`

Publishes staged edits, so readers see them. Calls `POST /v1/articles/{id}/staged/publish`.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `locale` | string | One language. Every staged language when omitted. |
| `force` | boolean | Publish even when the live article changed after the edit was staged, which is otherwise refused with `BASE_CHANGED`. The live change is lost. |

Returns `{status, published_locales, article}`. If the article was unpublished in the meantime, the staged edit is still applied and the article stays unpublished.

### `helpcenter_discard_staged_changes`

Throws staged edits away. The live article does not change. Calls `DELETE /v1/articles/{id}/staged`. Destructive: a discarded edit cannot be recovered.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `locale` | string | One language. Every staged language when omitted. |

Returns `{status, discarded, article}`, where `discarded` counts the staged languages removed. On an article with nothing staged, the tool answers not found: `This article has no staged changes to discard.`

### `helpcenter_list_article_versions`

Lists an article's earlier published versions, newest first. Calls `GET /v1/articles/{id}/versions`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `response_format` | `markdown` or `json` | Default `markdown`. The markdown summary shows every date as `archived unknown`; use `json` for `published_at`. |

Returns `{status, versions}`, each `{id, locale, title, published_at, _links}`, at most 20 across all languages. HelpCenter.io keeps 20 versions per language. A version is recorded when staged changes are published or a version is restored, so an article that was never staged has none. This tool and the next need no Catalyst plan. The API counts this read against the write limit.

### `helpcenter_restore_article_version`

Puts an earlier version back live. Calls `POST /v1/articles/{id}/versions/{versionId}/restore`. Destructive: readers see the restored version at once.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `version_id` | integer | Required. An `id` from `helpcenter_list_article_versions`. |

Returns `{status, article}`. The version it replaced is kept in the history, so you can restore it back.

## Categories

Category objects are `{id, parent, name, description, icon, position, privacy, created_at, updated_at}`. See [Categories](https://developers.helpcenter.io/content/categories-api).

### `helpcenter_list_categories`

Lists every category of the help center. Calls `GET /v1/categories`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `limit` | integer, 1-100 | Default `100`. |
| `page` | integer, 1 or more | Default `1`. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

### `helpcenter_create_category`

Creates a category, at the top level or inside another one. Calls `POST /v1/categories`.

| Argument | Type | Description |
| --- | --- | --- |
| `name` | per-language object | Required. For example `{"en": "Billing"}`. Up to 190 characters per language. |
| `description` | per-language object | Optional. |
| `parent_id` | integer | A category of this help center. `0` or omitted makes a top-level category. |
| `icon` | string, up to 190 characters | An icon identifier. |
| `position` | integer, 0 or more | Order among its siblings, ascending. When omitted, the category goes after the ones you have ordered. |

Returns `{status, category}`. When you leave out `position`, the response shows `"position": 0` although the category is stored after the others: list the categories to see the stored order. New categories are always public. To make one private, use the dashboard.

### `helpcenter_update_category`

Renames a category, changes its description, icon or position, or moves it. Calls `PATCH /v1/categories/{id}`.

| Argument | Type | Description |
| --- | --- | --- |
| `category_id` | integer | Required. |
| `name`, `description` | per-language object | Optional. |
| `parent_id` | integer | The new parent: a category of this help center, but not the category itself or one beneath it. `0` moves it to the top level. |
| `icon` | string, up to 190 characters | Optional. |
| `position` | integer, 0 or more | Order among its siblings. `0` puts it first. |

Returns `{status, category}`. The tool cannot change a category's privacy.

### `helpcenter_delete_category`

Deletes a category. Calls `DELETE /v1/categories/{id}`. Destructive. It never deletes articles: it re-files them.

| Argument | Type | Description |
| --- | --- | --- |
| `category_id` | integer | Required. |
| `on_orphan` | `refuse`, `uncategorize` or `reparent` | Default `refuse`: a category that still holds articles or subcategories is not deleted. `uncategorize` moves its articles to Uncategorized and its subcategories to the top level. `reparent` moves both up to the category's own parent. |

Returns `{status, message, on_orphan, articles_moved, children_moved, trashed_articles_refiled, trashed_children_refiled, moved_to}`. A refused delete tells the agent what the category holds, for example `It holds 1 article.`, and asks it to choose `uncategorize` or `reparent`.

### `helpcenter_reorder_categories`

Sets the order of many categories in one call. Calls `PUT /v1/categories/order`.

| Argument | Type | Description |
| --- | --- | --- |
| `categories` | array of `{id, position}`, 1 to 500 items | Required. The categories in the order you want. Leave out `position` to use each entry's place in the list. |

Returns `{status, message, updated_count, categories}`.

### `helpcenter_reorder_category_articles`

Sets the order of the articles in one category. Calls `PUT /v1/categories/{id}/articles/order`.

| Argument | Type | Description |
| --- | --- | --- |
| `category_id` | integer | Required. |
| `articles` | array of `{id, position}`, 1 to 1,000 items | Required. Leave out `position` to use each entry's place in the list. Ids that are not in the category are skipped. |

Returns `{status, message, updated_count, skipped_article_ids, order_visible, article_sort, article_sort_source, hint}`. Readers see this order only when the help center's category pages sort articles by Custom: check `order_visible`, and read `hint` when it is `false`.

## Comments

Comment objects leave out the commenter's email address and IP address, and team notes never appear in these tools. See [Comments](https://developers.helpcenter.io/content/comments-api) for the fields.

### `helpcenter_list_comments`

Lists reader comments across the help center, for example the ones waiting for approval. Calls `GET /v1/comments`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `status` | `pending`, `published`, `unpublished`, `deleted` or `all` | Everything except deleted comments when omitted. `pending` is the moderation queue. |
| `article_id` | integer | Only this article's comments. |
| `lang` | string | A language the help center publishes in. |
| `search` | string, up to 190 characters | Text the comment contains. |
| `order` | `asc` or `desc` | Default `desc`, newest first. |
| `limit` | integer, 1-100 | Default `25`. |
| `page` | integer, 1 or more | Default `1`. |
| `include_email` | boolean | Does not work today: leave it out. See below. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns the list envelope plus `status_counts`, the number of comments in each state. A call with `include_email: true` fails today, whatever the credential, so the tools cannot return email addresses.

### `helpcenter_get_article_comments`

Reads one article's comments as threads, with each reply under the comment it answers. Calls `GET /v1/articles/{id}/comments`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `status` | as in `helpcenter_list_comments` | Everything except deleted comments when omitted. |
| `lang` | string | Only comments in this language. |
| `order` | `asc` or `desc` | Default `asc`, oldest first. |
| `include_email` | boolean | Does not work today, as in `helpcenter_list_comments`. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, article, comments, meta}`, with `meta.threads_count` and `meta.comments_count`. The whole conversation comes back in one call, without paging.

### `helpcenter_moderate_comment`

Approves a comment, or unpublishes it to take it off the article. Calls `PATCH /v1/comments/{id}`. It cannot delete a comment.

| Argument | Type | Description |
| --- | --- | --- |
| `comment_id` | integer | Required. |
| `status` | `published` or `unpublished` | Required. `published` shows it to readers. |

Returns `{status, message, comment}`. Approving a reply emails the author of the comment it answers, once, as approving it in the dashboard does.

### `helpcenter_reply_to_comment`

Posts a reply to a comment, or a new comment on an article, in the name of the person behind the connection. Calls `POST /v1/articles/{id}/comments`. The comment is published at once.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `comment` | string, 1 to 5,000 characters | Required. Plain text: HTML is shown as text, not as formatting. |
| `parent_id` | integer | The comment to answer, on the same article. A new top-level comment when omitted. |
| `lang` | string | The parent comment's language, else the help center's default, when omitted. |

Returns `{status, message, comment}`. Calling it twice posts two comments: read the thread before retrying.

## Analytics

The three analytics tools share a limit of 6 requests a minute per credential, on top of the API's other limits. Traffic, view and search figures are computed once a day, so asking again for the same period returns the same numbers; ratings, activity and totals are current. Over the limit, the agent is told not to retry. Without `from` and `to`, a report covers the last 7 days; a range can be at most 92 days. The fields are in [Analytics](https://developers.helpcenter.io/content/analytics-api).

### `helpcenter_get_analytics_summary`

Visitors, searches, article views, ratings and your team's activity for a period, compared with the period before. Calls `GET /v1/analytics/summary`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `from`, `to` | string, `YYYY-MM-DD` | The period, both days included. The last 7 days when omitted; `to` defaults to today. |
| `lang` | string | Only this language. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, range, summary}`, with `summary.traffic`, `summary.ratings`, `summary.activity` and `summary.totals`.

### `helpcenter_get_content_performance`

Views and ratings for each article that was viewed in the period. Calls `GET /v1/analytics/content`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `from`, `to`, `lang` | as in `helpcenter_get_analytics_summary` | Optional. |
| `sort` | `views_desc`, `views_asc` or `rating_asc` | Default `views_desc`. `rating_asc` puts the worst-rated first. |
| `category_id` | integer | Only articles in this category. |
| `limit` | integer, 1-100 | Has no effect today: every page holds 25 articles. |
| `page` | integer, 1 or more | Default `1`. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, range, excludes_never_viewed, articles, meta}`. Articles nobody viewed in the period are not listed.

### `helpcenter_get_search_queries`

What readers searched for, and which searches found nothing: a list of articles you have not written yet. Calls `GET /v1/analytics/searches`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `from`, `to`, `lang` | as in `helpcenter_get_analytics_summary` | Optional. |
| `limit` | integer, 1-50 | Default `20`. Rows per list. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, range, content_gaps, frequent_queries, common_terms, meta}`. The lists are the top entries only.

## Team notes

Team notes are the private notes your team leaves on articles; readers never see them. Every call also checks that the person behind the credential still has access to team notes on the help center, and answers `notes_forbidden` when they do not. See [Team notes](https://developers.helpcenter.io/content/team-notes-api).

### `helpcenter_list_article_notes`

Reads the open notes on an article, each tied to the passage it is about. Calls `GET /v1/articles/{id}/notes`. Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `include_resolved` | boolean | Does not work today: `true` fails with `The request could not be accepted.` Leave it out. |
| `lang` | string | Only notes in this language. |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, article, notes, meta}`. Each note has `id`, `note`, `anchor` (`mark_id` and `quote`, the highlighted passage), `author`, `resolved`, `replies` and `_links`. `meta` has `threads_count`, `open_count` and `includes_resolved`.

### `helpcenter_reply_to_article_note`

Replies to a note. The reply stays internal. Calls `POST /v1/articles/{id}/notes/{noteId}/replies`.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `note_id` | integer | Required. The note thread to answer. |
| `note` | string, 1 to 5,000 characters | Required. Plain text. |

Returns `{status, message, note}`, the thread with the new reply in `replies`. Calling it twice posts two replies.

### `helpcenter_resolve_article_note`

Marks a note as done. Calls `POST /v1/articles/{id}/notes/{noteId}/resolve`.

| Argument | Type | Description |
| --- | --- | --- |
| `article_id` | integer | Required. |
| `note_id` | integer | Required. |

Returns `{status, message, id}`.

## Help centers

### `helpcenter_list_sites`

Lists the help centers the connection can reach, with their ids. Calls `GET /v1/sites`. Read-only. It works before a help center is chosen, which makes it the way out of `site_required`: list the ids, then connect with `?site=<id>`.

| Argument | Type | Description |
| --- | --- | --- |
| `response_format` | `markdown` or `json` | Default `markdown`. |

Returns `{status, sites, meta}`. Each site has `id`, `uuid`, `name`, `subdomain`, `domain`, `url`, `default_language`, `visibility`, `publicly_accessible`, `languages` and `created_at`. With an API key it lists the key's one help center. See [Sites and account](https://developers.helpcenter.io/content/sites-and-account-api).

## Related

- [Connect an AI assistant to your help center](https://developers.helpcenter.io/content/connect-an-ai-assistant-to-your-help-center)
- [The HelpCenter.io MCP server](https://developers.helpcenter.io/content/the-mcp-connector-for-ai-agents)
- [Scopes](https://developers.helpcenter.io/content/scopes)