# Connect an AI assistant to your help center

_Category: AI agents and MCP_

Connect Claude, ChatGPT or an agent you build to your help center through the HelpCenter.io MCP server. This guide covers each client, what you approve when you sign in, how to work with several help centers, and how to take access back.

## Before you start

- **Plan:** the help center must be on the Growth or Catalyst plan, or a free trial of one. On other plans, the **AI agents** card in Settings says **Not included in your current plan**. See [plans and pricing](https://helpcenter.io/pricing).
- **Server URL:** everyone connects to `https://mcp.helpcenter.io`. In your dashboard it is in **Settings** → **AI agents**, under **Connector URL**, with a **Copy** button.
- **Signing in:** with Claude and ChatGPT you sign in with your HelpCenter.io account, and there is no key to copy. You can connect the help centers that belong to your account.
- **Your own agent:** needs an API key from the help center it should work on. See [Create an API key](https://self.helpcenter.io/content/create-an-api-key).

![Screen recording. Under AI agents, copy the Connector URL. In Claude, add it as a custom connector, then sign in and pick this help center. Using Claude Code? Copy the one-line command instead.](https://helpcenter-io.s3.amazonaws.com/uploads/self/Z8exECXCTfhduL71hB6aee10Trhq2z0X8mBG4fan.gif)
The AI agents card in Settings has the connector URL and the Claude Code command.

## Connect Claude on the web or Claude Desktop

1. In Claude, open **Settings** → **Connectors** and choose **Add custom connector**.
2. Paste `https://mcp.helpcenter.io` as the URL and add the connector.
3. Claude opens the HelpCenter.io sign-in. Sign in, check the permissions on the **Authorize access** screen, tick your help centers if you have more than one, and click **Allow**.
4. Ask Claude something that needs your help center, for example "Which of our articles explain refunds, and what do they leave out?"

## Connect Claude Code

Run this command. The **AI agents** card shows it too, under **Claude Code**, with a **Copy** button.

```
claude mcp add --transport http helpcenter https://mcp.helpcenter.io
```

You sign in to HelpCenter.io the same way as in Claude, on the same **Authorize access** screen.

## Connect ChatGPT

ChatGPT connects through its developer mode, in ChatGPT on the web, and signs in with OAuth. It cannot send an API key.

1. Turn on developer mode in ChatGPT's settings. On a workspace, an admin turns it on first.
2. Create a developer-mode app with `https://mcp.helpcenter.io` as its MCP server URL, and choose OAuth for authentication.
3. ChatGPT opens the HelpCenter.io sign-in. Sign in, check the permissions, tick your help centers and click **Allow**.
4. Start a new chat that uses the app, and ask your question.

OpenAI decides which ChatGPT plans can add an app this way and whether it may change content. Its [guide to developer mode](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt) has the current rules.

## Connect another MCP client

A client that supports remote MCP servers over Streamable HTTP with OAuth sign-in can use the same URL, provided it follows the MCP authorization flow as HelpCenter.io implements it:

- **Discovery.** A request without a credential gets `401 Unauthorized` and a `WWW-Authenticate` header naming `https://mcp.helpcenter.io/.well-known/oauth-protected-resource`. That document names the authorization server, `https://helpcenter.io`, whose metadata is at `https://helpcenter.io/.well-known/oauth-authorization-server`.
- **Registration.** Dynamic client registration at `https://helpcenter.io/oauth/register`. Redirect URIs must be `https`, or `http` on a loopback address (`localhost`, `127.0.0.1`, `[::1]`). Any other scheme is refused with `invalid_redirect_uri`.
- **Authorization code with PKCE**, method `S256`.
- **The `resource` parameter**, set to `https://mcp.helpcenter.io`. Without it, the token is not issued for the MCP server, which refuses it with `401`.
- **Scopes.** The challenge suggests `content.read content.write design.read design.write`. Ask for `analytics.read`, `notes.read` and `notes.write` as well if the agent should use the analytics and team notes tools.

The endpoints, token lifetimes and errors are in [OAuth 2.1 for apps and AI clients](https://developers.helpcenter.io/content/oauth).

## Connect your own agent with an API key

An agent you run yourself skips the sign-in and sends an API key with every request. The key decides everything: it works on the help center it was created in, with its scope (**Read only** or **Read & write**), and reaches team notes or the design only if it was created with that access.

1. Create a key in **Settings** → **API keys** of the help center the agent should work on. See [Create an API key](https://self.helpcenter.io/content/create-an-api-key).
2. Store it on the server where the agent runs, for example as `HELPCENTER_API_KEY`. Never put it in browser code.
3. Send it as `Authorization: Bearer <key>`, with `Content-Type: application/json` and an `Accept` header that lists both `application/json` and `text/event-stream`. The `X-HelpCenter-Api-Key` and `apikey` headers also carry a key.

This request calls one tool:

```
curl -s https://mcp.helpcenter.io/ \
  -H "Authorization: Bearer $HELPCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"helpcenter_list_sites","arguments":{}}}'
```

The result has the text the model reads in `content`, and the API's response in `structuredContent`:

```
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Help centers (1)\n\n- Acme (id: 381) | help.example.com\n\nThis connection reaches one help center, so no site_id is needed."
      }
    ],
    "structuredContent": {
      "status": "success",
      "sites": [
        {
          "id": 381,
          "uuid": "3f9a8112-8fb7-414f-829a-bde2136e0249",
          "name": "Acme",
          "subdomain": "acme",
          "domain": "help.example.com",
          "url": "https://help.example.com",
          "default_language": "en",
          "visibility": "public",
          "publicly_accessible": true,
          "languages": ["en"],
          "created_at": "2026-09-30 08:03:14"
        }
      ],
      "meta": { "items_count": 1 }
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}
```

Things to know when you write your own client:

- Each `POST` stands alone. The server keeps no session, so you can call `tools/call` without `initialize` first. MCP client libraries send `initialize` anyway, which works too.
- A missing `text/event-stream` in `Accept` gets `406 Not Acceptable`, and a body without `Content-Type: application/json` gets `415 Unsupported Media Type`.
- A failed tool call still answers `200 OK`. Look for `"isError": true` in the result; its text says what went wrong and what to do.
- A wrong key is not refused when you connect: `initialize` and `tools/list` answer with any key. The first tool call fails with `Error: Authentication failed. The HelpCenter.io API key is missing or invalid.`
- The plan applies to keys too. A key that works against the REST API gets the plan refusal through the MCP server when its help center is not on Growth or Catalyst.

## What you approve on the consent screen

When an app signs in, HelpCenter.io shows **Authorize access**: the app's name, then **Permissions**, the list of permissions the app asks for. You approve them together or click **Deny**: you cannot drop one permission and keep the rest. What you choose is the help centers.

- **One help center:** the screen names it under **Help center**.
- **Several:** tick them under **Help centers to share**. **Select all** ticks every one you can share. Nothing is ticked the first time, and when you approve an app again, the help centers it already reaches are ticked.
- **Help centers on other plans** are shown locked, with their plan and an **Upgrade** link. When none of your help centers is on Growth or Catalyst, the screen says **Your plan doesn't include the MCP server** instead, and nothing is shared.

These are the permissions an app can ask for, with the words the screen uses:

| Permission | On the screen | What the agent can do with it |
| --- | --- | --- |
| `content.read` | Read your help-center categories and articles. | Search and read articles, categories, reader comments, staged changes and versions, and list your help centers. |
| `content.write` | Create and update your help-center articles. | Create and change articles and categories, delete categories, stage, publish and discard changes, restore versions, and approve, unpublish and answer comments. |
| `analytics.read` | Read your help-center analytics reports. | Use the three analytics tools. |
| `notes.read` | Read the private notes your team leaves on drafts. Readers never see these. | Read team notes. |
| `notes.write` | Reply to and resolve the private notes your team leaves on drafts. | Reply to and resolve team notes. |
| `design.read` | See your help center's design: its theme, page layouts, components, custom CSS and scripts. | Read the design draft, the guide to what can be changed, the themes and the published versions of the design. |
| `design.write` | `Change your help center's design — theme, layouts, components, custom CSS and scripts — and publish it.` | Apply a theme, edit, discard and publish the design draft, and load an earlier version into it. That includes custom CSS and scripts, which run in every visitor's browser once the design is published. |
| `webhooks.manage` | Register webhooks that notify it when your content changes. | Nothing through the MCP server: no tool uses it. |
| `offline_access` | Stay connected, so you are not asked to sign in again each time its short-lived access expires. | Nothing more. HelpCenter.io gives every app a refresh token, with or without this permission. |

Apps may also ask for `openid`, `profile` and `email`, which let them confirm who you are and read your name and email address.

If you already approved the same permissions for the same app, HelpCenter.io skips the screen and connects at once. The footer of the screen reminds you that you can change or revoke access in **Account** › **Connected Apps**.

## Work with more than one help center

If you approve one help center, the agent works there. If you approve several, the agent chooses one on each tool call:

1. Tell the agent which help center you mean, by its name or its address.
2. The agent lists your help centers with the `helpcenter_list_sites` tool, which shows each one with its id.
3. It passes that id as `site_id` on each call. One conversation can work in several help centers.

When your request does not say which help center you mean, the agent is told to ask you instead of choosing. A call that names no help center is refused with `site_required`, so nothing is written to a help center the agent did not name.

To keep an agent in one help center, add the connector with the id at the end of the URL, for example `https://mcp.helpcenter.io/?site=1234`. That connection acts on that help center on every call and refuses any other `site_id`. API keys ignore `?site=`, because a key belongs to one help center.

## Add a permission later

The `401` challenge that starts every sign-in names `content.read`, `content.write`, `design.read` and `design.write`. A client that asks for exactly those gets a connection without the analytics and team notes permissions, and those tools are then refused before they run: the server answers `403 Forbidden` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="analytics.read"` (or the permission the tool needs), and the agent reads:

```
This tool needs the 'analytics.read' permission and the current authorization does not include it. Re-authorize the HelpCenter.io connector and approve that permission — retrying without it will fail identically.
```

To fix it, authorize the connector again so that the client asks for the missing permission, then click **Allow**. HelpCenter.io adds it to what it remembers for the app. If you build the client, include the permission in the `scope` of the authorization request.

## Manage or revoke access

1. Click **Manage connected apps** in the **AI agents** card, or open `https://helpcenter.io/app/account/connected-apps`.
2. To change what an app reaches, tick or untick help centers under **Help centers it can reach** and click **Save help centers**. The change applies to the app's next request. To leave it none, disconnect it instead.
3. To remove an app, click **Disconnect** and confirm. Its tokens stop working at once, and the agent is told to reconnect.

Each app shows the permissions you approved, which you cannot change on this page. The account owner sees and manages every member's connections, and each member sees their own. For an agent that uses an API key, delete the key in **Settings** → **API keys**.

## Troubleshooting

**The client reports 401 Unauthorized with "Missing HelpCenter.io credentials".** That is the challenge that starts the sign-in. A client that supports OAuth for remote MCP servers continues to the HelpCenter.io sign-in. An agent of your own must send an API key.

**"Error: Authentication failed. The HelpCenter.io API key is missing or invalid."** The key is wrong or was deleted. The message's advice to set `HELPCENTER_IO_API_KEY` does not apply to `https://mcp.helpcenter.io`: check the key you send in the `Authorization` header.

**"Error: HelpCenter.io no longer accepts this OAuth authorization".** The app was disconnected or its token expired. Reconnect it to sign in again.

**"The HelpCenter.io MCP server is available on the Growth and Catalyst plans."** The help center's plan does not include the MCP server, for example after a plan change. Reconnecting does not help. It works again on the next request once the help center is on Growth or Catalyst.

**The sign-in says "Your plan doesn't include the MCP server".** None of your help centers is on Growth or Catalyst. Move one to either plan, then connect again.

**A help center you work on is not listed on the consent screen.** It belongs to another HelpCenter.io account. Ask its owner to connect it, or use an API key created in that help center.

**"Error: This connection reaches more than one help center and this call did not say which".** You approved several help centers and the agent called a tool without `site_id`. Tell the agent which help center you mean. The message lists the ids, and the agent repeats the call with one of them.

**"Error: This authorization does not cover help center 1234."** The `site_id` is not one of the help centers you approved. Ask the agent to list your help centers, or approve the app again with that help center ticked.

**"Error: This connection is pinned to help center 1234".** The connector URL carries `?site=1234` and the agent named another help center. Nothing was sent. Remove `?site=` from the URL to let the agent choose on each call, or add a second connector for the other help center.

**"Error: This authorization does not cover the help center the connection URL selects with '?site='."** The id in the connector URL is not one of the help centers you approved. Fix or remove it, or approve the app again with that help center ticked.

**"Error: This connection uses an API key, and a key is issued for exactly one help center".** The agent passed a `site_id` that is not the key's help center. Nothing was sent. Leave `site_id` out, or use a key created in the other help center.

**"This tool needs the 'analytics.read' permission" (or `notes.read`, `notes.write`, `content.write`, `design.read`, `design.write`).** See Add a permission later, above.

**"Error: Permission denied. This action requires the notes.read scope."** With an API key, the key was created without team notes access. Create a key with **Allow access to editorial notes** turned on. The advice in the message about a write-scoped key does not apply to notes.

**"Editorial notes are visible only to team members who can access team comments in the dashboard."** The person behind the connection no longer has access to team notes on that help center. Someone with that access has to connect instead.

**"Error: This API key was not issued with access to the help center's design."** The key was created without design access, or it is a **Read only** key and the tool changes the design. Create a key with **Allow access to the help center design** ticked, and with the **Read & write** scope if the agent should change the design. An existing key can't gain design access.

**"Error: The person this connection signs in as can no longer edit this help center's design."** The person who connected the agent, or who created the key, is not an Owner, Admin or Editor of that help center. Someone who can edit the design has to connect instead, or create the key.

**A design tool answers that the help center has to switch to the template editor first.** The design tools work only with help centers designed in the template editor. The answer carries the link to the template editor, where the owner reviews the current design as a draft and publishes it to switch. See [Design API](https://developers.helpcenter.io/content/design-api).

**"Error: Permission denied. This action requires the content.write scope."** The key is **Read only**. Use a **Read & write** key.

**"Send at most 50 articles per batch; split a larger import into several batches".** The agent put more than 50 articles in one bulk import. Nothing was sent. It can send the same articles again in batches of 50 or fewer.

**"Staged changes are not included in this help center's plan."** Staging an edit needs the Catalyst plan. See [Edit live articles safely with staged changes](https://self.helpcenter.io/content/staged-changes).

**New tools do not show up.** The server answers each request on its own and cannot notify a client that its tools changed, so the client sees new tools only when it lists them again. The same goes for an argument a tool gained, such as `site_id`: a client that still holds the earlier list may send it as text and get `Expected number, received string`. Reconnect the connector, or start a new session in your client.

**Your client gets 406 or 415.** Send `Accept: application/json, text/event-stream` and `Content-Type: application/json`.

## Related

- [The HelpCenter.io MCP server](https://developers.helpcenter.io/content/the-mcp-connector-for-ai-agents)
- [MCP tool reference](https://developers.helpcenter.io/content/mcp-tool-reference)
- [OAuth 2.1 for apps and AI clients](https://developers.helpcenter.io/content/oauth)
- [Choose which help center a request acts on](https://developers.helpcenter.io/content/choosing-a-help-center)