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. The agent endpoint, https://mcp.helpcenter.io/agent, for an agent building a help center for someone who has no account, has its own section at the end of this page.

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 six list tools (helpcenter_search_articles, helpcenter_list_articles, helpcenter_list_categories, helpcenter_list_comments, helpcenter_list_change_sets, helpcenter_list_images) wrap the API's list in {total, count, page, per_page, total_pages, has_more, next, items}.

• A list page is cut to fit when it comes to more than 25,000 characters of text, or more than 5 MB in all. Article bodies become 300-character excerpts first (content_truncated: true); if that is not enough, the page keeps the longest prefix that fits, with truncated: true and a truncation_reason of character_limit or response_size. Every list page carries next, the page and limit that fetch the first item it did not return, or null when nothing is left. Follow next instead of asking for page + 1, which would skip the items that were cut. To go through a large help center, pass include_content: false to helpcenter_list_articles or helpcenter_search_articles: without bodies, far more articles fit in a page.

• No reply is sent over 5.9 MB, the most one response can carry, whichever tool made it. A larger one is replaced by a tool error that starts The reply to <tool> came to <n> MB, over the 5.9 MB one HelpCenter.io connector response can carry, so it was not sent and says to ask for less: a smaller limit, a filter, or one item at a time. Only the reply is withheld. A write whose answer was too large has already taken effect, so read before you repeat it. A list page whose first item alone is over 5 MB comes back as a tool error that names the item and gives the page and limit that continue past it.

• 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, or, with include_content: false, the inventory entries described under helpcenter_list_articles. Search finds what an anonymous reader could find: published, public articles in public categories, in the language searched (in an additional language, only released translations). It returns every match, best first, up to the 1,000 best ranked: total counts them, and limit and page, or next, page through them. A lang the help center does not have is a tool error that says lang: That language is not enabled on this help center. To go through every article, drafts included, 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.

With include_content: false, items holds an inventory instead of full articles, to decide what to read in full with helpcenter_get_article. Each entry has id, external_id, title, slug, type, category_id, categories, published, visibility, views, has_staged_changes, staged_locales, staged_updated_at, updated_at and content_length: the length of each language's body in characters, for example {"en": 5231}.

For an incremental sync, pass the newest updated_at of your last pass as updated_since. The bound is inclusive, so that article comes back again: skip it by id. With status: "draft" the same call lists the drafts changed since then.

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 and leave rehost_images on. 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. Send rehost_images: false to keep every original address.

• 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 and leave rehost_images on. 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.

rehost_images is set per item, and images is left out of a result whose item has no content or sends rehost_images: false. All items of one call share a single time budget for downloading images. An article is saved even when some of its images could not be copied, so check failed_count in each result.

A call with more than 50 items is refused before any request is made, with Input validation error and Send at most 50 articles per batch; split a larger import into several batches, and nothing is written. Send a larger import in batches of 50 or fewer, each item with an external_id.

helpcenter_delete_article

Moves an article to the help center's Trash. Calls DELETE /v1/articles/{id}. Destructive: readers can no longer reach the article, its URL stops resolving, and links to it from other articles break. Only a person can bring it back, from the dashboard's Trash: no tool restores it. A change set that holds the article refuses to publish until that item is removed. To take an article off the help center and keep it editable, send helpcenter_update_article with published: false instead.

Returns {status, message, article}, where article is {id, deleted_at}. An article that is not in this help center, or is already in the Trash, answers as not found.

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

Change sets

A change set is a named release. It groups staged edits to published articles, drafts that have never been published and category visibility changes, and publishes all of them together, now or at a scheduled time. It owns no content, so removing an item or deleting the change set never deletes the work in it. Change sets are part of the Catalyst plan, in early preview, and a help center can have at most 25 open ones. The plan, the early preview and every error are in Change sets.

The flow: stage edits with helpcenter_stage_article_changes, or write drafts with helpcenter_create_article and published: false; create the change set; add the items; check that it is ready with helpcenter_get_change_set; publish it; then poll helpcenter_get_change_set_status until done is true.

helpcenter_list_change_sets

Lists the help center's change sets, most recently changed first. Calls GET /v1/change-sets. Read-only. Check it before creating one: the release may already exist.

Returns {total, count, page, per_page, total_pages, has_more, next, items}. Each item is {id, name, description, status, is_scheduled, scheduled_for, published_at, release_note, items_count, processed_items, total_items, created_at, updated_at}.

