HappyFox MCP by usefulapi
Triage HappyFox tickets, contacts and KB articles, run reports, and reply or add private notes.
Should I use this
Quality & Safety
Findings (4)
- LOWin happyfox_list_ticket_custom_fields
- LOWin happyfox_list_contact_custom_fields
- LOWin happyfox_get_report_tabular_data
- LOWin happyfox_update_ticket_custom_fields
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"happyfox": {
"url": "https://happyfox.usefulapi.io/mcp"
}
}
}Remote endpoints
https://happyfox.usefulapi.io/mcpstreamable-httpWhat it can do
Tool inventory
Tools (23)
🟢happyfox_list_tickets(q, status, category, sort, fields, ...)
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:"[email protected]"`, `unresponded:true`, `breached:true`, `duedate:overdue`, `created-after:"2026/01/31"`, `last-modified-on-or-after:"2026/09/01"`, `"Custom Field":"value"`. Separate several filters with a space. HappyFox: GET /api/1.1/json/tickets/.
Input Schema
{
"type": "object",
"properties": {
"q": {
"description": "HappyFox search/filter string (see description).",
"type": "string"
},
"status": {
"description": "`_all` (default), `_pending` (every pending-behaviour status), or a status id from happyfox_list_statuses.",
"type": "string"
},
"category": {
"description": "Only tickets in this category id (happyfox_list_categories).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"sort": {
"description": "Sort key, e.g. created (newest first), createa, updated, due, priorityd.",
"type": "string",
"enum": [
"categorya",
"categoryd",
"subjecta",
"subjectd",
"due",
"statusa",
"statusd",
"prioritya",
"priorityd",
"updated",
"updatea",
"unresponded",
"createa",
"created",
"assigneea",
"assigneed",
"last_modifieda",
"last_modifiedd",
"ticketa",
"ticketd",
"clienta",
"clientd"
]
},
"fields": {
"description": "Comma-separated top-level fields to return, e.g. id,display_id,subject,status — keeps responses small.",
"type": "string"
},
"minify_response": {
"description": "If true, return only ticket ids.",
"type": "boolean"
},
"page": {
"description": "Page number, starting at 1.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"size": {
"description": "Results per page, 1-50 (HappyFox default 10).",
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_get_ticket(ticket_number, show_cf_changes)
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>/.
Input Schema
{
"type": "object",
"properties": {
"ticket_number": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
},
"show_cf_changes": {
"description": "Include the history of custom-field changes in the updates.",
"type": "boolean"
}
},
"required": [
"ticket_number"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_list_contacts(q, page, size)
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:[email protected]` (space-separated, all must match). HappyFox: GET /api/1.1/json/users/.
Input Schema
{
"type": "object",
"properties": {
"q": {
"description": "Search string, `field:value` pairs separated by spaces.",
"type": "string"
},
"page": {
"description": "Page number, starting at 1.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"size": {
"description": "Results per page, 1-50 (HappyFox default 10).",
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_get_contact(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>/.
Input Schema
{
"type": "object",
"properties": {
"contact": {
"type": "string",
"minLength": 1,
"description": "The contact's numeric id (e.g. \"33\") or email address."
}
},
"required": [
"contact"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_list_contact_groups
List contact groups (typically customer companies) with their tagged email domains. HappyFox: GET /api/1.1/json/contact_groups/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_get_contact_group(contact_group_id)
Fetch a contact group and its member contacts. HappyFox: GET /api/1.1/json/contact_group/<id>/.
Input Schema
{
"type": "object",
"properties": {
"contact_group_id": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The contact group id."
}
},
"required": [
"contact_group_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢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/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢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/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢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/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_list_priorities
List ticket priorities with ids — ids used to set a ticket's priority. HappyFox: GET /api/1.1/json/priorities/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢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/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢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/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_list_reports
List the saved reports (id, name, description) from the Reports module. HappyFox: GET /api/1.1/json/reports/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_get_report_summary(report_id)
Summary counts for a saved report: ticket, completed, assigned, pending and unassigned counts. HappyFox: GET /api/1.1/json/report/<id>/.
Input Schema
{
"type": "object",
"properties": {
"report_id": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The report (from happyfox_list_reports) id."
}
},
"required": [
"report_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_get_report_tabular_data(report_id, page, size)
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/.
Input Schema
{
"type": "object",
"properties": {
"report_id": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The report (from happyfox_list_reports) id."
},
"page": {
"description": "Page number, starting at 1.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"size": {
"description": "Results per page, 1-50 (HappyFox default 10).",
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"required": [
"report_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢happyfox_list_kb_articles(internal)
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/.
Input Schema
{
"type": "object",
"properties": {
"internal": {
"description": "true = internal articles; false/omitted = external articles.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_create_ticket(name, email, phone, subject, text, ...)
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/.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Contact name."
},
"email": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"description": "Contact email address."
},
"phone": {
"description": "Contact phone number.",
"type": "string"
},
"subject": {
"type": "string",
"minLength": 1,
"description": "Ticket subject."
},
"text": {
"description": "Message in plain text (text or html is required).",
"type": "string"
},
"html": {
"description": "Message in HTML (text or html is required).",
"type": "string"
},
"category": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The category (happyfox_list_categories; must be public) id."
},
"priority": {
"description": "Priority id (happyfox_list_priorities); defaults to the default priority.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"assignee": {
"description": "Agent id to assign the ticket to (from happyfox_list_staff); null to unassign.",
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"tags": {
"description": "Tags, as a comma-separated string.",
"type": "string"
},
"cc": {
"description": "CC email addresses, as a comma-separated string.",
"type": "string"
},
"bcc": {
"description": "BCC email addresses, as a comma-separated string.",
"type": "string"
},
"due_date": {
"description": "Due date, yyyy-mm-dd or dd/mm/yyyy.",
"type": "string",
"pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\d{2}\\/\\d{2}\\/\\d{4})$"
},
"visible_only_staff": {
"description": "true = private ticket, visible to staff only.",
"type": "boolean"
},
"custom_fields": {
"description": "Custom field values keyed \"t-cf-<id>\" / \"c-cf-<id>\". Ticket (t-cf-) and contact (c-cf-) fields; required ones must be present. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(t\\-cf\\-|c\\-cf\\-)\\d+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
]
}
}
},
"required": [
"name",
"email",
"subject",
"category"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_add_staff_reply(ticket_number, staff, plaintext, html, update_customer, ...)
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/.
Input Schema
{
"type": "object",
"properties": {
"ticket_number": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
},
"staff": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The agent making the reply (happyfox_list_staff) id."
},
"plaintext": {
"description": "Reply in plain text.",
"type": "string"
},
"html": {
"description": "Reply in HTML.",
"type": "string"
},
"update_customer": {
"description": "true = send the reply to the contact by email. Default false.",
"type": "boolean"
},
"subject": {
"description": "Override the subject of the email sent to the contact.",
"type": "string"
},
"cc": {
"description": "CC email addresses, as a comma-separated string.",
"type": "string"
},
"bcc": {
"description": "BCC email addresses, as a comma-separated string.",
"type": "string"
},
"send_survey": {
"description": "true = send the satisfaction survey.",
"type": "boolean"
},
"status": {
"description": "New status id (happyfox_list_statuses).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"priority": {
"description": "New priority id (happyfox_list_priorities).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"assignee": {
"description": "Agent id to assign the ticket to (from happyfox_list_staff); null to unassign.",
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"time_spent": {
"description": "Minutes to add to the ticket's time spent (some categories require it).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"due_date": {
"description": "Due date, yyyy-mm-dd or dd/mm/yyyy.",
"type": "string",
"pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\d{2}\\/\\d{2}\\/\\d{4})$"
},
"tags": {
"description": "Tags to set, as a comma-separated string.",
"type": "string"
},
"custom_fields": {
"description": "Custom field values keyed \"t-cf-<id>\". Ticket fields (ids from happyfox_list_ticket_custom_fields); compulsory-on-completion fields are required when closing. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(t\\-cf\\-)\\d+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
]
}
}
},
"required": [
"ticket_number",
"staff"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_add_private_note(ticket_number, staff, plaintext, html, alert, ...)
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/.
Input Schema
{
"type": "object",
"properties": {
"ticket_number": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
},
"staff": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The agent adding the note (happyfox_list_staff) id."
},
"plaintext": {
"description": "Note in plain text.",
"type": "string"
},
"html": {
"description": "Note in HTML.",
"type": "string"
},
"alert": {
"description": "Send a private alert: `s` = all subscribers, `c` = all agents in the ticket's category, or an agent id.",
"type": "string",
"pattern": "^(s|c|\\d+)$"
},
"status": {
"description": "New status id (happyfox_list_statuses).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"priority": {
"description": "New priority id (happyfox_list_priorities).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"assignee": {
"description": "Agent id to assign the ticket to (from happyfox_list_staff); null to unassign.",
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"time_spent": {
"description": "Minutes to add to the ticket's time spent (some categories require it).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"due_date": {
"description": "Due date, yyyy-mm-dd or dd/mm/yyyy.",
"type": "string",
"pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\d{2}\\/\\d{2}\\/\\d{4})$"
},
"tags": {
"description": "Tags to set, as a comma-separated string.",
"type": "string"
},
"custom_fields": {
"description": "Custom field values keyed \"t-cf-<id>\". Ticket fields (ids from happyfox_list_ticket_custom_fields); compulsory-on-completion fields are required when closing. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(t\\-cf\\-)\\d+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
]
}
}
},
"required": [
"ticket_number",
"staff"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_update_ticket_tags(ticket_number, staff_id, add, remove)
Add and/or remove tags on a ticket without touching anything else. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/update_tags/.
Input Schema
{
"type": "object",
"properties": {
"ticket_number": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
},
"staff_id": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The agent making the change (shown in the ticket history) id."
},
"add": {
"description": "Tags to add, as a comma-separated string.",
"type": "string"
},
"remove": {
"description": "Tags to remove, as a comma-separated string.",
"type": "string"
}
},
"required": [
"ticket_number",
"staff_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_update_ticket_custom_fields(ticket_number, staff, 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/.
Input Schema
{
"type": "object",
"properties": {
"ticket_number": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
},
"staff": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The agent making the change id."
},
"custom_fields": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(t\\-cf\\-)\\d+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
]
},
"description": "Custom field values keyed \"t-cf-<id>\". Ticket fields only. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd."
}
},
"required": [
"ticket_number",
"staff",
"custom_fields"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_create_contact(name, email, phones, custom_fields)
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/.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Contact name."
},
"email": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"description": "Contact email address."
},
"phones": {
"description": "Phone numbers.",
"type": "array",
"items": {
"type": "object",
"properties": {
"number": {
"type": "string",
"minLength": 1,
"description": "The phone number."
},
"type": {
"description": "mo = mobile, w = work, m = main, h = home, o = other (default).",
"type": "string",
"enum": [
"mo",
"w",
"m",
"h",
"o"
]
},
"is_primary": {
"description": "Make this the primary number.",
"type": "boolean"
},
"id": {
"description": "Existing phone id, to edit that number instead of adding one.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"number"
]
}
},
"custom_fields": {
"description": "Custom field values keyed \"c-cf-<id>\". Contact fields (happyfox_list_contact_custom_fields); required ones must be present. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(c\\-cf\\-)\\d+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
]
}
}
},
"required": [
"name",
"email"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴happyfox_update_contact(contact_id, name, email, custom_fields)
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>/.
Input Schema
{
"type": "object",
"properties": {
"contact_id": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The contact id."
},
"name": {
"description": "New name.",
"type": "string",
"minLength": 1
},
"email": {
"description": "New email address.",
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"custom_fields": {
"description": "Custom field values keyed \"c-cf-<id>\". Contact fields. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(c\\-cf\\-)\\d+$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
]
}
}
},
"required": [
"contact_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Community
Evidence