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 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 walks you through it

Connecting With an API Key

Head to Settings > API and create a key, or pick an existing one
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
Point your MCP client at the HelpDocs MCP URL, and send the key as a bearer token


              https://••••••••••••••••••••••••••

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

{
            "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:

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.