helpcenter_get_change_set

Reads one change set: its items, its schedule and whether it is ready to publish. Calls GET /v1/change-sets/{id}. Read-only. Call it before publishing.

Returns {status, change_set}. The change_set has the fields of a list item plus readiness, {counts, locales, articles, blockers, warnings, publishable}, and items, each {id, type, article_id, category_id, locale, variant, payload, applied, error}.

• Item types. staged_version is one staged language of a published article, article_publish is a draft the change set will publish, and category_visibility is a category's visibility change, with a payload of {from, to}. The id of an item is what helpcenter_remove_change_set_item takes.

• Blockers and warnings. A blocker stops a publish: the article was deleted, or the live article changed after its edits were staged. A warning never does: an update in one language with no counterpart in another may be deliberate, so the agent is told to pass warnings on rather than decide.

helpcenter_create_change_set

Starts a new, empty change set. Calls POST /v1/change-sets. It is not idempotent: calling it twice makes two change sets with the same name, so the agent lists the open ones first.

Returns {status, change_set} with the new id. A help center that already has 25 open change sets is refused with TOO_MANY_OPEN_CHANGE_SETS.

helpcenter_update_change_set

Renames a change set or changes its description, also after it was published: the name is how a release is found in history. Calls PATCH /v1/change-sets/{id}. Destructive: it changes a change set that exists. The items are not touched.

Returns {status, change_set}.

helpcenter_delete_change_set

Deletes a change set. Calls DELETE /v1/change-sets/{id}. Destructive: the grouping, the release note and any schedule, which is cancelled, are gone, and the API cannot bring them back. The staged edits, drafts and categories in it are not touched: they stay unreleased. To stop a scheduled release but keep it, the agent is told to use helpcenter_unschedule_change_set instead.

Returns {status}. A change set that is publishing is refused with CHANGE_SET_NOT_OPEN.

helpcenter_add_change_set_items

Adds articles and categories to an open change set, many in one call. Calls POST /v1/change-sets/{id}/items. Destructive: it changes a change set that exists. Adding something that is already in the change set is harmless.

Returns {status, added, rejected, change_set}. At least one of article_ids and category_ids must have an entry.

• A partly rejected batch is a normal result. It answers status: "partial" (HTTP 207) and lists each refused id in rejected, as {article_id or category_id, reason}. One bad id never discards the others, so the agent reads rejected instead of assuming everything landed. A reason of not_found means the id is not in this help center.

• What added counts. Items, so an article staged in two languages adds 2. To ship only some languages, remove the other items afterwards.

• Limits. The change set must be open (CHANGE_SET_NOT_OPEN once it is publishing or published) and holds at most 500 items (CHANGE_SET_FULL).

helpcenter_remove_change_set_item

Takes one item out of an open change set. Calls DELETE /v1/change-sets/{id}/items/{itemId}. Destructive: it changes a change set that exists. The staged edit, draft or category the item pointed at is untouched and stops being part of this release. This is how to ship a release without one of its parts.

Returns {status, change_set} with the remaining items. A change set that is publishing or published is refused with CHANGE_SET_NOT_OPEN.

helpcenter_publish_change_set

Publishes every item of a change set together, now or at a scheduled time. Calls POST /v1/change-sets/{id}/publish. Destructive: readers see everything in the change set at once. Each staged edit archives the live version it replaces, so one article can be rolled back afterwards with helpcenter_restore_article_version.

Returns {status: "queued", change_set, status_url}, or {status: "scheduled", change_set} when scheduled_for was given.

• Accepted is not done. The API answers 202 either way. queued means publishing has started in the background and the articles are not necessarily live yet: the agent polls helpcenter_get_change_set_status until done is true, then reads each item's outcome. scheduled means the release is armed and nothing is live yet.

• Readiness is checked first. A change set that is empty, has blockers, or has a scheduled_for in the past is refused with 422, and nothing is published. A change set that is already publishing or published is refused with CHANGE_SET_NOT_OPEN.

helpcenter_unschedule_change_set

Cancels a change set's scheduled publish. Calls DELETE /v1/change-sets/{id}/schedule. Destructive: it changes a change set that exists. The change set stays open with all its items, and nothing is published or lost. Calling it on a change set that is not scheduled is harmless.

