# Connect to ChengHub over MCP

> Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-13 ｜ Source: `chenghub/src/mcp`, `chenghub/src/mcp/tools`, `chenghub/src/services/doc_service.rs`, `chenghub/web/src/features/account/McpConfigPanel.tsx`, `chenghub/config/default.toml`

ChengHub speaks the Model Context Protocol. Point any MCP-capable client at it — Claude Code, Cursor,
Windsurf, or anything else that speaks Streamable HTTP — and the manual you are reading right now, plus
the whole community board, becomes available inside that client. You can look up a node's inputs
without opening a browser, search whether someone already hit your error, and post the question
yourself when nobody has.

It takes three things: an access token, three lines of config, and one call to check it worked.

## What you get

The endpoint is one URL, `https://chenghub.org/mcp`, and it exposes the same data as the website
through the same rules. It is a transport, not a second application: visibility, validation, and rate
limits are identical to the web UI, and the endpoint grants nothing your account does not already have
— no moderation, no administration, no deletion, no account or token management.

Concretely, a connected client can:

- **Read the documentation** — browse the table of contents and pull any article in full, in English or
  Chinese.
- **Search the community** — list, search, and read posts and their comment threads.
- **Take part** — publish a post, comment, support a request, like or star, and report abuse.
- **Move workflows** — read a shared workflow's sanitized document, or publish one of your own.

## Step 1 — Create an access token

Sign in to ChengHub in a browser, open your account page, and find the MCP section. Choose a validity
period, create the token, and copy it. Two things about that moment matter:

- **The token is shown once.** The server never displays it again. Copy it before you close the dialog.
- **Creating a token needs a browser session.** It cannot be minted with another token, by design.

Tokens last 90 days by default; 7, 30, 180, and 365 days are also offered. You can revoke one at any
time from the same page, and revocation takes effect on the connected client's very next request —
authentication is re-checked on every call, not once when the session opens.

**Choose the "Full access" scope.** The other option, "Documentation only", does not mean "may read the
manual" — it is a maintenance credential for documentation administrators, and it is refused
everywhere else on the endpoint. Reading the documentation works perfectly well with an ordinary
full-access token. If every call comes back refused, this is almost always why.

## Step 2 — Add the server to your client

Every client needs the same three values: the URL, the `Authorization` header, and HTTP transport. Only
the key names differ.

Claude Code, in `.mcp.json` at the root of your project:

```json
{
  "mcpServers": {
    "chenghub": {
      "type": "http",
      "url": "https://chenghub.org/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}
```

Cursor, in `~/.cursor/mcp.json` — no `type` field for remote servers, and it can read the token from
the environment instead of holding it in the file:

```json
{
  "mcpServers": {
    "chenghub": {
      "url": "https://chenghub.org/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CHENGHUB_TOKEN}"
      }
    }
  }
}
```

Windsurf, which names the field `serverUrl`:

```json
{
  "mcpServers": {
    "chenghub": {
      "serverUrl": "https://chenghub.org/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}
```

Any other client works too, as long as it can send a bearer header to a Streamable HTTP endpoint. The
endpoint is stateless by default, so there is no session to keep alive and nothing to reconnect.

## Step 3 — Verify the connection

Ask the client to call the `me` tool. It returns the ChengHub identity that owns the token in use. If
you get your own account back, everything downstream will work.

A failure here is almost always the header. An expired, revoked, or malformed token is refused before
the request is even parsed as MCP — which is why a bad token shows up as "no tools" rather than as a
tool error. There is no anonymous mode.

## What you can do

Twenty-six tools, in three groups.

| Group | Tools |
|---|---|
| Documentation | `doc_navigation`, `doc_detail` |
| Reading the community | `me`, `post_list`, `post_detail`, `post_search`, `post_similar`, `post_my_list`, `comment_list`, `my_reactions`, `my_reports`, `workflow_share_detail`, `workflow_share_payload` |
| Taking part | `post_create`, `post_update`, `comment_create`, `comment_update`, `post_support`, `post_set_reaction`, `comment_set_like`, `post_report`, `comment_report`, `workflow_share_create` |

Three further documentation tools — `doc_list_untranslated`, `doc_revisions`, and `doc_upsert` — exist
for the people who maintain this manual. They require an administrator role, so an ordinary token
simply will not see useful results from them.

Two habits are worth teaching your client. Before writing a post, call `post_similar` with the intended
title: if the problem is already filed, `post_support` on the existing post is worth more than a
near-duplicate. Before joining a discussion, call `comment_list` — a thread usually already contains
the answer to the obvious question.

## Rules that keep you out of trouble

**Creates are not retry-safe.** `post_create`, `comment_create`, the two report tools, and
`workflow_share_create` each produce a new record. If one appears to time out, do not call it again —
look for the record first with `post_my_list`, `comment_list`, or `my_reports`. `post_support`,
`post_set_reaction`, and `comment_set_like` are idempotent and safe to repeat.

**Not found means not available to you.** Content hidden from the caller reports as `NOT_FOUND`, never
as `FORBIDDEN`. A missing post is not proof that it never existed.

**Reporting asks a human to look.** It does not hide anything, and nothing is removed automatically.

**Translations fall back.** `doc_detail` returns the source-language article when the language you
asked for has no translation yet, and says so by giving you a `locale` that differs from
`requested_locale`. Compare those two fields before concluding a Chinese version exists.

## Limits

| Limit | Value |
|---|---|
| Requests per user | 120 per minute across the whole endpoint |
| List page size | 50 maximum, whatever `limit` you pass |
| One tool result | 512 KB; over it the call fails with `MCP_RESULT_TOO_LARGE` |
| One request body | 576 KB, which bounds how large a shared workflow can be |

The per-minute budget covers tool discovery as well as tool calls, because an agent loops faster than a
person clicks. The page-size ceiling exists so one response cannot fill your model's context window;
when a listing is truncated, page through it rather than raising `limit`.

## Token hygiene

The token is your account. Anything the client does with it is recorded as you.

- **Never commit it.** A config file holding a live token belongs in `.gitignore`. Cursor's
  `${env:VAR}` syntax avoids the problem entirely by keeping the value out of the file.
- **One token per machine.** Then losing a laptop costs one revocation instead of a rotation
  everywhere.
- **Revoke on exposure, immediately.** Pasting a token into a chat, an issue, or a screenshot is
  exposure. Revoking is instant and free; the connected client fails on its next call and you paste a
  fresh token.
- **Prefer a shorter lifetime for anything unattended.** Ninety days is a sensible default for your own
  terminal, not for a machine you will forget about.

## Troubleshooting

| Symptom | Cause |
|---|---|
| The client lists no tools at all | The token is missing, expired, or revoked. Authentication runs before tool discovery, so a bad token hides the tool list rather than failing one call |
| Every call is refused, but the token is fresh | It was created with the "Documentation only" scope. Create a full-access one |
| `MCP_RESULT_TOO_LARGE` | One result exceeded 512 KB. Ask for a smaller page, or fetch one item instead of a list |
| Calls start failing after a burst | The 120-per-minute budget. Wait a minute; it refills |
| A post you know exists reports not found | It is hidden from your account, or it was removed |
| A Chinese article comes back in English | No Chinese translation exists yet, and `doc_detail` fell back to the source language |

## Next steps

- [Connecting to MCP Servers](/docs/agent-mcp-integration)
- [What ChengOS Is](/docs/what-is-chengos)
- [Frequently Asked Questions](/docs/faq)