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). The design tools need a key created with design access, in the same way (a Read only key can then read the design, a Read & write key can also change and publish it). See Scopes.

• Kind follows each tool's MCP annotations, which are in tools/list. Read-only tools change nothing (readOnlyHint: true). Destructive tools carry destructiveHint: true, so MCP clients can ask you before running them: they can change or remove something that already exists, or change what readers see. Writes marks the remaining tools, which only add something.

• 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>'. The one argument the tables below do not repeat is site_id, which every tool except helpcenter_list_sites takes. See Choose the help center, below.

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

Choose the help center

Every tool except helpcenter_list_sites takes this argument, in addition to the ones listed for it:

• One help center: a connection that reaches one help center needs no site_id.

• Several help centers: a call without site_id is refused, and nothing is changed. The text starts with Error: This connection reaches more than one help center and this call did not say which and lists the ids.

• An id the connection does not reach: refused with Error: This authorization does not cover help center 1234.

• A pinned connection (?site=<id> on the server URL) acts on its help center without site_id, and refuses a different id before any request is made.

• An API key acts on the help center it was created in, and refuses a different id before any request is made.

See Choose which help center a request acts on.

What tools return

• Every successful call returns the API's response in structuredContent. Two design tools return a part of it instead: see helpcenter_get_template_guide and helpcenter_get_template.

• 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. helpcenter_get_template_guide is the exception: it always answers in markdown.

• Write tools return the response as JSON text. The design write tools return a short summary as text instead: where the draft stands, the link to review it, and any results and warnings.

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

Design

The design tools work on the draft that the template editor opens. An agent edits the draft, a person reviews it in the template editor with a live preview, and visitors see nothing until helpcenter_publish_template. The tools call the design endpoints of the REST API: the design document, every operation and every error are in Design API.

• Two checks on every call. The connection needs design.read or design.write, which content.read and content.write don't include, and the person behind the credential must be able to edit the design in the dashboard: an Owner, Admin or Editor. Without that access, the call is refused with design_forbidden.

• Help centers that use the template editor. On a help center that hasn't switched to the template editor yet, every design tool is refused with template_migration_required and the link to its template editor. The agent is told not to retry and to pass the link on: switching is the owner's decision, made in the dashboard.

• The etag. The tools that need design.write take an optional etag: the draft's etag from the agent's last read or write. If the draft changed since, because someone saved in the template editor or another agent wrote to it, the call is refused with stale_draft and nothing changes. Without etag, the call applies to the draft as it is at that moment.

• Text is in the default language. The tools set design texts in the help center's default language. Translations of design texts are made in the dashboard, and they stay with their components when an agent moves or copies them.

helpcenter_get_template_guide

Reads the customization guide: what can be changed in the design and how, built from the components and settings the API accepts. Calls GET /v1/template/schema. Read-only.

Returns the guide as markdown, with the guide object of the API's response in structuredContent. It takes no response_format. What each topic holds is under Read the customization guide in Design API.

The tool's description tells the agent to read the overview before its first design edit, and a component's settings before it adds or configures that component: a setting takes only the values the template editor offers.

helpcenter_get_template

Reads the design draft: where it stands, the link to review it in the template editor, and an outline of every page, or one part of the draft in full. Calls GET /v1/template for the outline and GET /v1/template/draft for a part. Read-only.

The outline returns {status, template, outline}. template says where the design stands, with the draft's etag in template.draft.etag and the link to review the draft in template.urls.customizer. outline lists every component with its id, its type and the settings that differ from its defaults.

A part returns {section, etag, data}. A part that is too large for one answer, over 25,000 characters, comes back as a text that names the smaller parts to read, without structuredContent. If the help center has no draft yet, reading starts one from the live design.

helpcenter_list_template_themes

Lists the themes a help center can start from, or describes one of them. Calls GET /v1/template/themes, or GET /v1/template/themes/{themeKey} when you name a theme. Read-only.

Returns {status, themes}, each theme with its key, name, tagline, summary, best_for, palettes, fonts, density and preview_image. current is true for the theme the draft came from. With theme, it returns {status, theme}, which adds the theme's description, screenshots, anatomy (what each page is built from), changed_sections (the sections of the draft that applying the theme would change) and sections (every section you can apply). An unknown key is refused with unknown_theme, and the message lists the keys.

helpcenter_apply_template_theme

Copies a theme onto the draft: all of it, or only the sections you name. Calls POST /v1/template/themes/{themeKey}/apply. Destructive: each section it applies replaces that part of the draft. The live design does not change.

Returns {status, applied, warnings, template}. applied names the theme and the sections that were applied, and template carries the draft's new etag.

• Component ids change. Applying a page replaces its components, with new ids, so the agent reads the draft again before it edits them. Applying customCss replaces your custom CSS blocks.

• Without sections, the draft also takes the theme's brand and meta: the theme's placeholder name and tagline instead of yours, no logo or favicon, and the theme's SEO title and description. To give the current design a theme's look and keep its layout, apply only theme.colors, theme.darkColors, theme.fonts, theme.radius and theme.density. See Apply a theme in Design API.

helpcenter_update_template

Edits the draft with a batch of operations, applied in order, all or nothing. Calls PATCH /v1/template/draft. Destructive: operations can replace or remove parts of the draft. The live design does not change.

Returns {status, results, warnings, template}. results has one entry per operation, in order, with the id of each new component, CSS block or script, and template carries the draft's new etag. The fields of every operation are under Operations in Design API.

• All or nothing. When one operation can't be applied, nothing is saved. The refusal, template_invalid, names the operation, the setting and what would have been accepted, and the agent is told to fix that operation and send the whole batch again.

• Operations are strict too. A field an operation does not list is refused before any request is made.

• Synced regions whose pages differ. An edit to a region that every page shares, but whose pages hold different content, is refused until the agent chooses with sync_region: keep each page's version, or make every page use one page's version.

• Custom CSS and scripts run in every visitor's browser once the design is published. The tool's description tells the agent to add a script only when you asked for it.

helpcenter_publish_template

Puts the draft live: visitors see the new design from then on. It is the only design tool that changes the live help center. Calls POST /v1/template/publish. Destructive.

Returns {status, published, template}: published is the new live version, and template the draft that starts from it, with a new etag.

• The whole draft goes live, including changes people made in the template editor, and brand.name becomes the help center's name.

• Nothing to publish. A draft that is the same as the live design is refused with nothing_to_publish.

• Publish after the review. The tool's description tells the agent to publish only when you ask for it, ideally after you reviewed the draft in the template editor.

helpcenter_discard_template_changes

Resets the draft to the live design. Calls POST /v1/template/draft/discard. Destructive: every unpublished change is lost, including changes people made in the template editor, and it can't be undone. The live design does not change.

Returns {status, template}.

helpcenter_list_template_versions

Lists the published versions of the design, newest first, with the live one marked. Calls GET /v1/template/versions. Read-only.

Returns {status, versions}, each {id, status, live, message, preset_key, published_at, published_by}, up to 50.

helpcenter_restore_template_version

Loads an earlier published version into the draft. Calls POST /v1/template/versions/{versionId}/restore. Destructive: the version replaces what the draft holds. It does not go live: visitors see it only after helpcenter_publish_template, so it can be reviewed like any other change.

Returns {status, restored, template}, where restored is the version's id. An id that is not a version of this help center is refused with version_not_found.

Help centers

helpcenter_list_sites

Lists the help centers the connection can reach, with their ids. Calls GET /v1/sites. Read-only. It describes the connection, not one help center, so it takes no site_id. That makes it the way out of site_required: list the ids, then pass one as 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

• Design API