Returns {status, change_set} with is_scheduled false. A change set that has already started publishing, or has published, is refused with CHANGE_SET_NOT_OPEN: it is too late to cancel.

helpcenter_get_change_set_status

Checks on a change set's release: the poll after helpcenter_publish_change_set. Calls GET /v1/change-sets/{id}/status. Read-only.

Returns {status, change_set_status, done, processed_items, total_items, published_at, items}, where each item is {id, type, article_id, locale, variant, applied, error}.

• Loop on done, not on the status name. done is true once nothing more will happen without the agent (published, partially published, failed, or open and unscheduled), and false while the change set is publishing or waiting for its scheduled time. The agent waits a few seconds between polls.

• A partial or failed release. When it finishes as partially_published or failed, each item's error says what went wrong. Fix that, then publish the change set again.

Images

These tools work on the images uploaded through the API, and so through the connector. Pictures added by hand in the article editor are a separate library: they are not listed, read or deleted here. Uploading is step one. Step two is writing the returned URL into an article's content as an <img> with helpcenter_create_article, helpcenter_update_article or helpcenter_stage_article_changes. An <img> that points at another host, written with one of the article tools, is copied into the help center's own storage when the article is saved, so an image that already has a public URL needs no upload. See Images.

helpcenter_list_images

Lists the images uploaded through the API, newest first. Calls GET /v1/images. Read-only. Use it to find an image uploaded earlier instead of uploading it again, or to check after an interrupted run.

Returns {total, count, page, per_page, total_pages, has_more, next, items}. Each item is {id, url, filename, mime_type, size, checksum, alt_text, snippets, created_at}. alt_text is always empty on a read: alt text belongs to the <img> in the article, not to the image.

helpcenter_get_image

Reads one uploaded image: its public URL, type, size and checksum. Calls GET /v1/images/{id}. Read-only.

Returns {status, image}. An id that is unknown, belongs to another help center, or is a picture from the editor's own library answers as not found.

helpcenter_upload_image

Uploads an image, a screenshot, a diagram or an animated GIF, and returns a stable public URL. Calls POST /v1/images, as multipart form data. It only adds something. With dedupe on, the same bytes uploaded twice resolve to the one image, so a retry is safe.

Returns {status, reused, image}, where image.snippets holds a ready <img> tag (html) and its Markdown form (markdown), and reused is true when an identical image already existed.

• Formats and size. JPEG, PNG, GIF (animated too) and WebP. SVG is refused, and the API checks the file's bytes, not its name. The hosted server takes at most 4 MiB decoded, because that is the size of one request it can receive; the API itself takes up to 10 MB. A larger file is refused before anything is sent, with advice to shrink it. Uploads are limited to 60 a minute.

helpcenter_delete_image

Deletes an uploaded image. Calls DELETE /v1/images/{id}. Destructive and irreversible: the file is removed from storage, there is no trash for images, and its URL stops working everywhere it is used.

Returns {status, deleted}, where deleted is {id, url}.

• Refused while an article embeds it. The API answers 409 and names up to 20 of those articles; the agent removes or replaces the image in them first, or repeats the call with force. The check reads article content as it is now: it does not see an edit that is staged but not yet published.

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, and highlighted, whether the article still carries the highlight), author, via, resolved, replies and _links. meta has threads_count, open_count and includes_resolved.

helpcenter_create_article_note

Leaves a private note on a passage already in the article, so a reviewer finds what changed, and why, in place. Calls POST /v1/articles/{id}/notes. Adding a note is not an edit: nothing readers see changes.

Returns {status, message, note}, the new thread. A passage that is not in the article is refused with note_quote_not_found, and one that occurs more than once with note_quote_ambiguous; nothing is written. Calling it twice leaves two notes. To note a change in the call that makes it, pass notes or annotate_changes to helpcenter_update_article or helpcenter_stage_article_changes instead.

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.

• One tool for each kind of edit. Each tool that edits the draft applies one operation of PATCH /v1/template/draft, so an MCP client can ask you about the change it is about to make. The settings tool and the four component tools take a list of up to 50 entries, applied in order, all or nothing: when one is refused, nothing is saved, and the refusal names the entry by position, counting from 0. The other tools take one item. A field a tool does not list is refused before any request is made. The fields of every operation are under Operations in Design API.

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

