Connect an AI assistant to HelpVox

Set up

No browser? Use an API key

The OAuth sign-in needs a browser and a localhost redirect. A server without a screen, a CI job or a client that can only send a fixed header can use a HelpVox API key instead: the same key that opens the REST API. Create one under Integrations → HelpVox API keys in the dashboard and send it as a bearer token:

Authorization: Bearer hv_live_…

For example, in Claude Code:

claude mcp add --transport http helpvox https://www.helpvox.ai/mcp --header "Authorization: Bearer hv_live_…"

An API key has every permission of the company, with no per-client approval — keep it where you keep other secrets. Everything done with it is logged as the key, not as a person, and revoking the key under Integrations cuts the assistant off at once.

What you approve

The approval page shows the company (pick one if you belong to several) and the permissions the assistant asked for. Untick any write permission to grant less.

• read — orders, catalogue, conversations, callback requests, appointments, knowledge base, account
• orders:write — update order status and courier details, add shipment events, create orders
• requests:write — resolve callback requests, confirm or cancel appointments
• knowledge:write — replace the FAQ / knowledge base
• products:write — create, update and delete catalogue products and their prices
• settings:write — markets and delivery, opening hours and resources, pronunciations, phone and chat agent settings, test mode, integration switches and sync
• team:write — invite and remove team members, change roles, create and revoke API keys (access, not settings — granted separately)

Everything the assistant reads or changes is logged as done by the person who connected it. Disconnect it any time from Dashboard → Settings → Connected AI apps; the assistant then has to ask for access again.

Tools

get_account                list_orders            get_order              get_order_events
update_order               add_order_events       create_order
search_products            list_products          get_product
create_products            upsert_products        delete_product
list_categories            create_category        update_category        delete_category
list_conversations         get_conversation
list_callback_requests     resolve_callback_request
list_appointments          update_appointment
list_knowledge             replace_knowledge
get_company_profile        update_company_profile

# settings (settings:write)
get_settings               update_settings
list_markets               set_markets
get_hours                  set_hours
list_resources             add_resource           remove_resource
list_time_off              add_time_off           remove_time_off
list_pronunciations        set_pronunciations
list_chat_agents           get_chat_agent         update_chat_agent
list_phone_agents          get_phone_agent        update_phone_agent
get_integration            update_integration     run_sync

# access (team:write)
list_team                  invite_member          set_member_role        remove_member
list_api_keys              create_api_key         revoke_api_key

Tools not covered by the granted permissions are not offered at all. Each tool mirrors the matching endpoint of the HelpVox REST API — same fields, same status rules, same errors.

If something does not work

• Opening the URL in a browser shows a short JSON description. That is expected — the address is for assistants, not browsers. Add it in the client instead.
• The approval page says the app is not registered. The client skipped registration; remove the server from the client and add it again with the plain URL, without a client id or secret.
• “Needs authentication” after it used to work. Access was revoked in the dashboard or the sign-in expired after 30 days of no use. Run the client’s login step again.
• A tool is missing. Its permission was not granted. Disconnect in the dashboard and connect again, leaving that permission ticked.

Technical details for client developers: transport is Streamable HTTP (POST JSON-RPC, no server-sent events); authorization is discovered from /.well-known/oauth-protected-resource/mcp; PKCE S256 is required and dynamic client registration is open.