Docs/Guides

AI assistants (MCP)

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).

Connect#

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.

Sign in with your browser (Claude, ChatGPT)#

Assistants that run in the cloud can't be given a header, so they sign in with OAuth instead.

  1. 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.
  2. 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.
  3. 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.

Paste a key (Claude Code, Cursor, scripts)#

Create a key under Settings → API keys, optionally limited to some projects or read only, and give it to the client as a header.

Claude Code:

claude mcp add --transport http helpbites https://YOUR-SUPPORT-HOST/mcp \
  --header "Authorization: Bearer ak_…"

Cursor (~/.cursor/mcp.json), and most other clients that take a URL:

{
  "mcpServers": {
    "helpbites": {
      "url": "https://YOUR-SUPPORT-HOST/mcp",
      "headers": { "Authorization": "Bearer ak_…" }
    }
  }
}

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_…".

What it can do#

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.

Tool What it does
list_projects The projects in the workspace, with their ids. Most other tools need one.
get_me Who this connection acts as: the operator, their role, the workspaces and the plan.
get_overview The overview: unread, open, revenue and errors per project.
search Search conversations and knowledge base answers.

Team and attention#

Tool What it does
list_team_members Everyone in the workspace with their role; their ids are what assigneeId takes.
get_workspace_attention What waits on someone: drafts to approve, failed syncs, bounces, error alerts, feedback to triage, and the unread badge.
get_unread_count The inbox badge: customer messages waiting on a reply, never cached.

Conversations#

Tool What it does
list_conversations The inbox: filter by project, status, unread, assignee, priority, tag or customer.
get_conversation One conversation with its customer and project.
get_conversation_messages Its messages, internal notes and timeline events.
reply_to_conversation Send a reply to the customer, and email them whenever they have an address: asks first.
add_internal_note A note only the team sees.
update_conversation Status, priority, tags, assignee.
archive_conversation Archive or restore.
search_end_users Find a customer by name, email or id.
get_conversation_context Who the customer is: plan, MRR, past conversations, linked posts.
link_feedback_post Link a feedback post to a conversation, or file one for the customer.
draft_conversation_reply A draft reply from the project's assistant. Nothing is sent.
save_conversation_faq Save an answer from a conversation to the knowledge base.
start_conversation Open a conversation with a customer and send the first message (and email it): asks first.
delete_conversation Permanently remove a conversation and its messages: asks first.
set_conversation_status Close or reopen a conversation, or move it to another status of its type.
mark_conversation_read Mark a conversation read or unread for the team.
get_conversation_suggestions FAQs and saved replies to answer a conversation with.
run_conversation_action Run a host action configured on the conversation's type (it calls your app): asks first.

Messages#

Tool What it does
unsend_message Delete a message or note the team sent: asks first.
toggle_message_reaction Add or remove a tapback (like, heart, question...) on a message.

Saved replies#

Tool What it does
list_saved_replies Reusable replies.
create_saved_reply Add one.
update_saved_reply Change a reply's title, text or shortcut.
delete_saved_reply Remove a saved reply: asks first.

Conversation types#

Tool What it does
list_conversation_types A project's ticket types with their statuses, intake fields and host actions.
create_conversation_type Add a ticket type with its own statuses, fields and actions.
update_conversation_type Edit a type; the statuses, fields and actions lists you send replace the old ones.
delete_conversation_type Delete a type no conversation uses: asks first.

AI assistants#

Tool What it does
list_assistants The AI support assistants, with their settings (never their provider key).
get_assistant One assistant, and what it still needs before it answers customers by itself.
create_assistant Add an assistant; it starts as a draft with auto-reply off.
update_assistant Edit its instructions, model, routing rules or status; turning it live asks first.
delete_assistant Remove an assistant and its knowledge assignments: asks first.
duplicate_assistant Copy an assistant as a draft (without its key, rules or confidence bar).
list_assistant_assignments The knowledge an assistant is given or kept from.
add_assistant_assignment Give an assistant a knowledge model, a path or one FAQ, or keep one out.
remove_assistant_assignment Take back one grant or exclusion.
get_assistant_knowledge The active FAQs an assistant can read right now.
test_assistant_retrieval The knowledge an assistant would be given for a question. Saves nothing.
generate_assistant_answer The answer an assistant would write for a question (uses AI credits). Saves nothing.
test_assistant_answer What an assistant would do with a customer message: answer, hand over or stay silent, and why.

Feedback board#

