MCP Server
HelpYap ships a hosted Model Context Protocol server, so you can connect Claude (or any MCP client) directly to your project. Ask your assistant to review customer conversations, rewrite your bot's prompting, update knowledge base articles, or pull support analytics, all without opening the dashboard.
Endpoint
The server uses the Streamable HTTP transport and authenticates with a HelpYap API key:
https://app.helpyap.com/api/mcp
Authorization: Bearer hy_live_...Create a key under Dashboard → API access. The scopes you select decide which tools the assistant can see and call, so a read-only key is a safe default: add write scopes only when you want the assistant to make changes.
The server is stateless: there are no sessions and nothing is remembered between calls. Every request carries the key, and every tool call names the project it acts on. That is what lets one endpoint serve every user and every project.
Two kinds of key
| Key | Reaches | Use it when |
|---|---|---|
| Personal key | Every project you are a member of, now and in the future. Write access follows your role in each project (members keep conversation, customer, issue, knowledge, and survey writes; owners and admins keep everything the key grants). | You connect Claude for yourself and work across several projects. Each teammate creates their own, so actions are audited under their name. |
| Project key | One project, with exactly the scopes it was created with. Owners and admins create them. | A shared automation or integration that should only ever see one project. |
Picking a project per call
With a personal key, every project-scoped tool accepts a project_id argument (the project id or slug). Call list_projects to see your options; if you belong to a single project the argument is optional. Project keys ignore it (or reject a different project). Assistants handle this themselves: ask "show me open conversations in Acme" and Claude will look up the project and pass it along.
The REST API accepts the same personal keys: send X-HelpYap-Project: <id or slug> (or ?project=) to pick the project.
Connect a client
Claude Code
claude mcp add --transport http helpyap https://app.helpyap.com/api/mcp \
--header "Authorization: Bearer hy_live_..."Claude Desktop and claude.ai
Add a custom connector in Settings → Connectors with the URL https://app.helpyap.com/api/mcp and your API key as a Bearer authorization header.
Other MCP clients (Cursor, Windsurf, etc.)
{
"mcpServers": {
"helpyap": {
"url": "https://app.helpyap.com/api/mcp",
"headers": {
"Authorization": "Bearer hy_live_..."
}
}
}
}Tools
Every tool except list_projects acts on one project: the key's own project for project keys, or the project_id you pass for personal keys. A tool only appears to the assistant when the key holds its required scope.
| Tool | Required scope | Description |
|---|---|---|
| list_projects | (none) | List the projects this key can act on, with the id and slug to pass as project_id |
| list_conversations | conversations:read | List recent conversations, optionally filtered by status |
| get_conversation | conversations:read | Read a conversation with its full message history |
| reply_to_conversation | conversations:write | Send a human reply to the customer (widget, email, SMS, WhatsApp, Messenger) |
| update_conversation | conversations:write | Change status, set tags, or leave an internal note |
| get_bot_config | config:read | Read the AI agent configuration: prompting, messages, model settings |
| update_bot_config | config:write | Update prompting: custom AI instructions, welcome message, blocked topics, temperature, and more |
| get_system_prompt | config:read | Preview the fully compiled system prompt the AI agent runs with |
| list_kb_documents | knowledge:read | List knowledge base documents |
| get_kb_document | knowledge:read | Read the full content of a document |
| create_kb_document | knowledge:write | Add a new document (embeddings generated automatically) |
| update_kb_document | knowledge:write | Edit a document's title or content |
| delete_kb_document | knowledge:write | Permanently delete a document |
| get_support_summary | reports:read | Support analytics: volume, resolution and escalation rates, breakdowns |
| list_help_center_collections | knowledge:read | List help center collections |
| create_help_center_collection | knowledge:write | Create a help center collection |
| update_help_center_collection | knowledge:write | Update a collection's title, slug, order, or published state |
| list_help_center_articles | knowledge:read | List help center articles across all statuses |
| get_help_center_article | knowledge:read | Read an article's full content |
| create_help_center_article | knowledge:write | Write a new help center article (draft or published) |
| update_help_center_article | knowledge:write | Edit, publish, or archive an article |
| list_announcements | outreach:read | List banners, release notes, and news announcements |
| create_announcement | outreach:write | Create an announcement, optionally scheduled with a CTA |
| update_announcement | outreach:write | Edit, publish, schedule, or archive an announcement |
| list_guides | outreach:read | List engagement guides (checklists, tours, tooltips, modals) |
| create_guide | outreach:write | Create an engagement guide with steps |
| update_guide | outreach:write | Edit a guide or change its status |
| list_canned_responses | conversations:read | List reply templates |
| create_canned_response | conversations:write | Create a reply template with a shortcut |
| update_canned_response | conversations:write | Edit a reply template |
| delete_canned_response | conversations:write | Delete a reply template |
| list_survey_responses | surveys:read | Read feedback survey responses with search and filters |
| list_roadmap_items | roadmap:read | List roadmap / feature request items with votes |
| create_roadmap_item | roadmap:write | Add a roadmap item |
| update_roadmap_item | roadmap:write | Update roadmap status, priority, or published state |
What to ask your assistant
- "Which projects can you see? For each one, summarize this week's escalations."
- "Read my last 20 support conversations and tell me the three most common complaints."
- "Customers keep asking about refunds and the bot answers badly. Rewrite the custom prompt so it handles refunds correctly, then add a refund policy article to the knowledge base."
- "Which conversations escalated this week, and why? Reply to any that are still waiting."
- "Pull the last 30 days of support metrics and summarize how the AI agent is performing."
Security notes
- Keys are hashed at rest and shown only once at creation. Revoke a key at any time from the dashboard.
- Every write action (replies, config changes, knowledge base edits) is recorded in the project audit log. Personal keys are attributed to the user who owns them, project keys to the key itself.
- Personal keys re-check your project memberships and role on every call. Leave a project and the key stops reaching it immediately; nothing is cached server-side.
- Theme, channel credentials, and billing settings are never readable or writable through MCP.