# The HelpCenter.io MCP server

_Category: AI agents and MCP_

The HelpCenter.io MCP server lets an AI agent work in your help center: search and read articles, write and publish them, upload images, release several changes together, organize categories, answer reader comments, work through your team's notes, read your statistics, change the design, and set up the widget and FAQ sections. It speaks the Model Context Protocol (MCP) at `https://mcp.helpcenter.io`, so Claude, ChatGPT and agents you build see your help center as a set of tools.

The server is a thin layer over the [HelpCenter.io REST API](https://developers.helpcenter.io/content/developer-platform). Each tool call becomes a request to `https://api.helpcenter.io/v1`, made with the agent's own credential, so the API's permissions, validation and rate limits apply to the agent as they apply to your code. The server keeps no copy of your content and no credential between requests.

Connecting takes a minute: see [Connect an AI assistant to your help center](https://developers.helpcenter.io/content/connect-an-ai-assistant-to-your-help-center). Every tool, with its arguments and results, is in the [MCP tool reference](https://developers.helpcenter.io/content/mcp-tool-reference).

An agent acting for someone who has no HelpCenter.io account uses the server's second endpoint, `https://mcp.helpcenter.io/agent`: it creates a help center with no sign-in, fills it, and gives its user a link to claim it. See "The agent endpoint" below.

## At a glance

| Item | Details |
| --- | --- |
| Server URL | `https://mcp.helpcenter.io`. Add `?site=<id>` to pin a connection to one help center. |
| Agent endpoint | `https://mcp.helpcenter.io/agent`, with no sign-in, for an agent building a help center for someone who has no account |
| Transport | Streamable HTTP, stateless. Every `POST` gets one JSON response. There is no session (`Mcp-Session-Id`) and no event stream. |
| Protocol versions | `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07` |
| What it offers | Tools only. No prompts and no resources. |
| Sign-in | OAuth 2.1 (your MCP client signs you in), or an API key sent as `Authorization: Bearer <key>` |
| Plans | Growth and Catalyst, including their free trials |
| Limits | The API's per-credential rate limits: 300 requests a minute, of which at most 120 writes, and 6 a minute for the analytics tools. A tool call that waits more than 25 seconds for the API times out. |

Your readers get a different server: every public help center also has a read-only, anonymous MCP server at its own address. See [The public MCP server of a help center](https://developers.helpcenter.io/content/public-mcp-server).

## What agents can do

| Area | The tools let an agent | Permission |
| --- | --- | --- |
| Articles | Search published articles, list and read every article (drafts included), create and update articles in HTML or Markdown, import up to 50 in one call, and move an article to the Trash. | `content.read`, `content.write` |
| Images | Upload a screenshot, a diagram or an animated GIF (up to 4 MiB on the hosted server) and get a URL to place in an article, list and read the images uploaded this way, and delete one. | `content.read`, `content.write` |
| Staged changes and versions | Save an edit to a published article without readers seeing it, publish or discard it, and list or restore earlier versions. | `content.read`, `content.write` |
| Change sets | Group staged edits, drafts and category visibility changes into a named release, check that it is ready, publish it now or at a scheduled time, follow it until it is done, and cancel its schedule. Part of the Catalyst plan, in early preview. | `content.read`, `content.write` |
| Categories | List, create, update and reorder categories, set the article order inside one, and delete one after saying where its contents go. | `content.read`, `content.write` |
| Comments | Read reader comments and the moderation queue, approve or unpublish a comment, and reply. | `content.read`, `content.write` |
| Widget and FAQ sections | Read the snippet that puts the widget on your website and the websites allowed to embed it, add or remove those websites, and create, change, fill, order and delete embeddable FAQ sections. | `content.read`, `content.write`, and `embed.manage` for the websites |
| Analytics | Read traffic and ratings, per-article performance, and what readers searched for and did not find. | `analytics.read` |
| Team notes | Read the private notes your team leaves on articles, leave notes on passages, reply to them and resolve them. | `notes.read`, `notes.write` |
| Design | Read the design and the guide to what can be changed, start from a theme, edit the draft that the template editor opens (theme, pages and components, navigation, custom CSS and scripts), publish it, discard it, and load an earlier version into it. | `design.read`, `design.write` |
| Help centers | List the help centers the connection can reach, with their ids. | `content.read` |

Articles an agent creates stay drafts unless it publishes them. Changes to a published article go live at once, unless the agent stages them first. Changes to the design go to a draft that you review in the template editor, and visitors see them only when that draft is published (see [Design API](https://developers.helpcenter.io/content/design-api)).

## What agents cannot do

- Restore an article from the Trash, or delete a comment. They can unpublish an article or a comment, which you can reverse, and move an article to the Trash, which only a person can undo.
- Manage webhooks, edit interface translations, export a help center, send article feedback or set an article's SEO title and description. Your own code can do all of these with the [REST API](https://developers.helpcenter.io/content/developer-platform).
- Change settings other than the websites allowed to embed your help center, your team or billing.
- Publish the help center itself. Articles an agent publishes reach readers once you publish the help center, in **Settings**.
- Create a help center, import a knowledge base from another platform, or manage redirects and the custom domain. For someone who has no HelpCenter.io account, an agent does all of these through the agent endpoint (below) or the REST API: see [Migrate a knowledge base as an AI agent](https://developers.helpcenter.io/content/migrate-a-knowledge-base-as-an-ai-agent). On a help center you already have, your own code imports, redirects and sets the custom domain with the REST API: see [Imports](https://developers.helpcenter.io/content/imports-api), [Redirects](https://developers.helpcenter.io/content/redirects-api) and [Custom domain](https://developers.helpcenter.io/content/custom-domain-api).
- Translate the texts in your design, or switch a help center to the template editor. The design tools set texts in the help center's default language, and both of these are done in the dashboard.
- Read reader email addresses or IP addresses. Comment tools leave out email addresses, and no tool returns an IP address.
- See team notes through the comment tools. Team notes are only reachable through the team notes tools, with their own permission.

Tools that can change or remove something that already exists, or change what readers see, are marked as destructive in their MCP annotations (`destructiveHint: true`), which MCP clients can use to ask you before running them. The [MCP tool reference](https://developers.helpcenter.io/content/mcp-tool-reference) shows the kind of every tool. These need the most care: discarding staged changes or the design draft, which can't be recovered; deleting a category, an image or a change set; moving an article to the Trash, which only a person can undo; and restoring an earlier version of an article, publishing a change set or publishing the design, which readers see at once.

## How agents sign in

The same URL takes two kinds of credential, both in the `Authorization: Bearer` header.

|  | OAuth sign-in | API key |
| --- | --- | --- |
| Use it for | Claude, ChatGPT and other MCP clients that sign you in | Agents and scripts you run yourself |
| How it works | The client sends you to HelpCenter.io to sign in. You approve the permissions it asks for and choose the help centers it may reach. | Create a key in **Settings** → **API keys** and send it as `Authorization: Bearer <key>`. The `X-HelpCenter-Api-Key` and `apikey` headers also work. |
| Acts as | You, on the help centers you chose | The person who created the key, on the key's help center |
| Can do | What the permissions you approved allow | What the key's scope allows (**Read only** or **Read & write**), plus team notes and the design if the key was created with that access |
| Stop it | Disconnect the app in **Account** → **Connected Apps** | Delete the key in **Settings** → **API keys** |

A client that connects without a credential gets `401 Unauthorized` with a `WWW-Authenticate` header that points to the server's OAuth metadata, `https://mcp.helpcenter.io/.well-known/oauth-protected-resource`. MCP clients follow it to the HelpCenter.io authorization server and start the sign-in. [OAuth 2.1 for apps and AI clients](https://developers.helpcenter.io/content/oauth) covers the flow in depth.

OAuth reaches only help centers that belong to the HelpCenter.io account you sign in with. To connect an agent to a help center another account owns, use an API key created in that help center.

## Plans

The MCP server is part of the Growth and Catalyst plans, including their free trials. HelpCenter.io checks the plan on every request, for the help center the request acts on, so a plan change applies to the very next tool call.

The check covers API keys too. The REST API itself works on every plan, but the MCP server marks its own requests to the API with the header `X-HCio-Client: mcp`, and requests carrying it are checked. So a key that works against `https://api.helpcenter.io/v1` on any plan is refused through the MCP server on a plan that does not include it.

On other plans:

- The OAuth consent screen shows those help centers locked, with an **Upgrade** link. When none of your help centers qualifies, it says **Your plan doesn't include the MCP server** and shares nothing.
- A tool call is refused by the API with `402 Payment Required`:

```
{
  "status": "error",
  "code": "plan_upgrade_required",
  "feature": "mcp",
  "message": "The HelpCenter.io MCP server is available on the Growth and Catalyst plans. Acme does not have an active plan.",
  "upgrade_url": "https://helpcenter.io/app/account/billing",
  "plans": ["growth", "catalyst"]
}
```

When the help center has a plan, the second sentence names it, for example `Acme is on the Bootstrap plan.` The agent receives the refusal as a tool error it is asked to pass on, not to act on:

```
The HelpCenter.io MCP server is available on the Growth and Catalyst plans. Acme does not have an active plan.

Upgrade the plan: https://helpcenter.io/app/account/billing

This is the help center's subscription plan, not an authentication problem. Do not retry, and do not reconnect or re-authorize the HelpCenter.io connector — neither changes the plan, so both end in this same answer. Tell the user, so that someone who manages the HelpCenter.io account can change the plan.
```

Staging an edit also needs staged changes on the help center, part of the Catalyst plan (see [Staged changes and versions](https://developers.helpcenter.io/content/staged-changes-api)). Listing and restoring versions has no extra plan requirement, but versions are only recorded when staged changes are published or a version is restored, so a help center without staged changes usually has none. The change set tools need change sets on the help center, part of the Catalyst plan in early preview (see [Change sets](https://developers.helpcenter.io/content/change-sets-api)); without them they are refused with `402 Payment Required`.

## Which help center the agent works on

Every tool except `helpcenter_list_sites` takes an optional `site_id` argument: the id of the help center that call acts on. What a connection needs depends on how it signed in:

- **API key:** always the help center the key was created in. A `?site=` on the URL is ignored, and a `site_id` that names another help center is refused before any request is made.
- **OAuth, one help center approved:** that one, with nothing to configure.
- **OAuth, several approved:** the agent names one on each call, with `site_id`. The `helpcenter_list_sites` tool lists the ids. A call that names none is refused with `site_required`, and the refusal lists the ids, so nothing is written to a help center the agent did not name.
- **OAuth, pinned:** add `?site=<id>` to the server URL, for example `https://mcp.helpcenter.io/?site=1234`, and every call acts on that help center. A pinned connection refuses a `site_id` that names a different one.

`site_id` applies to one call. The server keeps nothing between requests, so an agent passes it on every call of a task, and one conversation can work in several help centers. The server's `initialize` response carries instructions that tell the agent to list the help centers, to pass `site_id`, and to ask you when your request does not say which help center you mean. Pin the connection when an agent should stay in one help center. See [Choose which help center a request acts on](https://developers.helpcenter.io/content/choosing-a-help-center).

## Security model

- **It acts as a person.** Every request carries the credential of the person who connected the agent (or who created the key). Replies to comments are posted in their name.
- **It is limited twice.** A connection reaches only the help centers you approved and only what its permissions allow. The API enforces both on every request, including which help center an id belongs to: an id from another help center answers as not found.
- **Tokens are bound to this server.** The server accepts only OAuth access tokens that HelpCenter.io signed for `https://mcp.helpcenter.io`. A token issued for anything else is refused with `401`, however valid it is elsewhere.
- **Revoking works on the next request.** Unticking a help center in **Connected Apps** applies to the agent's next call, and **Disconnect** revokes its tokens at once. Deleting an API key stops it immediately.
- **Team notes need two things.** The `notes.read` or `notes.write` permission (or a key created with team notes access), and the person behind the credential must still have access to team notes in the dashboard. HelpCenter.io checks the second on every request.
- **The design needs two things too.** The `design.read` or `design.write` permission (or a key created with design access), and the person behind the credential must be able to edit the design in the dashboard: an Owner, Admin or Editor. HelpCenter.io checks the second on every request. `design.write` reaches custom CSS and scripts, which run in every visitor's browser once the design is published, so approve it only for agents you trust.
- **Nothing is kept.** The server stores no content. It logs one line per request (method, status, tool name, timing), never the arguments, the results or the credential.

## The agent endpoint

`https://mcp.helpcenter.io/agent` is for an AI agent acting for someone who has no HelpCenter.io account yet. The agent creates an unpublished help center, fills it by hand or with an import, checks it with a preview link, and gives its user a link to claim it. [Migrate a knowledge base as an AI agent](https://developers.helpcenter.io/content/migrate-a-knowledge-base-as-an-ai-agent) is the whole flow, and the [MCP tool reference](https://developers.helpcenter.io/content/mcp-tool-reference) lists the endpoint's tools.

- **No sign-in.** The endpoint never asks for a credential and ignores any it is sent. `helpcenter_create_help_center` creates the help center and returns its key, once. Every tool that acts on the help center takes that key as a required `agent_key` argument, and sends it to the API as that call's credential. The server keeps nothing between calls, and the key is never logged and never returned by any other tool.
- **Its tools.** Creating, reading and deleting the help center, migration requests, imports, redirects and the custom domain, plus this server's article, staged changes, category and design tools. It has none for images, change sets, deleting an article, comments, analytics or team notes, and no `helpcenter_list_sites`: a key belongs to one help center, so its content and design tools take no `site_id`.
- **The key's limits apply.** Until the user claims the help center, the key reaches only its content and design. The redirect and custom domain tools work once the user has claimed it, verified their email address and activated a plan. Only the user can make the help center public.
- **Creating counts in a shared pool.** In ChatGPT, creating counts in a pool shared by every ChatGPT agent. From any other client it counts in the endpoint's own: 60 help centers an hour and 300 open at once, across every agent that uses it. Migration requests are limited to 30 a day across every agent that uses the endpoint.

The main endpoint leaves this flow out on purpose. There, a request without a credential is answered with the sign-in challenge that starts OAuth in Claude and ChatGPT, so it can't also serve an agent that has no account to sign in with.

## Related

- [Connect an AI assistant to your help center](https://developers.helpcenter.io/content/connect-an-ai-assistant-to-your-help-center)
- [MCP tool reference](https://developers.helpcenter.io/content/mcp-tool-reference)
- [Migrate a knowledge base as an AI agent](https://developers.helpcenter.io/content/migrate-a-knowledge-base-as-an-ai-agent)
- [OAuth 2.1 for apps and AI clients](https://developers.helpcenter.io/content/oauth)
- [Design API](https://developers.helpcenter.io/content/design-api)
- [The public MCP server of a help center](https://developers.helpcenter.io/content/public-mcp-server)