Tool What it does
list_feedback A project's feedback board.
get_feedback_post One post with its comments.
update_feedback_post Change status, hide, feature or lock a post.
comment_on_feedback_post Comment as the team, or leave an internal note.
get_feedback_config The board's statuses, types, platforms, tags and options: the keys the other tools accept.
get_roadmap The public roadmap as visitors see it.
create_feedback_post File a post on the board as the team.
delete_feedback_post Delete a post with its votes and comments: asks first.
merge_feedback_post Merge a duplicate into another post, moving its votes: asks first.
list_feedback_comments A post's comments, including internal notes and hidden ones.
update_feedback_comment Hide, make internal or restore a comment, or rewrite its text.
delete_feedback_comment Remove a comment: asks first.
list_feedback_participants Who can be @mentioned in a post's thread.

Planning#

Tool What it does
list_board_items 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.

Changelog: entries#

Tool What it does
list_changelog_entries Changelog entries, drafts included.
create_changelog_entry Write an entry: a draft unless told to publish.
update_changelog_entry Edit an entry, or publish a draft.
changelog_linked_conversations The conversations a changelog entry answers.
reply_to_changelog_conversations Tell all of them it shipped.
create_changelog_entries Write up to 50 entries at once, skipping commits already written up.
merge_changelog_entries Fold 2 to 10 entries into one and archive the sources: asks first.
suggest_changelog_merges The AI proposes which of 2 to 300 entries (100 without Jev on the server) to merge, and the merged text (possibly none). Saves nothing.
delete_changelog_entry Delete an entry: asks first.
link_changelog_entry Link or unlink a feedback post, board item or conversation an entry ships.
review_changelog_entry Approve (publish) or reject a draft entry: asks first before approving.

Changelog: AI drafts and email#

Tool What it does
generate_changelog_from_commits Have the AI draft entries from the project's GitHub commits.
get_changelog_generate_run The state of the last AI run: running, done or failed, with counts.
run_changelog_notify Run the changelog email job now, or as a dry run: asks first.
get_changelog_subscriber_counts How many people the changelog emails, by cadence.

Changelog: releases#

Tool What it does
list_changelog_releases A project's releases, drafts included.
create_changelog_release Create a release (a version that groups entries), a draft by default.
update_changelog_release Edit a release: asks first when publishing.
delete_changelog_release Delete a release; its entries stay: asks first.
publish_changelog_release Publish a release and its draft entries: asks first.
suggest_changelog_release_copy The AI proposes a release's headline and intro. Saves nothing.

Changelog: reader comments#

Tool What it does
list_changelog_comments The comments under an entry, including hidden ones.
moderate_changelog_comment Hide a reader's comment or show it again.
delete_changelog_comment Take a comment down for good: asks first.

Errors#

Tool What it does
list_errors Issues from the connected error tracker.
get_error One issue with its latest event and stack trace.
file_error_on_board Turn an error into a board item.
set_error_status Open, resolve or close an issue in the tracker and its inbox conversation.
analyze_error AI analysis of one error with a suggested fix, or the context to hand to a coding agent.
analyze_errors AI triage of all unresolved errors, saved as a report.
list_error_analyses The saved analyses and the latest triage report.
list_error_reports Saved triage reports, newest first.
delete_error_report Remove one saved report: asks first.
get_error_report_schedule How often the AI triage runs on its own.
set_error_report_schedule Run the AI triage daily, weekly, monthly or never.
get_error_alerts The alert rules, who is mailed and the alerts that fired recently.
set_error_alerts Replace the alert rules and recipients (send them all): asks first.
get_filed_error The board item an error was filed as, if any.
rename_error_link Change the label of a tracker project the project reports to.
remove_error_link Stop reporting to a tracker project; nothing is deleted in the tracker: asks first.
list_error_providers The supported trackers and whether a server is connected for each.
list_error_servers The tracker servers of the workspace (never their tokens).

Knowledge base: answers#

Tool What it does
list_knowledge_models The knowledge bases, with their ids.
list_faqs Knowledge base answers: filter or search.
get_faq One answer.
create_faq Add a question and answer.
update_faq Edit an answer, its tags, keywords, folder or status (draft, active, disabled, archived, outdated).
delete_faq Remove one: asks first.
list_knowledge_documents Documents uploaded as knowledge sources.

Knowledge base: models#

