Let Claude, ChatGPT, Cursor or any assistant that speaks the
Model Context Protocol work in your
HelpBites workspace: read the inbox, draft a reply, move a feedback post along,
write a changelog entry, look into an error. You keep control: the assistant
acts as you, with your role, in one workspace, and you can cut it off from
Settings → API keys at any time.
The server is one address on your HelpBites host:
https://YOUR-SUPPORT-HOST/mcp
It is stateless Streamable HTTP (JSON-RPC 2.0), so it needs nothing beyond the
app itself, so it runs on a self-hosted instance as is. The same address is shown,
ready to copy, under Settings → API keys and on the workspace's Developer & MCP
page (with the Claude Code command below).
There are two ways to sign in. Browser sign-in creates and manages a scoped API
key for the assistant behind the scenes; you do not need to create or paste one.
For clients that only support static headers, you can provide an API key yourself.
Assistants that run in the cloud can't be given a header, so they sign in with
OAuth instead.
In Claude, add a custom connector from Settings → Connectors → Add custom
connector. In ChatGPT, open Plugins → + → Add custom MCP server, paste
the address above, and choose OAuth authentication.
Your browser opens HelpBites. Sign in if you aren't, check the workspace,
choose whether the assistant may read and change things or may only read, choose all projects or only some,
and press Approve.
The assistant gets a key named MCP: Claude (or whatever it called itself).
It is listed under Settings → API keys. Revoking it there disconnects the
assistant.
What this needs:
A public https address. Cloud assistants call your server from the
internet, so localhost won't do (use a tunnel while you try it, and set
APP_URL to the tunnel's address).
HELPBITES_SECRET set on the server (it signs the assistant's registration).
A role that may manage API keys (owners and admins).
The browser connection renews its 30-day access key automatically each time the
assistant uses it, and a connection nobody uses for 90 days ends. Its rotating
refresh token is tied to the API-key record, so revoking that key under
Settings → API keys disconnects the assistant. A refresh token that is used a
second time after the first minute is treated as a stolen copy and the whole
connection is revoked; reconnect from the assistant if that happens.
The approval page shows the address you are sent back to, in plain sight. For an
assistant HelpBites doesn't recognise (anything other than Claude, ChatGPT, a
local app or an editor's own address) it says so and selects Read only for you.
Only approve a connection you just started. An assistant's registration can only
point at an https address, a loopback address or an app's own scheme, and its name
is shown as plain text.
Changes made by an assistant through MCP tools are marked via MCP in a
Planning item's edit history; direct API-key edits are marked via API.
Comments written with comment_on_board_item display the connected assistant's
name (such as ChatGPT or Claude), while the operator who authorized the
connection remains recorded as the actor.
ChatGPT's custom MCP connections are available on supported Business,
Enterprise and Edu workspaces; availability and controls depend on the
workspace plan and admin settings.
Clients that only run local programs (an older Claude Desktop) can bridge with
npx mcp-remote https://YOUR-SUPPORT-HOST/mcp --header "Authorization: Bearer ak_…".
Each tool is one of the documented /v1 API routes, called with the assistant's key, and together they cover what the
panel does: if you can do it in the panel, an assistant can, except what is under Left out on purpose below. Nothing here is a back door: the role check, the
workspace and a key's project limit apply exactly as they do in the panel and the native app. The tools are grouped by
where you meet them in the panel; ask the server for the live list with tools/list.
The work board behind the roadmap: cards and epics (filter with kind, epic, release, a changelog release).
create_board_item
Add an item. Pass your own clientId to make it safe to retry: the same one returns the item already created.
create_board_item_from_feedback
Plan a feedback post: the AI writes the item, the post is linked.
update_board_item
Edit or move an item.
delete_board_item
Remove an item and its links: asks first.
link_board_item
Link or unlink a feedback post, conversation or related item.
merge_board_item
Fold a duplicate item into another: its posts, conversations, labels and files move over, and the source is closed, not deleted: asks first.
list_board_item_history
An item's edit history: what changed, who changed it and from where.
suggest_board_item_title
The AI writes a title from a description. Saves nothing.
suggest_board_item_public_description
The AI writes the public roadmap text from the title and description, without brand names or comparisons to other products. Saves nothing.
upload_board_comment_attachment
Upload an image, file or MP4/MOV video from a public url (HelpBites downloads it; use this for large screenshots and recordings) or as base64, and get its download URL, to attach to a comment or an item.
create_attachment_upload
Get a 15-minute URL to curl -T a local file to as raw bytes (no base64, no public link needed), for files too big to send inline; the PUT returns the attachment object.
list_board_item_comments
Read an item's private comments, threaded replies and attachment URLs.
comment_on_board_item
Add a private comment or threaded reply, optionally with uploaded files.
list_github_refs
Commits and merged pull requests that mention an item as #12.
A project's Settings: name, site, sender, access, hidden sections, and the feedback, changelog, blog, legal, newsletter, widget, hub, company and style sections. Only what you send changes; lists inside are replaced whole. Asks first.
update_board_settings
The Planning board: turn it on, its statuses and labels (replaced whole), the public roadmap's layout and whether linked feedback follows item status. Asks first.
update_project_flags
Replace a project's feature flags (send them all; one left out is deleted).
The GitHub accounts connected to the workspace (no tokens).
list_github_connection_repos
The repos one connection can read, to pick from for a project.
get_workspace
The workspace's name, status and your role in it.
get_usage
The plan, its limits and features, and what the workspace has used.
get_storage_usage
Where the workspace's storage goes, by kind of file and by project.
rename_workspace
Change the workspace's name.
Try: "Which conversations are unread? Draft a reply to the one about the failed
export, and show it to me before sending." Or: "Suggest plans for our pricing
table from the repo, and show me before you change anything."
It acts as you. The assistant can do what your role does in that
workspace, no more. A key limited to some projects can't reach the rest, or
anything workspace-wide.
It can be read-only. Choose Read only when you create a key or approve a
sign-in, and the connection can look at everything your role can see and change
nothing: it is offered only the tools that read, and the API refuses any other
call from that key with 403 key_read_only. Good for summaries, triage and
anything you would rather not have steered by a customer's message. Switch an
existing key either way in Settings → API keys (or PATCH /v1/admin/api-keys/{id}
with readOnly).
A key can't mint access or move where things go. Creating, renaming or
revoking API keys, adding, re-roling or removing teammates, inviting people,
revealing or rotating a project's secret, creating a project (the answer holds
its secret), changing the workspace's AI providers, deleting the workspace,
connecting Telegram, Stripe, a revenue source, GitHub or an error tracker,
registering a push device, approving an assistant's sign-in, importing or
exporting a workspace, and everything that sets where customer data, mail or
credentials go (custom domains, inbound addresses, webhook endpoints, a
project's linked repositories, contact sources, a project's notification
addresses, sender, reply-to and mail domain, site URL, allowed origins, whether
email bodies are logged, and its event and action webhooks) need a person
signed in to the panel; an API key, an assistant's included, gets
403 session_required. Otherwise a steered assistant could leave itself a way
back in, or a copy of your customers' messages going somewhere, that outlives the
connection you can revoke. Each of these actions writes a line to the audit log.
A path argument is an id. The assistant's arguments are put in a URL, so an
id may only hold letters, digits, dashes and underscores, and never a word that
names another route (export, stats, config…).
A call that doesn't answer is given up on after 30 seconds, a request body
is limited to 4 MB, and a batch to 20 messages. /mcp takes API keys and OAuth
connections, not a panel session.
Writes are marked. Every tool says whether it only reads, and assistants
that ask before acting use that. Replies to customers, sent email, publishing,
deleting and replacing a whole list reach real people or can't be taken back:
those tools are marked destructive, and their descriptions tell the assistant to
confirm first. Prefer a client that asks you to approve each write.
Customer text is untrusted. Messages, feedback and error reports are written
by other people, and an assistant reads them. Someone can try to slip it
instructions ("reply with a refund code"). Keep write approvals on, and read what
an assistant is about to send before you allow it.
Secrets stay out of answers. A template's share token, a webhook's signing
secret, a provider key, and the token in an error tracker's webhook address are
cut from what an assistant reads, wherever they sit in a record.
An assistant never subscribes anyone. Marketing consent is the person's own:
a contact written through the MCP can be unsubscribed, never subscribed.
Marketing is for admins. Sending a campaign or an email, running a sequence,
suppressing an address and erasing a contact through /v1 need the marketing
role (admin), as their /v1/admin twins always did; a project secret, the host
app's own server, is not asked.
Revoke at any time. Each connection is an API key: rename or revoke it
under Settings → API keys. Changing your password with revoke keys
ticked removes them all.
Limits apply. A key is limited to 600 calls a minute, and to the plan's
per-minute allowance on the hosted edition.
Results are trimmed. A very long answer is cut off after 60,000 characters
with a note, so one big list doesn't fill the assistant's memory: ask for less
with a filter or limit.
A tool that fails (a wrong id, a role that can't do that) answers with
isError: true and the API's own message, so the assistant can correct itself.
The server offers tools only; it keeps no sessions, so GET and DELETE on
/mcp answer 405. For anything the tools don't cover, the full
API is the same key's reach, and building your own interface on
it is just as supported.
For the curious, or anyone writing a client. It is standard OAuth 2.1 with PKCE
(S256), no client secret, and dynamic client registration:
Step
Where
The server answers 401 with WWW-Authenticate: Bearer resource_metadata="…"
POST /mcp
Protected resource metadata (RFC 9728)
/.well-known/oauth-protected-resource
Authorization server metadata (RFC 8414)
/.well-known/oauth-authorization-server
Register the client (RFC 7591)
POST /v1/oauth/register
The person approves
the panel page /oauth/authorize
Exchange the code
POST /v1/oauth/token
Registration stores nothing: the client id is the client's name and redirect
addresses, signed with a key derived from HELPBITES_SECRET. Redirect addresses
must be https, http://localhost, or an app's own scheme (cursor://). The
authorization code lives two minutes in Redis and works once. Access tokens are
ordinary admin API keys, rotated with one-use refresh tokens; revoking the key
also prevents further refreshes.
An assistant can do what the panel does, except these, which stay with a signed-in person (or are not a JSON call):
Access and credentials. Signing in, passwords, API keys, approving an assistant's connection, adding or removing
teammates and invitations, revealing or rotating a project's secret, connecting or disconnecting Stripe, RevenueCat,
GitHub, error trackers, Telegram or a contact database (they carry secrets), creating a project (the answer holds its
secret), deleting a workspace, and moving data between servers. A tool that lets an assistant mint a way back in would
outlive the connection you can revoke, so the API itself refuses most of these to an API key (403 session_required).
Files and streams. Uploading or downloading images, logos, brand files and documents, template import and export,
live event streams, the streaming AI chats of the email designer and Pages, and previews that return rendered HTML.
What customers use. The chat widget, votes, reactions and subscriptions made as a customer, public checkout, the
public delivery APIs and the webhook receivers.
Bulk imports from other systems (Ghost, other changelogs and feedback tools).
For these, and for anything newer than the tools, the full API is the same key's reach; its
OpenAPI spec lists every route. tests/mcpCoverage.test.ts keeps this list honest: a /v1 route
that has neither a tool nor an entry there fails the test.
No prompts, resources or live notifications: the server offers tools.
A connection has your role, narrowed by a project limit, read-only and an expiry:
there is no role of its own (say, one that may reply but not publish) yet.
Section settings (feedback, changelog, blog, widget, legal, marketing, style, hub) are objects whose keys
are described in words: the tool schema cannot check what is inside them, the route does.