---
title: "Using an API Key with HelpDocs MCP"
url: "https://support.helpdocs.io/article/3jo521wzda-using-an-api-key-with-help-docs-mcp"
category: "MCP"
updated_at: "2026-08-27T13:52:37Z"
---

# Using an API Key with HelpDocs MCP

The Claude and ChatGPT connectors authorize HelpDocs MCP through a browser sign-in flow. That works beautifully when there's a person and a browser involved—but not so well in CI pipelines, self-hosted agents, or scripts running on a server somewhere at 3am.

For those, you can authenticate the MCP server with an API key you already have.

API key auth sits alongside OAuth rather than replacing it. If your client supports the browser flow, that's still the easiest way to connect. See our [overview of HelpDocs MCP](/article/8wdmcyn6tg-connecting-to-helpdocs-mcp) to get started there.

### Before You Start

Three things need to be in place:

- **MCP Access is enabled.** Head to **Settings** > **AI**, make sure **Enable AI Tools** is checked, then select **MCP Access** in the **Choose features** dropdown
- **Your plan includes API access.** Write tools also need write API access on your plan
- **You have an API key.** If you don't yet, our guide on [creating and managing API keys](/article/e2gilg5mkd-creating-and-managing-api-keys) walks you through it

### Connecting With an API Key

1. Head to **Settings** > **API** and create a key, or pick an existing one
2. Click **More** > **Edit** and set the permission scope. Read-only is plenty for search and research; choose Read and Write if you want your assistant to create and edit content
3. Point your MCP client at the HelpDocs MCP URL, and send the key as a bearer token

`https://••••••••••••••••••••••••••` Click to reveal URL Copy

Most clients let you attach custom headers to an HTTP MCP server. Here's what that looks like in a typical config file:

```json
{
  "servers": {
    "helpdocs": {
      "type": "http",
      "url": "YOUR_HELPDOCS_MCP_URL",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Swap `YOUR_HELPDOCS_MCP_URL` for the URL above and `YOUR_API_KEY` for your key. The exact shape of the config varies between clients—some use `servers`, some use `mcpServers`—but the URL and the `Authorization` header are the two things that matter.

You don't need to tell the client which HelpDocs account to connect to. Each key belongs to exactly one account, so we work it out from the key itself.

### Checking It Works

Before wiring up a client, you can ask the server what tools it's offering:

```bash
curl -s YOUR_HELPDOCS_MCP_URL \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A JSON response listing tools like `search` and `list_articles` means you're connected ✅

### What Your Key Can Do

The tools your assistant sees depend on the permission scope you gave the key:

| Key permission | Tools available                                                                                                           |
|----------------|---------------------------------------------------------------------------------------------------------------------------|
| Read-only      | Search articles, list and read articles, list and read categories, pull analytics, and use the built-in authoring prompts |
| Read and Write | Everything above, plus creating, updating, and deleting articles and categories                                           |

A key can never do more through MCP than the person who created it can do in the app. Every tool checks the key owner's role, so a key made by a teammate who can't publish won't be able to publish over MCP either.

**Keys follow their owner.** If the teammate who created a key leaves your account, their key stops working with MCP straight away. Worth creating keys under an account that's going to stick around if the integration is something your team depends on.

### API Key or OAuth?

| Use OAuth when                                                                 | Use an API key when                                                       |
|--------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| You're connecting Claude, ChatGPT, or another client with a built-in connector | Your client runs headless—CI jobs, scheduled scripts, self-hosted agents  |
| A person is signing in and there's a browser to redirect to                    | There's nobody around to click Authorize                                  |
| You want each teammate connecting under their own login                        | You want one long-lived credential you can rotate or revoke from Settings |

### Keeping Your Key Safe

An MCP key is a real API key with real access to your content. The usual rules apply:

- Keep it server-side. Never put it in frontend code, a public repo, or anywhere a browser can see it
- Give it the narrowest scope that does the job. If your agent only reads docs, make it read-only
- Use a separate key per integration so you can revoke one without breaking the others
- Name keys after what they do, like "Docs CI Agent", so you know what you're revoking later

### Troubleshooting

My assistant connects but sees no tools

The key authenticated but came back with nothing it's allowed to do. Check that MCP Access is enabled under **Settings** > **AI**, and that your plan includes API access. If you see *"No scopes granted for this request"*, the key has neither read nor write permission your plan supports.

"This API key isn't linked to a user"

Keys created before we started attributing keys to the person who made them have no owner attached, and MCP needs one to check permissions and credit authorship. Head to **Settings** > **API**, create a fresh key, and use that instead.

"The user this API key belongs to is no longer a member of this account"

The teammate who created the key has been removed from the account. Create a new key under a current member and swap it in.

"Not authorized: incorrect key"

The key doesn't match anything on your account. It's usually a stray space or a missing character from a copy-paste, or a key that's since been deleted. Check it against **Settings** > **API**.

Read tools work but write tools are missing

Three things can cause this. The key might be read-only—check its permission scope. Your plan might not include write API access. Or the user who owns the key might not have permission to manage content in your account.

"MCP rate limit exceeded"

You've hit the cap on MCP requests. Slow the client down and it'll recover on its own—the `Retry-After` header tells you how long to wait.