Tool What it does
get_knowledge_model One knowledge base: name, status, language, project.
create_knowledge_model Start an empty knowledge base for a project.
update_knowledge_model Rename it, change its status (archive instead of deleting), language or description.
delete_knowledge_model Delete it with all its FAQs, folders and documents; reports the impact unless confirmed: asks first.
get_knowledge_model_dashboard Counts: FAQs by status, folders, documents, what waits for the search index.
duplicate_knowledge_model Copy a model with its folders and FAQs (the copies are drafts).
reindex_knowledge_model Rebuild the model's search index in the background.

Knowledge base: folders#

Tool What it does
list_knowledge_nodes A model's folder tree, flat and nested.
create_knowledge_node Add a folder, at the top or under another.
update_knowledge_node Rename, move or reorder a folder.
delete_knowledge_node Remove a folder; its children and FAQs move up. Reports the impact unless confirmed: asks first.

Knowledge base: FAQs in bulk, documents and imports#

Tool What it does
bulk_update_faqs Set the status of, move, tag or delete up to 500 FAQs at once: asks first.
get_knowledge_document One uploaded document with its version history and the number of FAQs made from it.
delete_knowledge_document Remove a document; its FAQs stay. Reports the impact unless confirmed: asks first.
reprocess_knowledge_document Re-read a document's file and update the FAQs made from it.
get_knowledge_import Where a document is in its import: status, errors, stats.
commit_knowledge_import Create or update FAQs from reviewed entries for an uploaded document.

Contacts and segments#

Tool What it does
list_contacts A project's people: filter by segment, tag, subscription, billing or search.
get_contact One person, with their plan, MRR, language and tags.
get_contact_activity Everything one person has done in one list: conversations, posts, votes, emails, payments, onboarding.
update_contact Name, language, tags, email, user id and attributes. Never marketing consent.
list_segments Saved segments.
upsert_contacts Create a person or update the one who matches (by user id, then email), one at a time or up to 1000. Never subscribes anyone to marketing.
erase_contact Erase a person and everything they left in the project: asks first.
create_segment Save a filter over the contacts as a segment.
preview_segment Count who a filter or segment matches, with a sample. Saves nothing.
update_segment Rename a segment or give it a new filter.
delete_segment Delete a segment; the contacts stay: asks first.

Sequences and campaigns#

Tool What it does
list_sequences Automated email sequences.
enroll_in_sequence Put people (or a whole segment) on an active sequence.
list_automation_recipes Ready-made sequences started by an event.
install_automation_recipe Add a recipe as a draft sequence.
list_campaigns A project's email campaigns with their numbers.
get_campaign One campaign: numbers, audience size, what stops it sending.
create_campaign A draft: template, segment or topic. Sends nothing.
update_campaign Edit a draft, or schedule, send, pause or cancel: sending asks first.
get_sequence One sequence with its trigger, steps and counts.
create_sequence A draft series of emails. Sends nothing until it is activated.
update_sequence Edit a sequence, or activate or pause it: activating asks first.
delete_sequence Delete a sequence and everyone's place on it: asks first.
list_sequence_enrollments Who is on a sequence, where they are and when the next email is due.
delete_campaign Delete a campaign that is not sending: asks first.
send_campaign_test Send a campaign to up to five addresses as a test: asks first.

Lead forms#

Tool What it does
list_lead_forms A project's waitlist and interest forms, with their sign-up numbers.
get_lead_form One form: fields, words, look, settings, translations.
create_lead_form Add a form from a preset; it is live at once.
update_lead_form Change fields, words, look, settings or close the form.
delete_lead_form Delete a form; its leads stay contacts: asks first.
translate_lead_form Translate a form into other languages with AI.
list_lead_files Files people attached through a form, for one person or one form.
delete_lead_file Delete one of those files for good: asks first.

Onboarding flows#

Tool What it does
list_onboarding_flows A project's onboarding flows, drafts included, with what is published.
get_onboarding_flow One flow: steps, style, options, translations.
create_onboarding_flow Start a draft flow, with three starter steps unless you send your own.
update_onboarding_flow Edit the working copy (steps, look, options, translations). Apps keep the published version.
delete_onboarding_flow Delete a flow: asks first.
publish_onboarding_flow Make the working copy the version apps get: asks first.
unpublish_onboarding_flow Take a flow offline; apps get a 404.
translate_onboarding_flow Translate a flow into other languages with AI.

Email templates#

