---
title: "API tokens and MCP"
url: "/help/buuk/api-tokens-and-mcp"
updated: "2026-11-13T18:45:42.138Z"
---
# API tokens and MCP

Open **Settings → Developers** and use the **API tokens** tab. Tokens let scripts and AI tools use this help center without signing in, and every token is scoped to one workspace.

![Settings → Developers, API tokens tab: create a token and copy the CLI or MCP setup.](/api/media/assets/270d7d7b-4a6b-4e27-a93c-27c9fbdbfaed)

## Create a token

Press **Create token**. Name it after the job that will use it — “GitHub Actions” or “Cursor” — then pick the access level:

- **Can write **suggests and updates articles from the CLI or CI. It matches an editor role.
- **Read only **fetches docs, analytics, and freshness data, and cannot publish.

The full value starts with `buuk_cli_` and is shown exactly once — store it as `BUUK_API_TOKEN` in your secret store. The token list shows each token’s prefix, its role, when it was last used (or Never used), and a Revoke button; revoking cuts off anything using it immediately.

## Call the public API

Authenticate every request with a bearer header. The list endpoint supports filters and pagination:

```bash
curl "https://app.getbuuk.com/api/public/articles?status=published&kind=guide&limit=50" \
  -H "Authorization: Bearer buuk_cli_…"
```

Alongside listing and fetching articles, the read surface includes each article’s `revisions` (version number, kind, and timestamp for every snapshot — useful for audits), its published `translations` per locale, an `analytics summary`, `Ask AI conversation history` with per-conversation message counts, and reader `feedback`. Creating articles from markdown is a write call and needs a Can write token.

See the Guides and API reference tabs on this help center for authentication, pagination, and operations. Writes answer at up to 60 requests a minute and reads at 240 per workspace, so batch your loops.

## MCP

The same token initializes Model Context Protocol at `/api/mcp` — the server answers JSON-RPC `initialize` and `tools/list`, so an authoring agent can search and read your docs directly from its environment.

For external tools, you can enable a public reader MCP at `/api/public/mcp/<workspace-slug>` from Settings → General. It needs no token, only that the help center is public, and exposes published public content exclusively — private sections and hidden pages are excluded, mirroring what a crawler could reach on your public site. MCP access beyond your own workspace is a Growth capability.

## Worked example

A nightly CI job keeps docs honest: it exports `BUUK_API_TOKEN` and `BUUK_WORKSPACE`, runs `buuk suggest` against each release note, and files the gaps as suggestions. A docs teammate then opens Suggestions, accepts what is accurate, and publishes. The token has Can write access but no dashboard password anywhere.

> [!WARNING]
> Never put a live token in client-side code or a public repo. Read-only is enough for most jobs; revoke from the same tab the moment a token leaks.

## Troubleshooting

**Requests return 401**

Send the header exactly as `Authorization: Bearer buuk_cli_…`, with the full secret. A revoked or mistyped token, or one from a different workspace, also answers 401.

**A write call returns 403**

Read-only tokens can fetch docs, analytics, and freshness, but cannot create or update articles. Create a Can write token for the job that needs to change content.

**The MCP server is empty or silent**

Confirm the token works against the REST API first. For the public MCP, check that the help-center visibility is public and the MCP toggle is on in Settings → General.

## Related

- Push on change instead of polling: [Webhooks](./webhooks).
- What the drafts it creates become: [Suggested updates](./suggested-updates).
- Freshness data you can read with a token: [Doc health and freshness](./doc-health-and-freshness).
- Where SSO and seats are handled separately: [Members, roles, and groups](./members-roles-and-groups).