# HappyFox MCP by usefulapi

> HappyFox MCP by usefulapi is an MCP server. Triage HappyFox tickets, contacts and KB articles, run reports, and reply or add private notes. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Website:** https://usefulapi.io/happyfox/
- **Repository:** https://github.com/m190/usefulapi-mcp/tree/HEAD/servers/happyfox
- **MCP Registry name:** io.usefulapi/happyfox
- **Listing updated:** 2026-11-13

## About

Triage HappyFox tickets, contacts and KB articles, run reports, and reply or add private notes.

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http happyfox https://happyfox.usefulapi.io/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://happyfox.usefulapi.io/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "happyfox": {
      "url": "https://happyfox.usefulapi.io/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "happyfox": {
      "type": "http",
      "url": "https://happyfox.usefulapi.io/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "happyfox": {
      "serverUrl": "https://happyfox.usefulapi.io/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "happyfox": {
      "type": "http",
      "url": "https://happyfox.usefulapi.io/mcp"
    }
  }
}
```

## Tools

- `happyfox_list_tickets`: List tickets, newest activity first, with optional filters and HappyFox's search syntax. Paginated (page_info + data). Search `q` examples: `status:"New","In Progress"`, `priority:"High"`, `assignee:none`, `tag:"billing"`, `contact:"jane@example.com"`, `unresponded:true`, `breached:true`, `duedate:overdue`, `created-after:"2026/01/31"`, `last-modified-on-or-after:"2026/09/01"`, `"Custom Field":"va
- `happyfox_get_ticket`: Fetch a ticket with its full conversation: status, priority, category, contact, assignee, custom fields, SLA breaches and every update (messages, private notes, property changes, attachment links that expire in 5 minutes). HappyFox: GET /api/1.1/json/ticket/<ticket_number>/.
- `happyfox_list_contacts`: List contacts (customers), paginated, or search them. Search `q` fields: name, email, phone (digits only, no +), updated_since, created_since — e.g. `name:adam email:adam@example.com` (space-separated, all must match). HappyFox: GET /api/1.1/json/users/.
- `happyfox_get_contact`: Fetch a contact by id or by email address — phones, contact groups, ticket counts and custom fields. HappyFox: GET /api/1.1/json/user/<id or email>/.
- `happyfox_list_contact_groups`: List contact groups (typically customer companies) with their tagged email domains. HappyFox: GET /api/1.1/json/contact_groups/.
- `happyfox_get_contact_group`: Fetch a contact group and its member contacts. HappyFox: GET /api/1.1/json/contact_group/<id>/.
- `happyfox_list_categories`: List ticket categories (queues) with their ids — needed to create a ticket or filter tickets. HappyFox: GET /api/1.1/json/categories/.
- `happyfox_list_staff`: List agents (staff) with their ids, roles, categories and active flag — the `staff` id every reply/note needs, and assignee ids. HappyFox: GET /api/1.1/json/staff/.
- `happyfox_list_statuses`: List ticket statuses with ids and behaviour (pending / completed) — ids used to change a ticket's status. HappyFox: GET /api/1.1/json/statuses/.
- `happyfox_list_priorities`: List ticket priorities with ids — ids used to set a ticket's priority. HappyFox: GET /api/1.1/json/priorities/.
- `happyfox_list_ticket_custom_fields`: List ticket custom fields: id, type, choices (with choice ids), required flags and categories. Use the ids as t-cf-<id>. HappyFox: GET /api/1.1/json/ticket_custom_fields/.
- `happyfox_list_contact_custom_fields`: List contact custom fields: id, type, choices and required flag. Use the ids as c-cf-<id>. HappyFox: GET /api/1.1/json/user_custom_fields/.
- `happyfox_list_reports`: List the saved reports (id, name, description) from the Reports module. HappyFox: GET /api/1.1/json/reports/.
- `happyfox_get_report_summary`: Summary counts for a saved report: ticket, completed, assigned, pending and unassigned counts. HappyFox: GET /api/1.1/json/report/<id>/.
- `happyfox_get_report_tabular_data`: The tabular view of a saved report — one row per ticket (display_id, subject, status, assignee, due date), paginated. HappyFox: GET /api/1.1/json/report/<id>/tabulardata/.
- `happyfox_list_kb_articles`: Export the knowledge base: external (customer-facing) articles by default, or internal (agent-only) articles. HappyFox: GET /api/1.1/json/kb/articles/ or /kb/internal-articles/.
- `happyfox_create_ticket`: Open a new ticket on behalf of a contact (created if the email is new). Needs a category id (a public category), a subject and a message in `text` or `html`. HappyFox: POST /api/1.1/json/tickets/.
- `happyfox_add_staff_reply`: Add an agent reply to a ticket and/or change its status, priority, assignee, due date or tags. The contact is emailed ONLY if update_customer is true (HappyFox default: false). With no message it just updates properties. Moving to a completed status may require the category's compulsory custom fields. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/staff_update/.
- `happyfox_add_private_note`: Add an internal note (never sent to the contact), optionally alerting agents and changing status, priority, assignee, due date or tags. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/staff_pvtnote/.
- `happyfox_update_ticket_tags`: Add and/or remove tags on a ticket without touching anything else. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/update_tags/.
- `happyfox_update_ticket_custom_fields`: Set ticket custom-field values (t-cf-<id>, ids from happyfox_list_ticket_custom_fields). HappyFox: POST /api/1.1/json/ticket/<ticket_number>/update_custom_fields/.
- `happyfox_create_contact`: Create a contact. HappyFox treats this as create-or-edit keyed on email: if the email already exists that contact is updated, and any contact custom field NOT passed is reset — use happyfox_update_contact to edit an existing contact. HappyFox: POST /api/1.1/json/users/.
- `happyfox_update_contact`: Edit an existing contact's name, email or contact custom fields (c-cf-<id>). Phone numbers are edited via happyfox_create_contact with the phone id. HappyFox: POST /api/1.1/json/user/<id>/.

## FAQ

### How do I add HappyFox MCP by usefulapi to Claude Code?

Run this command in your terminal: claude mcp add --transport http happyfox https://happyfox.usefulapi.io/mcp

---
Source: https://ai-powered.com/mcp/happyfox-mcp-by-usefulapi