Tool What it does
list_email_templates A project's email templates, or the shared masters.
get_email_template One template: subject, design, variables.
send_test_email Send a template, with sample values, to up to five addresses: asks first.
list_email_starters The built-in designs a new template can start from.
create_email_template Add a template: from a design, a starter, a blank page, or by linking a master.
update_email_template Edit a template's name, key, design, variables, folder or translations.
delete_email_template Delete a template: asks first.
duplicate_email_template Copy a template.
detach_email_template Turn a linked master into the project's own copy: asks first.
share_email_template Open or revoke a view or edit link to one template: asks first.
translate_email_template Translate a template into other languages with AI.
list_email_chats The AI designer chats people had about a template.
get_email_chat The messages of one AI designer chat.
delete_email_chat Delete an AI designer chat: asks first.
stop_email_chat_turn Stop the AI designer while it is answering.

Email folders and components#

Tool What it does
list_email_folders The folders that organise a project's (or the masters') templates.
create_email_folder Add a folder.
update_email_folder Rename a folder or move it into another.
delete_email_folder Delete a folder; what is inside moves up: asks first.
list_email_components The library of reusable email blocks.
create_email_component Save custom HTML with {{@key}} fields as a reusable block.
update_email_component Edit a block in the library; emails already using it keep their copy.
delete_email_component Remove a block from the library: asks first.

Email log, totals, settings and suppressions#

Tool What it does
list_email_logs Everything sent or tried: filter by address, template, status, campaign.
list_email_suppressions Addresses a project no longer mails.
get_email_log One sent message: status, delivery events and its content when kept.
get_email_stats Email totals by status, source and day, and the most-sent templates.
delete_email_logs Delete log entries older than a date: asks first.
get_email_settings How this server sends email: sender, webhook, retention. No secrets.
add_email_suppressions Stop a project mailing these addresses.
remove_email_suppression Mail an address again: asks first.

Transactional email#

Tool What it does
send_email Send a template, your own HTML, a design or a plain message to up to 50 people for a project: asks first.
render_email Preview exactly what a send would deliver. Nothing is sent.
preview_email_template Render a template by id with its sample values.

Pricing tables#

Tool What it does
list_pricing_tables A project's pricing tables.
get_pricing_table One table's plans, features, words, look and A/B test.
create_pricing_table Start a draft from a template.
update_pricing_table Edit plans, features, prices, words, look or translations.
publish_pricing_table Make the table live: asks first.
get_stripe_catalog Stripe products, prices and payment links to link plans to.
get_pricing_stats Views, clicks, purchases and revenue, and the A/B test result.
suggest_pricing AI proposal for plans, features and prices, from the repos and Stripe.
add_pricing_variant Copy a table to test against it.
start_pricing_experiment Start an A/B test: asks first.
stop_pricing_experiment End it, optionally keeping the winner.
preview_pricing_table See the table as apps would get it, with optional changes applied. Saves nothing.
translate_pricing_table AI translation of the working copy into up to eight languages, saved as translations.
unpublish_pricing_table Back to a draft; its public URL and checkout links stop working: asks first.
delete_pricing_table Remove a table for good: asks first.

Revenue and Stripe#

Tool What it does
get_revenue_report Revenue over every connected source: net, MRR, subscribers, months, plans, top customers, recent payments.
sync_revenue_source Read Stripe, App Store, Paddle or Lemon Squeezy again now, optionally from the start.
get_testflight_usage TestFlight installs, sessions, crashes and feedback per build, from the App Store source.
get_stripe_connection Whether Stripe is connected and how the last sync went (never the key).
get_contact_billing One person's Stripe customer, subscriptions and payments.
Tool What it does
list_legal_documents A project's legal documents, drafts included.
get_legal_document One document with its sections and rule coverage.
update_legal_document Edit sections or the summary: asks first when it is published.
publish_legal_document Make it public and record a version: asks first.
unpublish_legal_document Back to draft.
create_legal_document Start a draft from the wizard answers, with AI, blank, or by importing a text you already have. Nothing is public yet.
delete_legal_document Remove a document and all its versions: asks first.
check_legal_document Check a document against the rulepacks: coverage, and with AI per-requirement findings.
analyse_legal_text Read any pasted legal text (or a document) against the rules for its regions. Saves nothing.
suggest_legal_change_note AI note for the next version, from what changed since the last published one.
recompose_legal_document Re-run the clause composer on the answers, keeping hand-written and locked sections: asks first when it is published.
rewrite_legal_section AI rewrite of one section: a proposal by default, saved only with apply (asks first on a published document).
generate_legal_tldr AI summary for the top of the public page: asks first when it is published.
translate_legal_document A new draft of the document in another language, written by AI for review.
list_legal_versions The published versions, newest first.
restore_legal_version Put a published version back as the working draft, replacing the current text: asks first.
Tool What it does
get_legal_wizard The wizard's questions for a document type, plus the answers a project already supplies.
preview_legal_document Compose sections from answers and see the coverage, without saving or using AI.
suggest_legal_answers Suggest wizard answers from the project's GitHub repos, with the evidence for each.
list_legal_clauses The reviewed clause library the composer uses.
list_legal_rulepacks The requirement checklists the checks are grounded in.

