MCP: set HelpStack up by asking

HelpStack speaks MCP (Model Context Protocol), so an AI assistant like Claude can configure your workspace for you. You describe what you want in your own words; it adds the knowledge base articles, the FAQ chips, the agent tools.

"Crawl our help centre, then add a tool that looks up an order by its number and email against https://api.mystore.si/orders."

This is a setup connection by default: it configures the workspace. It reads your conversations or replies to a customer only if an admin ticks those scopes when creating the token, which needs the Growth plan. The rest of the limits are under What it cannot do.

Quick facts#

1. Create a token#

Settings → API tokens → Create a token. Give it a name you will recognise later, like "Claude on my laptop", because that name is how you will know which one to revoke.

The token is shown once. We store only a hash of it, so there is no screen that can show it to you again and no support request that can recover it. If you lose it, revoke it and make another. That takes ten seconds and is the intended path, not a failure.

A token is tied to one organization — the one you were in when you created it. If you belong to several, create one token per organization you want to configure. A token cannot be moved between them, and joining another organization later does not widen a token you already hold.

1b. Choose what the token can do#

When you create a token you tick what it may reach. A token can never do more than you can — your role still applies — and the scopes only narrow it further.

The two settings: scopes are ticked by default, which is the setup surface this page describes. The two conversations: scopes are never pre-ticked — showing an assistant your inbox should be a decision someone makes, not one they inherit — and they only appear at all on the Growth plan. Untick settings:write and you get a token that can look at your configuration and change nothing — useful for letting an assistant audit a setup, or answer "what have we actually got configured?", without any risk of it editing.

tools/list only shows tools the token can call, so an assistant never sees a door it cannot open.

2. Connect your assistant#

Claude Code:

claude mcp add helpstack --transport http https://helpstack.eu/api/mcp \
  --header "Authorization: Bearer hs_your_token_here"

Claude Desktop and ChatGPT — add a custom connector pointing at https://helpstack.eu/api/mcp and sign in when it asks. These clients cannot send a token you paste, so they use a sign-in flow instead: you pick which organization to connect and approve what the app may do, on a HelpStack page. Nothing is granted until you approve it, and you can disconnect the app later from Settings → API tokens.

You do not need to create a token for that route. Tokens are for clients like Claude Code that can set a header themselves.

Codex — it reads the token from an environment variable, so it never lands in your config file:

export HELPSTACK_MCP_TOKEN="hs_your_token_here"
codex mcp add helpstack --url https://helpstack.eu/api/mcp \
  --bearer-token-env-var HELPSTACK_MCP_TOKEN

Anything else that speaks MCP over HTTP — point it at the same URL with the same header. There is nothing HelpStack-specific in the transport.

Then ask it to run whoami. It should answer with your organization's name and your role. If it does, everything below will work.

Two ways to connect#

Both end up in the same place: an identity with a role, an organization, and a set of permissions, re-checked on every call.

What it can do#

What your assistant is told before it calls

Every tool is published with three hints: whether it only reads, whether its effect can be undone, and which permission it needs. Clients like Claude, Cursor and ChatGPT read those to decide what to put in front of you first, so listing your channels goes through quietly while sending a reply asks.

Two of them are worth knowing about:

• Only two tools reach outside HelpStack. add_knowledge_base_url and recrawl_knowledge_base_source fetch a page from the web. Every other tool stays inside your own workspace.
• send_reply is marked irreversible, along with the four delete tools and the edits that overwrite something in place. draft_reply is not: a draft nobody approved has reached nobody, so retracting it costs nothing.

The hints are advice to the client, not a lock. What a token may actually do is still decided by its scopes and your role, re-checked on every call.

Numbers without the inbox

analytics:read and conversations:read are separate on purpose, and this is the distinction worth understanding before you tick anything. get_analytics returns aggregates: how many conversations, how fast they were answered, which tags are growing, what the AI got wrong. None of it is anything a customer wrote. search_conversations returns customer text, so it sits with the inbox tools instead.

So you can hand an assistant your numbers without handing it your inbox. "Refunds are up 40%" and "here is what fourteen people said about refunds" are different disclosures, and they are granted separately.

Reading is available to any member. Writing requires owner or admin, the same as the dashboard: a token belonging to an agent can look but not change. That is checked before your arguments are, so a token without permission learns nothing about a tool by calling it.

The one that ties it together

attach_knowledge_base_groups_to_channel is the step people miss. Adding articles does not aim them anywhere: a channel with no groups attached searches your whole knowledge base, which is right for one topic and poor for many. Group the articles, attach the group, and the AI answers that channel from that slice.

Answering the hard ones#

With conversations:read and conversations:draft, an assistant can read a difficult thread and write you a considered answer:

