MCP tool reference

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. For plans, sign-in and the security model, see The HelpCenter.io MCP server.

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.

• 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.

All tools

Articles

Article objects are the REST API's, with every language in per-language maps. See Articles for every field.

helpcenter_search_articles

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

helpcenter_list_categories

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

helpcenter_create_category

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

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}.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

Related

• Connect an AI assistant to your help center

• The HelpCenter.io MCP server

• Scopes