Pages#

Tool What it does
list_cms_entries A project's pages and other entries, drafts included, with status and address.
get_cms_entry One entry's working copy: its block tree and style.
create_cms_entry A draft page, from a template, a block tree or empty. Nothing goes public.
update_cms_entry Edit the name, slug, style or the whole block tree of the working copy.
delete_cms_entry Remove an entry for good: asks first.
publish_cms_entry Make the working copy the live page: asks first.
unpublish_cms_entry Take a page offline; the working copy stays.
list_cms_components The built-in and the project's own components, with their fields and templates.
get_cms_component One of the project's own components.
create_cms_component Add a component: its fields and an optional HTML and CSS template.
update_cms_component Edit a component (fields is the whole list): asks first when pages use it.
delete_cms_component Remove a component: asks first.
list_cms_assets The files uploaded for pages, with their addresses and alt text.
upload_cms_asset Add an image, SVG, video or PDF to the pages' file library, from a public URL or as base64.
update_cms_asset Rename a file or change its alt text.
delete_cms_asset Remove a file: asks first.
get_cms_settings The Pages settings: the preview address and the messaging brief.
update_cms_settings Change the preview address or the messaging brief.
list_cms_templates The templates a new page can start from.
list_cms_repos The linked GitHub repos the assistants can read.
suggest_cms_wizard_answers The AI suggests the page wizard's answers from the linked repos. Saves nothing.

Blog#

Tool What it does
list_blog_posts A project's blog posts and standalone blog pages: drafts first, then published, scheduled ones marked.
get_blog_post One post with its Markdown, rendered HTML, SEO fields and newsletter state.
create_blog_post Write a post or page: a draft unless told to publish (publishing asks first).
update_blog_post Edit a post, schedule it, or publish or unpublish it: asks first when it goes public or is live.
delete_blog_post Remove a post with its comments and reactions: asks first.
send_blog_newsletter Email a published post to the subscribers as a campaign, now, scheduled, or as a draft to test first: asks first.
draft_blog_post_with_ai The AI proposes a whole post, a continuation, a rewrite, a passage or the title and meta text, from the linked repos. Saves nothing.
list_blog_comments The comments on every post for moderation, newest first.
update_blog_comment Hide or show a comment (or edit a team comment you wrote).
delete_blog_comment Take a comment down for good: asks first.
comment_on_blog_post Answer a post or a comment publicly as the team: confirm the wording first.

Brand kit#

Tool What it does
get_brand_kit The kit (tagline, about, colours, fonts, guidelines, page settings) and every file in it.
update_brand_kit Edit the kit; colours, fonts and guidelines are replaced as whole lists: asks first when the public page is on.
update_brand_asset Rename a brand file, change its kind, background, visibility or order.
delete_brand_asset Remove a brand file: asks first.

Project settings, flags and webhooks#

Tool What it does
update_project_settings 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).
list_webhook_endpoints A project's webhook endpoints.

Project setup and infrastructure#

Tool What it does
get_project_overview One project's numbers, setup checklist, what needs attention and latest activity.
get_project_setup What is wired up in a project and what is still to do.
get_project_email_setup Whether the project's email can send, and whether campaigns can start.
delete_webhook_endpoint Remove an endpoint: asks first.
test_webhook_endpoint Send a signed webhook.test event to an endpoint.
list_webhook_deliveries Recent deliveries with their status and errors.
list_project_domains Custom domains with their DNS records and check results.
list_inbound_addresses The addresses a project receives mail at.
get_project_repos The GitHub repos a project reads.
create_cards_with_ai Turn pasted text into feedback posts or board items with AI: asks first.

GitHub and the workspace#

Tool What it does
list_github_connections 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."

Safe by design#

  • 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.

Calling it yourself#

Every message is a JSON-RPC POST. List the tools, then call one:

curl https://YOUR-SUPPORT-HOST/mcp \
  -H "Authorization: Bearer ak_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl https://YOUR-SUPPORT-HOST/mcp \
  -H "Authorization: Bearer ak_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_conversations","arguments":{"unread":true,"limit":10}}}'

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.

How sign-in works#

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.

Left out on purpose#

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.

Not built yet#

  • 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.