MCP Server

Connect Claude Desktop, Cursor, ChatGPT, or any MCP client to your Helpway workspace. Triage your inbox, draft replies, find hot leads, and search your knowledge base from your AI assistant.

Helpway exposes a Model Context Protocol server so any MCP-compatible AI client can operate your support workspace — read conversations, send replies across widget / email / WhatsApp, manage contacts, inspect live visitors, and search your knowledge base.

Endpoint

https://api.helpway.ai/mcp

There are two ways to authenticate. OAuth is the default — no key copy-paste, your client handles the browser approval flow for you.

Option A — OAuth (recommended)

Point your client at the endpoint and approve the connection in your browser when prompted.

No key to manage. The token is scoped to your Helpway login and can be revoked anytime from Settings → Developers.

Claude Code

Run this in your terminal:

claude mcp add --transport http --scope user helpway https://api.helpway.ai/mcp

Then run /mcp inside Claude Code and pick helpway → Authenticate — your browser opens the Helpway consent screen. Approve, and the tools are live. Manage servers anytime with claude mcp list.

Claude Desktop

Settings → Connectors → Add custom connector → paste the URL:

https://api.helpway.ai/mcp

A browser window opens for the Helpway consent screen. Approve, and the tools appear in your next chat.

Cursor

Settings → MCP → Add new MCP server, choose Remote, and paste the endpoint. Cursor triggers the OAuth flow on first use.

Via the npm bridge (still OAuth, no key)

If your client only supports stdio servers, use the published @helpway/mcp bridge — it still authenticates over OAuth, no key needed. The first run opens your browser to sign in; tokens cache in ~/.helpway and refresh automatically, so you only log in once.

{
  "mcpServers": {
    "helpway": {
      "command": "npx",
      "args": ["@helpway/mcp@latest"]
    }
  }
}

Option B — API key

For headless clients (CI pipelines, scripts) that can't do interactive OAuth, create an API key in Settings → Developers → API Keys, then pass it to the bridge via env:

claude mcp add helpway -s user -e HELPWAY_API_KEY=hw_sk_… -- npx -y @helpway/mcp@latest

Or as JSON config:

{
  "mcpServers": {
    "helpway": {
      "command": "npx",
      "args": ["@helpway/mcp@latest"],
      "env": { "HELPWAY_API_KEY": "hw_sk_…" }
    }
  }
}

Workspaces

One connection reaches every workspace you belong to — not just your default. Call list_workspaces first to see them; each has a slug and an id. Every workspace-scoped tool accepts an optional workspace argument (the slug or id) to target a specific one; omit it to use your default.

list_workspaces()
→ [{ slug: "acme", name: "Acme", default: true }, { slug: "riuve", name: "Riuve" }, …]

list_conversations({ workspace: "riuve", status: "open" })

Access is membership-checked — you can only target workspaces your account belongs to. OAuth connections see all your workspaces; API keys stay locked to the one they were created for.

Tools

Every tool below (except whoami and list_workspaces) accepts the optional workspace argument.

Tool	What it does
`whoami`	Confirm the account + default workspace + scopes you're connected as
`list_workspaces`	Every workspace you can operate on (slug, id, org, role)
`list_conversations`	Browse the inbox (status / channel / assignee filters)
`get_conversation`	Full thread + visitor + page history
`search_conversations`	Find a thread by keyword, customer, or topic
`send_message`	Reply on widget / email / WhatsApp (channel auto-routed)
`create_draft`	Stage a reply for human review before send
`resolve_conversation`	Resolve / reopen / mark spam
`assign_conversation`	Assign or unassign a teammate
`list_contacts`	Browse identified people
`get_contact`	Full profile + latest visitor + page history
`search_contacts`	Find a contact by name / email
`list_active_visitors`	Who's on the site right now, with current page
`get_visitor`	One session — device, locale, full page journey
`search_knowledge_base`	Semantic search for grounded replies
`list_articles`	Browse knowledge base entries
`list_inboxes`	Configured channels (email senders, WhatsApp numbers)

Example prompts

Once connected, talk to your AI client naturally:

"List my Helpway workspaces."

"In the Acme workspace, show open conversations from the last day that nobody has replied to."

"Find visitors who looked at the pricing page in the last hour and don't have a conversation yet, then draft a friendly check-in for each."

"Summarize this customer's history before I reply: search for sarah@acme.com and show her conversations."

Channels

send_message infers the channel from the conversation — you never pass it. Helpway routes:

Widget → WebSocket delivery with push-notification fallback
Email → threaded reply via the conversation's connected inbox
WhatsApp → WhatsApp Business message (where enabled)

Drafts vs. sends

When you want a human to review AI-generated copy before it reaches the customer, use create_draft instead of send_message. The draft lands in the inbox composer — a teammate edits if needed and clicks Send.

Rate limits

100 read calls/min and 30 write calls/min per key. Exceeding returns a 429 with a Retry-After header.