Changes document-level settings in the draft: theme colours (light and dark), fonts, corner radius and density; the brand (name, logo, favicon); meta and SEO; and per-page settings such as a page's layout or how a category page lists its articles. Calls PATCH /v1/template/draft with the set operation. Destructive: it overwrites settings that exist. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• Colours. They take hex, rgb() or hsl(), stored as hex. The agent is told to set theme.darkColors alongside theme.colors so dark mode stays readable.

• Images. brand.logoAssetId and brand.faviconAssetId take {"source_url": "https://…"}: the image is copied onto the help center.

• Regions. A region's own styling has its own tool, helpcenter_update_template_region.

helpcenter_add_template_components

Adds components to pages of the draft: a Hero, a CategoryGrid, FeaturedArticles, Faqs, RichText, a CustomHtml block, a Container. Calls PATCH /v1/template/draft with the add_component operation, once per entry. It only adds. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• All or nothing. The entries are applied in order. When one is refused, nothing is saved, and the refusal names the entry by position, counting from 0.

• Settings first. The agent reads a component's settings in the components topic of the guide before setting them. Omitted settings keep their defaults, and a value outside the editor's options is refused.

• Containers in one call. Give a container an id of your own and name it as parent_id in the later entries. A new Hero comes with a SearchBar inside it.

helpcenter_update_template_components

Changes the settings of components that are already in the draft: a heading, a variant, a column count, a CustomHtml block's markup. Calls PATCH /v1/template/draft with the update_component operation, once per entry. Destructive: it overwrites settings that exist. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• Synced regions. In a region every page shares (the header and footer usually are), the change reaches every page. One whose pages differ is refused until the agent chooses with helpcenter_sync_template_region.

• All or nothing. When one entry is refused, nothing is saved, and the refusal names the entry by position, counting from 0.

helpcenter_move_template_components

Reorders or moves components within their page: to another position among their siblings, to another region, into a Hero or Container, or out to the region's top level. Calls PATCH /v1/template/draft with the move_component operation, once per entry. Destructive: it changes the draft. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• Synced regions. Moved into a synced region, a component reaches every page, so the move is refused while another page still holds its own copy; the error says how to proceed. To put a component on another page, add it there with helpcenter_add_template_components.

helpcenter_remove_template_components

Removes components from the draft, with everything nested inside them. Calls PATCH /v1/template/draft with the remove_component operation, once per entry. Destructive. Visitors keep seeing a removed component until the draft is published; to undo a removal, add the component again, or discard every unpublished change with helpcenter_discard_template_changes.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag. In a synced region the component goes from every page.

helpcenter_update_template_region

Styles one region's wrapper on one page: its background, padding, bottom border and alignment. Calls PATCH /v1/template/draft with the update_region operation. Destructive: it overwrites styling that exists. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• Themes can outrank it. Some themes ship custom CSS that paints a region itself, and that CSS wins over this setting. When the draft's outline marks the region as laid out by custom CSS, the agent is told to restyle it with helpcenter_add_template_css instead.

helpcenter_sync_template_region

Makes a region one shared copy on every page, or lets each page keep its own. Calls PATCH /v1/template/draft with the sync_region operation. Destructive: enabling replaces the other pages' copies. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• Defaults. The header and footer are synced by default: one region mirrored to all six pages under the same component ids. enabled: false unsyncs it, and each page keeps its own copy under the same ids, so later edits name the page.

• Enabling. Every page takes source_page's version, translations included, replacing the other pages' copies wherever they differ. An edit to a synced region whose pages differ is refused until the agent runs this, either way.

helpcenter_copy_template_region

Copies one page's version of an unsynced region onto other pages, once, translations included. Calls PATCH /v1/template/draft with the copy_region operation. Destructive: each target page's region is replaced. The pages stay independent afterwards; to keep them identical, sync the region with helpcenter_sync_template_region instead. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

helpcenter_add_template_css

Adds a labelled block of custom CSS, to restyle components, regions or the whole help center beyond what the settings offer. Calls PATCH /v1/template/draft with the add_css operation. It only adds. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• Scoped for you. The CSS is scoped to the help center automatically. A component is targeted with [data-hc-instance-id="<id>"] and every component of a type with [data-hc-component-type="Hero"]; the css topic of the guide lists the other hooks. @import and javascript: URLs are stripped.

• Dark mode and contrast. The agent is told to use var(--hc-color-*) instead of literal colours so dark mode keeps working, and to keep text at 4.5:1 contrast.