You: Read conversation 4821 and draft a reply. The customer is right that we shipped late, but the refund they are asking for is more than the order.

It calls get_conversation, reads the whole thread, and calls draft_reply. The draft lands in your inbox exactly like an AI-generated one, and you press send.

A draft cannot reach a customer. draft_reply never queues a send: the draft sits inert until a person approves it in HelpStack, where the approval is recorded against their name.

On an email channel with a reply template, write only the body. The greeting and the sign-off (closing line and signer) are added when the email is sent, so draft_reply and send_reply remove a greeting or sign-off your assistant wrote rather than send it twice.

Sending is a separate scope, conversations:send, and the separation is the point. conversations:draft does not imply it, nothing else grants it, and it is never ticked by default. "Write me an answer" and "answer them for me" are different decisions, so they are different permissions.

If you do grant it, send_reply replies immediately with nobody reviewing it — the same thing your channels already do when auto-reply is on. It runs the same language detection and translation the approve button does, so an English answer does not reach a customer who wrote in Slovenian, and the message is attributed to the person whose token it is rather than to an anonymous assistant. A sent message cannot be recalled.

Unsent drafts are marked as such when the assistant reads a thread back, so it never mistakes its own unapproved draft for something the customer has seen.

What it cannot do#

Deliberately, and this is the more useful half of the list:

• It cannot send unless you granted conversations:send, which is off by default, separate from drafting, and available only on Growth.
• It cannot see another organization. The organization comes from the token and is never something a caller passes in, so there is no argument to get wrong and no way to ask about a workspace that is not yours.
• It cannot read your inbox unless you granted that. The conversation scopes are off unless ticked, and unavailable below the Growth plan.
• It cannot exceed your own permissions. A token acts as the person who made it, with that person's role as it is now — demote someone and their tokens lose the same access immediately.
• It cannot outlive your membership. Remove someone from the organization and their tokens stop working on the next call, with no cleanup step.
• It cannot touch a channel's credentials. Mailbox passwords, Google refresh tokens and Meta page tokens are not fields any tool accepts, so connecting or reconnecting a channel stays a dashboard job. An assistant can change how a channel behaves; it cannot change what it logs in as.
• It cannot keep a scope your plan lost. Downgrade from Growth and the conversation scopes stop working that day, on tokens already issued. Tags work the same way: the taxonomy tools refuse an organization below Growth, so MCP is never a way around the plan.
• It cannot create a token. A token that could mint tokens would escape its own permissions in one call, so there is no tool for it. Tokens are created in Settings, by a person.
• It cannot add, remove, or re-role a team member. Changing who can reach your inbox is the same escalation as minting a token, so list_team_members reads and nothing writes. Invitations stay in the dashboard.
• It cannot touch billing. No tool starts a checkout, changes a plan, or opens the billing portal. A merchant billed through Shopify is refused off-platform checkout by the server anyway.
• It cannot connect Shopify or WooCommerce. Both need a person in a browser — an OAuth screen, or a pairing code pasted into WordPress.
• It cannot change anyone else's notifications. A preference row belongs to one person, so set_notification_preferences writes the token owner's and nobody else's.
• It cannot change the organization's URL slug. Your name and default language are settable; the slug appears in links and is not.

Worked example#

Setting up a store's support from nothing, in one conversation:

You: Here is our help centre: https://mystore.si/pomoc. Crawl it, then add an FAQ chip asking about delivery times, and a tool that checks order status against our API.

The assistant will call add_knowledge_base_url, then create_faq, then create_agent_tool — and will usually call list_agent_tools first to avoid duplicating a tool you already have.

Two things to expect:

• The crawl is not instant. Each run indexes roughly 50 pages and re-running reaches further, so a large site is covered over several crawls. Ask for list_knowledge_base_sources to see how far it has got.
• A tool's description is the important part. It is what the model reads to decide when to call your tool. Ask for it in plain terms — "only use this when the customer gives both an order number and the email they ordered with" — and it will be written into the description where it belongs.

When something is refused#

The errors you are most likely to see, and what they mean:

Keeping a token safe#

A token is a password that types itself. Treat it like one:

• One token per place it is used, so revoking one does not break the others.
• Revoke it when you stop using it. Settings → API tokens shows when each was last used, which is usually enough to tell which one is idle.
• Do not paste it into a shared document or a chat. If you have, revoke it — the cost of being wrong is someone reconfiguring your assistant.
• It is not for your customers or your website. It belongs on machines you control.

Related#

• Agent tools — what tools are and how to write a good description.
• Custom agent tools — the integrator's reference for the endpoints your tools call.
• Knowledge base — how crawling and articles behave.
• Feature flags — which capabilities your plan includes.