@helpway/mcp

MCP server for Helpway — connect Claude Desktop, Cursor, ChatGPT, or any MCP client to your Helpway workspace.

What you can do

• Browse + search conversations, contacts, and the knowledge base
• Send messages on widget, email, or WhatsApp channels (Helpway routes automatically)
• Create drafts for human review before send
• Resolve / reopen / assign conversations
• Read page history + live visitor signals to power proactive outreach
• Search the knowledge base semantically for grounded replies

Install

Claude Desktop / Cursor (OAuth — no key needed)

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

The first run opens your browser to sign in to Helpway. Approve, and you're connected — tokens are cached in ~/.helpway and refreshed automatically, so you only log in once. No API key to copy, store, or rotate.

Native remote (clients that speak remote MCP)

If your client supports remote MCP servers directly, skip the bridge and point it at the endpoint — it runs the same OAuth flow natively:

https://api.helpway.ai/mcp

API key (headless tools — CI, scripts)

For non-interactive environments, create a key at https://app.helpway.ai/settings/developers and set HELPWAY_API_KEY:

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

Available tools

whoami, list_conversations, get_conversation, search_conversations, send_message, create_draft, resolve_conversation, assign_conversation, list_contacts, get_contact, search_contacts, list_active_visitors, get_visitor, search_knowledge_base, list_articles, list_inboxes

Environment variables

| Variable | Required | Default | Notes | |---|---|---|---| | HELPWAY_API_KEY | no | — | hw_sk_… for headless mode. Omit to use OAuth. | | HELPWAY_API_URL | no | https://api.helpway.ai | Override for self-hosted or dev | | HELPWAY_LOCAL | no | false | true → targets http://localhost:52500 | | HELPWAY_OAUTH_PORT | no | 8976 | Loopback port for the OAuth redirect | | HELPWAY_DEBUG | no | false | Logs every JSON-RPC call to stderr |

CLI flags: --local (same as HELPWAY_LOCAL=true), --debug.

Cached OAuth credentials live in ~/.helpway/mcp-auth-<host>.json (mode 0600), keyed by API host so prod and local don't collide. Delete the file to force a fresh login.

Local development

Run the API locally, then point the bridge at it:

# terminal 1 — Helpway API
cd apps/api && bun run dev   # serves http://localhost:52500

# terminal 2 — drive the bridge
HELPWAY_API_KEY=hw_sk_… npx @helpway/mcp --local --debug

Claude Desktop config for local testing:

{
	"mcpServers": {
		"helpway-local": {
			"command": "node",
			"args": ["/abs/path/packages/mcp/dist/index.js", "--local"],
			"env": { "HELPWAY_API_KEY": "hw_sk_…", "HELPWAY_DEBUG": "true" }
		}
	}
}

License

MIT