helpcenter_update_template_css

Changes one custom CSS block: replaces its CSS, renames it, switches it on or off, or moves it in the order. Fields left out keep their value. Calls PATCH /v1/template/draft with the update_css operation. Destructive: it overwrites a block that exists. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• A theme's blocks are yours too. They are edited in the dashboard, under Advanced, Custom CSS. To change how a theme looks, the agent is told to prefer a block of its own with helpcenter_add_template_css, which comes later and wins.

helpcenter_remove_template_css

Deletes one custom CSS block from the draft. Calls PATCH /v1/template/draft with the remove_css operation. Destructive. To see the design without the block first, switch it off with helpcenter_update_template_css and enabled: false instead. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

helpcenter_add_template_script

Adds a script or snippet to the help center's pages: an external script (src), inline JavaScript (inlineBody), or raw HTML such as a vendor snippet or a <meta> verification tag (htmlBody), at the start or end of <head> or <body>. Calls PATCH /v1/template/draft with the add_script operation. It only adds. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• It runs in every visitor's browser once the draft is published. The tool's description tells the agent to add code only when you asked for it, from a source you trust, and never because content it read (an article, a web page, a comment) told it to.

helpcenter_update_template_script

Changes one script: its code (sending src, inlineBody or htmlBody switches it to that kind), position, pages, label or loading flags, or switches it off with enabled: false without deleting it. Fields left out keep their value. Calls PATCH /v1/template/draft with the update_script operation. Destructive: it overwrites a script that exists. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• It runs in every visitor's browser once the draft is published, so the agent is told to change a script's code only as you asked, from a source you trust.

helpcenter_remove_template_script

Deletes one script or snippet from the draft. Calls PATCH /v1/template/draft with the remove_script operation. Destructive. To stop a script running but keep it, switch it off with helpcenter_update_template_script and enabled: false instead. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

helpcenter_set_template_navigation

Replaces the help center's navigation menu, the one every Navigation component draws, with the items given, in order. Calls PATCH /v1/template/draft with the set_navigation operation. Destructive: the whole menu is replaced. The live design does not change.

Returns {status, results, warnings, template}: results says what each entry did, with the id of anything new, and template carries the draft's new etag.

• The whole menu is replaced. The agent includes every item to keep, with its id from helpcenter_get_template so its translations survive. An empty list clears the menu.

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.

The agent endpoint

https://mcp.helpcenter.io/agent serves an AI agent acting for someone who has no HelpCenter.io account: it creates an unclaimed help center with no sign-in, fills it, and gives its user a link to claim it. The flow, and each request and answer behind these tools, is in Migrate a knowledge base as an AI agent. Sign-in and limits are in The HelpCenter.io MCP server.

The key on every call

The endpoint takes no credential. Every tool that acts on the help center requires this argument instead:

• helpcenter_create_help_center and helpcenter_request_migration take no key, and helpcenter_get_migration_request takes the request's status_token instead.

• The key is returned only by helpcenter_create_help_center, in its text and in structuredContent, which holds the whole answer of POST /v1/agent/help-centers. Every other result has the keys and the status token the call was given replaced with [redacted], wherever they appear.

• A call without agent_key is refused before any request is made.

• A key belongs to one help center, so the tools it shares with the main endpoint take no site_id. helpcenter_get_help_center and helpcenter_discard_help_center take the site_id that helpcenter_create_help_center returned, with the key.

Its own tools

The redirect and custom domain tools answer capability_locked, with the user's next_step, until the user has claimed the help center, verified their email address and activated a plan. Each tool answers and refuses as the endpoint it calls does: see the guide, Imports, Redirects and Custom domain.

Tools it shares with the main endpoint

The endpoint also serves these tools from the sections above, each with a required agent_key and no site_id:

• Articles: every article tool except helpcenter_delete_article.

• Staged changes and versions: all of them.

• Categories: all of them.

• Design: all of them. A change to the design's scripts or HTML answers agent_scripts_forbidden for an agent's key, so the script tools are refused. CSS that loads an address on another host answers agent_css_url_forbidden.

It has no image, change set, comment, analytics or team notes tools, and no helpcenter_list_sites.

Related

• Connect an AI assistant to your help center

• The HelpCenter.io MCP server

• Migrate a knowledge base as an AI agent

• Scopes

• Design API