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, not a support one. It configures the workspace. It cannot read your conversations or reply to a customer — see 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#

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.

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 keep a scope your plan lost. Downgrade from Growth and the conversation scopes stop working that day, on tokens already issued.

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.