DocsKoala ships an MCP (Model Context Protocol) server so an AI coding agent, Claude Code, Cursor, or anything else that speaks MCP, can read your review inbox, draft or edit help articles, and reorganize your help center directly from your editor, without you switching tabs to the dashboard.
This is a setup tutorial, not a feature overview: it walks through creating a scoped token, wiring up the connector on either client, running a first tool call to confirm the connection, and what to do when something doesn't connect. It also documents every one of the 12 tools currently exposed, since "connect your agent" is only half the picture, knowing exactly what that agent can and can't touch is the part that actually matters for a support/docs tool.
Direct answer
To connect an AI coding agent to DocsKoala over MCP: go to Settings → MCP in your dashboard, create an API token scoped to only the tools you want the agent to use (drafting-only tokens shouldn't get approve or organize scopes), then add https://yourapp.docskoala.com/api/mcp as a custom connector in your client. Claude Code's "Add custom connector" flow handles authentication via OAuth automatically once you paste the URL, no token paste needed. Clients that don't support MCP's OAuth discovery, like Cursor, need the token pasted manually as an Authorization: Bearer <token> header in their MCP config file. Either way, nothing the agent drafts, edits, or reorganizes publishes to your live help center automatically, every change lands in the Review Inbox for a human to approve first.
What you need before you start
- An owner or admin role on your DocsKoala org. Only those roles can create or manage API tokens from Settings → MCP.
- A client that supports MCP. Claude Code and Claude.ai (via custom connectors), Cursor, and any other MCP-compatible client work the same way once you have the server URL and, where needed, a token.
- A decision about scope, not a prerequisite exactly, but worth deciding before you create the token: should this agent be able to publish, or only draft? See the tool reference below before picking scopes.
Step 1: Create a scoped API token
- In your DocsKoala dashboard, go to Settings → MCP.
- Click Create API token (in the Tokens tab). Give it a name that identifies where it's used,
Claude CodeorCursor - laptopreads better in an audit log six months from now thantoken1. - Select scopes individually. Every scope maps to specific tools; a token given only
drafts:createcan callcreate_draftand nothing else, it can't approve, dismiss, or reorganize anything even if the underlying client tries. - Pick an expiry. The default is 90 days, not "Never", since this token can end up in an AI agent's config file, which has a larger leak surface than a typical API key (committed to a repo by accident, pasted into a support thread, logged by the client). "Never" is available if you deliberately want it.
- Copy the plaintext token shown after creation. It is only ever displayed once; if you lose it, revoke it and create a new one rather than trying to recover it.
| Scope | Grants access to |
|---|---|
review:list | list_review_inbox — see pending drafts |
drafts:create | create_draft — propose a new article or an update to an existing one |
drafts:edit | edit_draft — edit a still-pending draft before review |
review:approve | approve_draft — publish a pending draft (the one write-through-to-live scope) |
review:dismiss | dismiss_draft — reject a pending draft |
categories:move_article | move_article_category — assign/clear a published article's category |
categories:reorder | reorder_categories — set category sort order |
articles:move_project | move_article_project — move a published article between projects |
articles:read | list_articles — list published articles |
escalations:read | list_escalations, get_escalation — read support inbox conversations |
escalations:reply | reply_escalation — send a reply on a support conversation |
Step 2a: Add the connector in Claude Code or Claude.ai
- Copy your org's MCP server URL:
https://<your-subdomain>.docskoala.com/api/mcp(or your custom domain, if you have one connected). - In Claude.ai, go to Settings → Connectors → Add custom connector. In Claude Code, the equivalent lives in your client's MCP/connector settings.
- Paste the server URL. Claude discovers the OAuth endpoints automatically (DocsKoala's server publishes standard
.well-known/oauth-protected-resourceand.well-known/oauth-authorization-servermetadata) and registers itself as a client. - You'll be redirected to a consent screen on your own DocsKoala domain (an OAuth 2.1 authorization-code flow with PKCE). Log in if prompted, review what's being requested, and approve.
- Claude now holds its own OAuth-issued credential, there's no API token to paste or manage for this path specifically.
If you're inside the DocsKoala dashboard already, the Connect to Claude button on the MCP page copies the correct server URL and opens Claude's connector settings in one step, so there's no risk of a typo in the path.
Step 2b: Add the connector in Cursor (or any client without OAuth discovery)
Cursor and most other MCP clients don't yet do the OAuth-discovery dance Claude does, so you connect with the API token you created in Step 1 instead, passed as a bearer credential in the client's MCP config.
- Open your MCP client's server config (in Cursor, this is the
mcpServerssection of its MCP settings). - Add an entry pointing at your server URL, with the token set as an
Authorizationheader in the formBearer <your-token>. - Restart or reload the client's MCP connection so it picks up the new server.
- The client should now list the tools your token's scopes allow, if it doesn't, see troubleshooting below.
Step 3: Verify the connection works
- Ask your agent to "list the review inbox" or call
list_review_inboxdirectly. If your token hasreview:list, this should return pending drafts (or an empty list, if there aren't any) rather than an error. - Try something the token's scopes don't cover, if you only granted
drafts:create, ask it to approve a draft. You should get back a clearFORBIDDENerror naming the missing scope, not a silent failure or a published article. - Check Settings → MCP → Activity in your dashboard. Every tool call that writes anything (a created draft, an approval, a category move) shows up here with which token did it and when.
A typical workflow once it's connected
- You (or the automated PR pipeline) merge a change that affects customer-facing behavior.
- From your editor, you ask the connected agent to check the review inbox and see if a draft already exists for that change.
- If there's a rough draft, you ask the agent to tighten a section or fix a stale screenshot reference, it calls
edit_draftdirectly from your terminal. - You still open the Review Inbox in the dashboard (or ask the agent to summarize the diff) before approving.
approve_draftis the one call in the whole tool set that actually publishes something, so it's worth treating deliberately even when it's convenient to trigger from chat. - Once approved, the article is live and re-indexed, the agent's job for that change is done.
Why nothing publishes on its own
Every write-capable tool (create_draft, edit_draft, move_article_category, reorder_categories, move_article_project) either creates a pending draft or modifies something already published in a structural way, none of them push new customer-facing article content live. Only approve_draft does that, and it requires the review:approve scope specifically. A token built for drafting doesn't have it, so an agent with that token literally cannot publish, regardless of what it's asked to do.
Full tool reference
| Tool | What it does | Publishes immediately? |
|---|---|---|
list_review_inbox | List pending drafts, optionally filtered by project | No, read-only |
create_draft | Create a new draft article, or propose an update to an existing one | No, lands in review |
edit_draft | Edit a still-pending draft's title or content | No, lands in review |
approve_draft | Publish a pending draft as a new article or version | Yes |
dismiss_draft | Reject a pending draft without publishing it | No |
move_article_category | Assign or clear a published article's category | Changes structure, not content |
reorder_categories | Set a project's category sort order | Changes structure, not content |
move_article_project | Move a published article to a different project in the same org | Changes structure, not content |
list_articles | List published help articles, optionally by project | No, read-only |
list_escalations | List support inbox conversations, optionally by project | No, read-only |
get_escalation | Get one support conversation's full message thread | No, read-only |
reply_escalation | Send a reply on a support conversation over its real channel (Slack, email, Telegram, API, or widget) | Yes, sends a real message |
Troubleshooting common connection errors
| What you see | Likely cause | Fix |
|---|---|---|
| "Missing or malformed Authorization header. Expected: Bearer <token>." | The client isn't sending the header at all, or sent it in the wrong format | For manual-token clients (Cursor, etc.), confirm the header is exactly Authorization: Bearer <token> with no extra quoting or a stray newline |
A FORBIDDEN error naming a specific scope | The token doesn't have the scope that tool call needs | This is working as intended, not a bug. Create a new token (or ask an org owner/admin to) with the scope added if the agent genuinely needs it |
| Claude's connector setup fails during the consent step | The redirect URL Claude registered doesn't match, or the login session expired mid-flow | Remove the connector in Claude and re-add it from scratch rather than retrying the same stuck flow |
| Tool calls succeed but nothing shows up in Activity | You're looking at a different org than the token belongs to | Confirm which org is active in the dashboard, tokens and their activity are per-org, not global to your account |
Frequently asked questions
Can an MCP-connected agent publish articles without human review?
No. Every drafting and editing tool lands its output in the Review Inbox as pending. Only approve_draft publishes, and it requires the review:approve scope, which you choose whether to grant when creating the token. A drafting-only token cannot publish under any circumstances.
What's the difference between connecting via OAuth and using an API token?
They reach the same server and tools, just with different setup. Claude's custom connector flow uses OAuth: paste the server URL and Claude handles discovery, registration, and consent automatically, no token to copy or store. Clients without that OAuth-discovery support, like Cursor, connect with a manually created API token pasted into the client's own config as a bearer credential.
Can I limit an MCP token to only drafting, not approving or organizing?
Yes. Scopes are granted individually per token: give it review:list, drafts:create, and drafts:edit for a drafting-only setup, and leave off review:approve, review:dismiss, and the category/project-move scopes entirely.
How do I revoke access if I stop using an agent, or a token leaks?
From Settings → MCP → Tokens, revoke the token directly, it stops working on the next request. There's no dependency on the AI client itself to disconnect cleanly on its end.
Can one token see support tickets across every project in my org?
Only if it has the escalations:read scope, and even then it's scoped to your org, never another organization's data. You can also filter list_escalations by project when calling it, but the scope grant itself is org-wide, not per-project.
Does connecting MCP give the agent access to my GitHub repo too?
No, those are two separate integrations. MCP access covers your DocsKoala help center content and review inbox. Repo access (for the PR-to-docs pipeline) is a separate GitHub App installation with its own scoped, read-only permissions. See is it safe to give an AI tool repo access for that side of it.
Conclusion
- Setup is three real steps: create a scoped token (or let Claude's connector handle OAuth automatically), point the client at your server's
/api/mcpURL, and verify with a read-only call before trusting it with anything else. - Scope the token narrowly. A drafting-only token literally cannot publish, dismiss, or reorganize, regardless of what the agent is asked to do.
- Every write lands in the Review Inbox except
approve_draft, and every tool call is logged per-token in Settings → MCP → Activity. - 12 tools cover drafting, review, article organization, published-article listing, and the support inbox, see the full tool reference above before deciding what to grant.