Tiflux MCP

🚀 TiFlux MCP Server

Model Context Protocol (MCP) server for TiFlux integration with Claude Code and other AI clients.

Seamlessly connect your AI assistant to TiFlux — manage tickets, clients, chats, desks, appointments, and communications through a single MCP interface.

---

✨ Features

• 🎫 Ticket Management — Get, create, update, close, and list tickets with comprehensive filtering.
• 📊 Stages & SLA History — Inspect the full history of ticket stages with per-stage SLA outcomes.
• 💬 Internal Communications — Create and list internal communications for tickets with file attachments.
• ⏱️ Time Tracking (Appointments) — Create and list work-hour appointments on tickets.
• 🗨️ Chat Management — List inbox/mine/in-attendance/archived chats, fetch chat details, transfer/link chats, send WhatsApp messages, and finish chats.
• 🖥️ Desk Exploration — List available desks and inspect full desk configurations (SLA, fields, behavior) without leaving the chat.
• 🧩 Custom Field Discovery — Discover custom fields (entities) at all three levels — entity → field → option — enabling LLMs to correctly fill checkbox/single_select fields using the right option IDs.
• 🏢 Client CRUD — Full CRUD for clients — get, create, update, list with filters, related desks/technical groups, portal users, and email permissions.
• 📎 File Upload Support — Attach up to 10 files (25MB each) to internal communications.
• 🔌 API Integration — Direct integration with TiFlux API v2.
• ⚙️ Environment Configuration — Secure configuration with environment variables.
• ✅ Comprehensive Testing — Automated tests with 100% mock isolation.

---

📦 Installation

npm install -g @tiflux/mcp

---

🚀 Usage

With Claude Code

Add to your MCP configuration:

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

With Other MCP Clients

npx @tiflux/mcp@latest

Via URL (HTTP Transport)

Endpoint: https://mcp.tiflux.com/mcp

claude mcp add tiflux-lambda --transport http https://mcp.tiflux.com/mcp --header "x-tiflux-api-key:APIKEY" -s project

Manual Configuration

Add to .claude/settings.json or ~/.claude.json:

{
  "mcpServers": {
    "tiflux": {
      "type": "url",
      "url": "https://mcp.tiflux.com/mcp",
      "headers": {
        "x-tiflux-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Endpoints

Endpoint	Method	Auth	Description
/mcp	GET	No	Server info
/mcp	POST	Yes	MCP operations
/health	GET	No	Health check

Via Web (OAuth 2.0) — Claude web & ChatGPT connectors

Use TiFlux as a connector in any AI platform that supports MCP over OAuth 2.0 — such as Claude (claude.ai / desktop) and ChatGPT — with no local install. You just add a custom connector pointing to the TiFlux MCP server URL.

MCP Server URL (paste this in the connector):

https://mcp.tiflux.com

Add the connector:

• Claude (claude.ai / desktop): Settings → Connectors → Add custom connector → paste https://mcp.tiflux.com → Connect.
• ChatGPT: Settings → Connectors (or when building a GPT, Add a connector) → paste https://mcp.tiflux.com → Connect.

How the authorization works:

1. After adding the connector, the platform opens the TiFlux authorization page automatically.
2. The page shows a step-by-step guide to generate your TiFlux API Key:
   • Log in at app.tiflux.com
   • Click your profile photo → Minha conta
   • Open the Sessões tab
   • Under Sessões API, click "Gerar novo token de sessão"
   • Copy the generated key and paste it into the authorization form
3. After authorizing, the platform receives a Bearer token and uses it for all subsequent MCP requests — no need to handle the key again.

💡 For Claude Code or local/script usage with a direct API key header, see Via URL (HTTP Transport) above.

Authentication methods supported:

Method	Header	When to use
API key (direct)	x-tiflux-api-key: YOUR_API_KEY	Claude Code, local SDK, scripts
Bearer token (OAuth)	Authorization: Bearer <token>	Claude.ai, ChatGPT, web connectors

OAuth 2.0 endpoints:

Endpoint	Description
GET /.well-known/oauth-authorization-server	OAuth server metadata (RFC 8414)
POST /register	Dynamic client registration (RFC 7591)
GET /authorize	Authorization page (user enters API key)
POST /authorize	Form submit — issues auth code
POST /token	Token exchange and refresh

---

⚙️ Configuration

Create a .env file with your TiFlux API credentials:

# TiFlux API Configuration
TIFLUX_API_KEY=your_api_key_here

# Default values for ticket creation
TIFLUX_DEFAULT_CLIENT_ID=1
TIFLUX_DEFAULT_DESK_ID=1
TIFLUX_DEFAULT_PRIORITY_ID=1
TIFLUX_DEFAULT_CATALOG_ITEM_ID=1

---

🧰 Available Tools

get_ticket

Retrieve a specific ticket by ID with comprehensive information including status, priority, desk, stage, catalog, responsible, client, audit data, SLA, and URLs.

Parameters:

• ticket_number (string, required): Number of the ticket to retrieve
• show_entities (boolean, optional): Include ALL custom fields linked to the ticket
• include_filled_entity (boolean, optional): Include only custom fields with filled values

Returns:

Comprehensive ticket information including:

• Status (ID, name, open/closed flags)
• Priority (ID, name)
• Desk (ID, internal name, display name, active status)
• Stage (ID, name, first/last stage flags, max time)
• Service Catalog (item ID, item name, area, catalog)
• Responsible (ID, name, email, type, technical group)
• Client (ID, name, social reason, active status)
• Audit (created by ID, origin, created/updated dates)
• SLA (status, expirations, deadlines)
• Additional info (followers, worked hours, reopens, internal/external URLs)

New in v1.4.0: Expanded fields for complete ticket metadata in a single call.

create_ticket

Create a new ticket in TiFlux.

Parameters:

• title (string, required): Ticket title
• description (string, required): Ticket description. Accepts Markdown (bold, lists, headings, code) — the MCP automatically converts it to HTML before sending to the API.
• client_id (number, optional): Client (company) ID
• client_name (string, optional): Client (company) name for automatic search (alternative to client_id). Use only when the user says "client" or "company" explicitly.
• desk_id (number, optional): Desk ID
• desk_name (string, optional): Desk/team name for automatic search (alternative to desk_id). Accepts partial names — e.g. "cansados" resolves to "Dev - Cansados" (see Smart Name Resolution). Prefer this when the user references a name without qualifying the entity.
• priority_id (number, optional): Priority ID
• services_catalogs_item_id (number, optional): Service catalog item ID
• catalog_item_name (string, optional): Catalog item name for automatic search (alternative to services_catalogs_item_id, requires desk_id or desk_name)
• status_id (number, optional): Status ID
• requestor_id (number, optional): Requestor ID (person who opens the ticket, must belong to the selected client). Pass this directly if you already know the ID — skips the auto-resolve lookup.
• requestor_name (string, optional): Requestor name. If provided without requestor_id and without requestor_email, the MCP automatically attempts to resolve this to an existing requestor_id (avoids creating a "ghost" requestor). If multiple matches are found, returns a list to disambiguate. If no match, falls back to the previous behavior (sends name as-is).
• requestor_email (string, optional): Requestor email. When provided, the MCP does not attempt to auto-resolve the name to an ID — the email is an exact enough identifier.
• requestor_telephone (string, optional): Requestor phone
• responsible_id (number, optional): Responsible user ID
• responsible_name (string, optional): Responsible user name for automatic search (alternative to responsible_id)
• followers (string, optional): Comma-separated follower emails
• parent_ticket_number (number, optional): Parent ticket number — the created ticket will be linked as a child of this ticket
• files_base64 (array, optional): Array of base64 encoded files [{content: "base64...", filename: "file.png"}] (max 10 files, 25MB each)

New in v2.4.0: Support for base64 file upload via files_base64. The ticket is sent as multipart/form-data. Note for Server mode (Lambda): files_base64 payloads are subject to the 6MB API Gateway limit.

⚠️ Breaking change (v2.8.0): The files parameter (local paths) was removed. Use the new upload_ticket_files tool to send files via base64, or pass the files directly via files_base64.

update_ticket

Update an existing ticket in TiFlux.

Parameters:

• ticket_id (string, required): ID of the ticket to update
• title (string, optional): New ticket title
• description (string, optional): New ticket description. Accepts Markdown (bold, lists, headings, code) — the MCP automatically converts it to HTML before sending to the API.
• client_id (number, optional): New client ID
• desk_id (number, optional): New desk ID
• desk_name (string, optional): Desk name for automatic search (alternative to desk_id). Accepts partial names — e.g. "cansados" resolves to "Dev - Cansados" (see Smart Name Resolution)
• stage_id (number, optional): Stage/phase ID
• stage_name (string, optional): Stage name for automatic search (alternative to stage_id, requires desk_id or desk_name)
• responsible_id (number, optional): Responsible user ID (use null to unassign)
• responsible_name (string, optional): Responsible user name for automatic search (alternative to responsible_id)
• followers (string, optional): Comma-separated follower emails
• services_catalogs_item_id (number, optional): Catalog item ID for updating desk with specific item
• catalog_item_name (string, optional): Catalog item name for automatic search (alternative to services_catalogs_item_id, requires desk_id or desk_name)

Note: At least one optional field must be provided along with the ticket_id.

update_ticket_entities

Update custom fields (entities) of a ticket in TiFlux. Supports up to 50 fields per request. For checkbox fields with multiple named options, send one item per option with entity_field_option_id. Use list_entity_field_options to discover option IDs.

Parameters:

• ticket_number (string, required): Ticket number to update
• entities (array, required): List of custom fields to update. For multiple-choice checkbox fields, send one item per option.

Entity Object Structure:

• entity_field_id (number, required): Custom field ID (obtained via get_ticket or list_entity_fields)
• value (string, required): Field value. Accepted types:
  • text: string
  • text_area: string
  • currency: float as string (e.g., "150.55")
  • phone: numbers only (e.g., "47999999999")
  • email: string
  • link: URL starting with http/https/ftp
  • date: format YYYY-MM-DD
  • single_select: option ID as string
  • checkbox: boolean as string "true"/"false"
  • Use null to clear non-required fields
• entity_field_option_id (number, optional): Option ID for checkbox multiple-choice fields. Use list_entity_field_options to get IDs. For multiple-choice checkboxes, send one item per option with the same entity_field_id and different entity_field_option_id.
• country_code (string, optional): Country code (for phone fields outside Brazil)

Example — simple text/date fields:

{
  "ticket_number": "123",
  "entities": [
    {
      "entity_field_id": 72,
      "value": "New value"
    },
    {
      "entity_field_id": 73,
      "value": "2025-01-15"
    }
  ]
}

Example — checkbox with multiple named options:

{
  "ticket_number": "12345",
  "entities": [
    { "entity_field_id": 81, "entity_field_option_id": 11, "value": "true" },
    { "entity_field_id": 81, "entity_field_option_id": 12, "value": "false" },
    { "entity_field_id": 81, "entity_field_option_id": 13, "value": "true" }
  ]
}

cancel_ticket

Cancel a specific ticket in TiFlux.

Parameters:

• ticket_number (string, required): Ticket number to be cancelled (e.g., "37", "123")

Example:

{
  "ticket_number": "84429"
}

list_tickets

List tickets with filtering options.

Parameters:

• desk_ids (string, optional): Comma-separated desk IDs (e.g., "1,2,3")
• desk_name (string, optional): Desk/team name for automatic ID resolution. Accepts partial names — e.g. "cansados" resolves to "Dev - Cansados" (see Smart Name Resolution). Prefer this field when the user references a name without qualifying the entity.
• client_ids (string, optional): Comma-separated client (company) IDs (e.g., "1,2,3")
• client_name (string, optional): Client (company) name for automatic search. Use only when the user explicitly says "client", "company", or gives a known corporate name. For a person, prefer requestor_email.
• stage_ids (string, optional): Comma-separated stage IDs (e.g., "1,2,3")
• stage_name (string, optional): Stage name (must be used with desk_name)
• responsible_ids (string, optional): Comma-separated responsible (assigned attendant) user IDs (use when you already have the ID)
• responsible_name (string, optional): Responsible user name for automatic resolution. Works for both admin (via GET /users) and non-admin users (via attendant groups fallback). Use when the user says "assigned to" / "responsible" and gives a name.
• requestor_ids (string, optional): Comma-separated requestor (person who opened the ticket) IDs (e.g., "1,2,3"). Use for filtering by person (not company). Resolve the ID via search_user(type="client").
• requestor_email (string, optional): Email of the requestor (person who opened the ticket). Use when the user references a person or provides an email directly. Avoids a round-trip to resolve the ID.
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Items per page (default: 20, max: 200)
• is_closed (boolean, optional): Include closed tickets (default: false)
• date_type (string, optional): Date type for filtering: "created_at" (creation date, default) or "solved_in_time" (resolution/closing date)
• start_datetime (string, optional): Start date/time filter in ISO 8601 format (e.g., "2024-05-15T00:00:00Z"). Filters tickets with date >= start_datetime
• end_datetime (string, optional): End date/time filter in ISO 8601 format (e.g., "2024-05-15T23:59:59Z"). Filters tickets with date <= end_datetime

Note: At least one filter (desk_ids/desk_name, client_ids/client_name, stage_ids/stage_name, responsible_ids/responsible_name, requestor_ids, or requestor_email) is required.

Example — filter by requestor email:

{
  "requestor_email": "joao@empresa.com",
  "is_closed": false
}

Date Filtering Examples:

// List tickets created in a specific date range (including closed ones)
{
  "desk_name": "Support",
  "date_type": "created_at",
  "start_datetime": "2024-01-01T00:00:00Z",
  "end_datetime": "2024-01-31T23:59:59Z",
  "is_closed": true
}

// List tickets resolved in a specific period
{
  "desk_name": "Support",
  "date_type": "solved_in_time",
  "start_datetime": "2024-01-01T00:00:00Z",
  "end_datetime": "2024-01-31T23:59:59Z",
  "is_closed": true
}

close_ticket

Close a specific ticket in TiFlux.

Parameters:

• ticket_number (string, required): Ticket number to be closed (e.g., "37", "123")

Example:

{
  "ticket_number": "84429"
}

Success Response:

**Ticket #84429 fechado com sucesso!**

**Mensagem:** Ticket 84429 closed successfully

*Ticket fechado via API TiFlux*

create_ticket_answer

Create a new answer (client communication) in a specific ticket.

Parameters:

• ticket_number (string, required): Ticket number where answer will be created
• text (string, required): Answer content that will be sent to the client. Accepts Markdown (bold, lists, headings, code) — the MCP automatically converts it to HTML before sending to the API.
• with_signature (boolean, optional): Include user signature in the answer (default: false)
• files_base64 (array, optional): Array of base64 encoded files [{content: "base64...", filename: "file.pdf"}] (max 10 files, 40MB each)

New in v1.3.0: Support for base64 file upload via files_base64 parameter.

⚠️ Breaking change (v2.8.0): The files parameter (local paths) was removed. Use the new upload_ticket_files tool to send files via base64, or pass the files directly via files_base64.

Example:

{
  "ticket_number": "123",
  "text": "Hello, your issue has been resolved.",
  "with_signature": true,
  "files_base64": [{"content": "JVBERi0x...", "filename": "attachment.pdf"}]
}

search_client

Search for clients by name (shortcut — name-only). Use list_clients for full filters and pagination.

Parameters:

• client_name (string, required): Client name to search (partial match supported)

list_clients

List clients with filters and pagination. Full version of search_client — accepts status, name, and CPF/CNPJ filters.

Parameters:

• active (boolean, optional): Filter by status: true = active only, false = inactive only. Omit for all.
• name (string, optional): Filter by name (partial match)
• social_revenue (string, optional): Filter by CPF/CNPJ
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Results per page (default: 20, max: 200)

Example:

{
  "active": true,
  "name": "Acme",
  "limit": 10
}

get_client

Get full details of a client by ID.

Parameters:

• client_id (number, required): Client ID (obtained via search_client or list_clients)
• show_entities (boolean, optional): Include custom fields (entities) in the response (default: false)

Example:

{
  "client_id": 42,
  "show_entities": true
}

create_client

Create a new client in TiFlux. Only name and social are required; all other fields are optional and only sent if provided.

Parameters:

• name (string, required): Client trade name (nome fantasia)
• social (string, required): Client legal name (razão social)
• social_revenue (string, optional): CPF or CNPJ
• desk_ids (array of numbers, optional): Desk IDs to associate
• add_all_desks (boolean, optional): Associate all desks
• technical_group_ids (array of numbers, optional): Technical group IDs to associate
• status (boolean, optional): Active (true) or inactive (false) — default: true
• max_agents (number, optional): Maximum agents allowed
• email_financial (string, optional): Financial contact email
• anotations (string, optional): Internal notes
• billing_report_type (string, optional): detailed_with_appointment, detailed, synthetic, or "" (empty)

Example:

{
  "name": "Acme Corp",
  "social": "Acme Corporação Ltda",
  "social_revenue": "12.345.678/0001-99",
  "desk_ids": [1, 2]
}

update_client

Update an existing client (partial update — only provided fields are sent).

Parameters:

• client_id (number, required): Client ID to update
• All fields from create_client (all optional)

Example:

{
  "client_id": 42,
  "status": false,
  "email_financial": "novo@empresa.com"
}

update_client_entities

Update custom fields (entities) for a client. Supports up to 50 fields per request. For checkbox fields with multiple options, send one item per option with entity_field_id + entity_field_option_id + value: "true"/"false".

Parameters:

• client_id (number, required): Client ID to update
• entities (array, required): List of custom fields. Each item:
  • entity_field_id (number, required): Custom field ID
  • value (string, required): Field value (or null to clear)
  • entity_field_option_id (number, optional): Option ID for checkbox/single_select
  • country_code (string, optional): Country code for phone fields

Example:

{
  "client_id": 42,
  "entities": [
    { "entity_field_id": 72, "value": "TI" },
    { "entity_field_id": 80, "entity_field_option_id": 12, "value": "true" }
  ]
}

get_client_desks

List desks associated with a client.

Parameters:

• client_id (number, required): Client ID
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Results per page (default: 20, max: 200)

get_client_technical_groups

List technical groups associated with a client.

Parameters:

• client_id (number, required): Client ID
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Results per page (default: 20, max: 200)

create_client_user

Create a portal user for a client. Allows the user to access the client portal.

Parameters:

• client_id (number, required): Client ID to associate the user with
• name (string, required): Full name of the user
• email (string, required): User email — used for portal login
• extension (string, optional): Phone extension
• authorization_flow (boolean, optional): Require authorization for portal access
• telephone (string, optional): Phone number
• country_code (string, optional): Country code for the phone number

Example:

{
  "client_id": 42,
  "name": "João Silva",
  "email": "joao@empresa.com",
  "telephone": "11999999999"
}

add_client_email_permission

Add an authorized domain or email to open tickets on behalf of a client.

Parameters:

• client_id (number, required): Client ID
• address (string, required): Domain (e.g. @empresa.com.br) or specific email authorized to open tickets for this client

Example:

{
  "client_id": 42,
  "address": "@empresa.com.br"
}

search_user

Search for users by name to use as responsible in tickets.

Parameters:

• name (string, required): User name to search (partial match supported, searches in name and email)
• type (string, optional): User type filter (client, attendant, admin)
• active (boolean, optional): Filter active (true) or inactive (false) users
• limit (number, optional): Results per page (default: 20, max: 200)
• offset (number, optional): Page number (default: 1)

Non-admin support (fallback via attendant groups):

If the API key belongs to a non-admin user, GET /users returns 403. In this case, the tool automatically falls back to enumerating attendant groups (GET /technical-groups) and their members (GET /technical-groups/{id}/users), then applies fuzzy matching by name. The result is identical to the admin path — no parameter change needed. A note is added to the output when the fallback was used.

Implementation Note:

For admin users, the TiFlux API does not support name-based filtering in the /users endpoint — the tool fetches up to 200 users and filters client-side. For non-admin users, the tool uses the technical-groups chain and deduplicates users that appear in multiple groups.

Example:

{
  "name": "John",
  "type": "attendant",
  "active": true
}

search_stage

Search for stages of a specific desk to use in ticket updates.

Parameters:

• desk_id (number, optional): Desk ID to search stages
• desk_name (string, optional): Desk name for automatic search (alternative to desk_id). Accepts partial names — e.g. "cansados" resolves to "Dev - Cansados" (see Smart Name Resolution)
• limit (number, optional): Results per page (default: 20, max: 200)
• offset (number, optional): Page number (default: 1)

Note: At least one parameter (desk_id or desk_name) must be provided.

Example:

{
  "desk_name": "Suporte",
  "limit": 20
}

search_catalog_item

Search for service catalog items by free-text term or by name/filter within a specific desk. Use search to explore items by keyword (server-side, matches catalog name, area name, or item name). Use catalog_item_name to locate a specific item by name (client-side, collapses to single detail when exactly 1 match).

Parameters:

• desk_id (number, optional): Desk ID to search catalog items
• desk_name (string, optional): Desk name for automatic search (alternative to desk_id). Accepts partial names — e.g. "cansados" resolves to "Dev - Cansados" (see Smart Name Resolution)
• search (string, optional): Free-text term for server-side search across catalog name, area name, and item name. Partial match, case-insensitive, accent-insensitive. Returns a listing with full hierarchy (catalog → area → item). Combinable with area_id/catalog_id to narrow scope.
• catalog_item_name (string, optional): Catalog item name to search (client-side partial match on item name only). 1 match → detailed view; multiple → error with list. Use search for broader exploration.
• area_id (number, optional): Service area ID to filter results
• catalog_id (number, optional): Service catalog ID to filter results
• limit (number, optional): Results per page (default: 20, max: 200)
• offset (number, optional): Page number (default: 1)

Note: At least one of desk_id or desk_name must be provided, along with at least one of search, catalog_item_name, area_id, or catalog_id.

Example — free-text search (recommended for exploration):

{
  "desk_name": "Support",
  "search": "infra",
  "limit": 10
}

Example — locate a specific item by name:

{
  "desk_name": "Support",
  "catalog_item_name": "Installation",
  "limit": 10
}

---

💬 Internal Communications

create_internal_communication

Create a new internal communication in a ticket.

Parameters:

• ticket_number (string, required): Ticket number where communication will be created
• text (string, required): Communication content. Accepts Markdown (bold, lists, headings, code) — the MCP automatically converts it to HTML before sending to the API.
• files_base64 (array, optional): Array of base64 encoded files [{content: "base64...", filename: "file.pdf"}] (max 10 files, 25MB each)

New in v1.3.0: Support for base64 file upload via files_base64 parameter.

⚠️ Breaking change (v2.8.0): The files parameter (local paths) was removed. Use the new upload_ticket_files tool to send files via base64, or pass the files directly via files_base64.

Example:

{
  "ticket_number": "123",
  "text": "Internal communication content",
  "files_base64": [{"content": "base64...", "filename": "relatorio.pdf"}]
}

list_internal_communications

List internal communications for a ticket.

Parameters:

• ticket_number (string, required): Ticket number to list communications
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Communications per page (default: 20, max: 200)

get_ticket_files

Get all files attached to a specific ticket.

Parameters:

• ticket_number (string, required): Ticket number to retrieve files from

Returns:

List of files with details including:

• File ID, name, content type
• File size (formatted as KB/MB/GB)
• URL for download
• Created date and creator information

Example:

{
  "ticket_number": "123"
}

upload_ticket_files

Upload files to an existing ticket in TiFlux. Files must be provided as base64-encoded content.

Parameters:

• ticket_number (string, required): Ticket number where files will be attached (e.g., "123", "456")
• files_base64 (array, required): Array of base64 encoded files [{content: "base64...", filename: "file.pdf"}] (max 10 files, 25MB each)

Example:

{
  "ticket_number": "123",
  "files_base64": [
    {"content": "base64encodedcontent...", "filename": "relatorio.md"},
    {"content": "base64encodedcontent...", "filename": "screenshot.png"}
  ]
}

Returns: Confirmation with list of uploaded files.

Note: Uploaded text files (.md, .txt, .csv, .json) are sent with the appropriate charset=utf-8 content type, which prevents character encoding issues (mojibake) in the TiFlux portal.

delete_ticket_file

Remove a file attached to a ticket in TiFlux.

Parameters:

• ticket_number (string, required): Ticket number from which the file will be removed (e.g., "123", "456")
• file_id (string, required): ID of the file to remove (obtained via get_ticket_files)

Example:

{
  "ticket_number": "123",
  "file_id": "456"
}

Returns: Confirmation that the file was removed.

get_ticket_stages_slas

List the full history of a ticket as it moved through the desk's stages, with the SLA outcome for each stage. Useful for SLA audits, escalation reviews, and bottleneck analysis.

Parameters:

• ticket_number (string, required): Ticket number (e.g., "123", "456")
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Records per page (default: 20, max: 200)

Returns:

For each stage transition, the formatted output includes:

• Stage name and desk
• Time spent in expedient (HH:MM)
• Whether the SLA was met (✅ Sim / ❌ Não)
• SLA expiration timestamp
• When the ticket entered the stage and who moved it
• When (if) the ticket was attended in this stage and by whom

Empty result: Tickets on desks without an active SLA return an empty list with an explanatory message — this is expected behavior, not an error.

Example:

{
  "ticket_number": "32",
  "offset": 1,
  "limit": 20
}

list_ticket_answers

List answers (communications with the client) of a specific ticket, paginated.

Parameters:

• ticket_number (integer, required): Ticket number to list answers from
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Answers per page (default: 20, max: 200)

Returns:

Each answer includes:

• Author name, date/time, origin (agent, client, etc.)
• File count indicator
• Preview of the content (first 200 characters)
• Pagination info with hint for next page

Example:

{
  "ticket_number": 123,
  "offset": 1,
  "limit": 20
}

get_ticket_answer

Get the full detail of a specific answer from a ticket, including attached files.

Parameters:

• ticket_number (integer, required): Ticket number
• answer_id (integer, required): ID of the answer to retrieve

Returns:

• Full answer content (untruncated), author, date, origin
• Complete list of attached files with name, type, size and download URL

Example:

{
  "ticket_number": 123,
  "answer_id": 501
}

delete_ticket_answer

Remove an answer (client communication) from a ticket in TiFlux.

Parameters:

• ticket_number (string, required): Ticket number from which the answer will be removed (e.g., "123", "456")
• answer_id (string, required): ID of the answer to remove (obtained via list_ticket_answers or get_ticket_answer)

Example:

{
  "ticket_number": "123",
  "answer_id": "501"
}

Returns: Confirmation that the answer was removed.

delete_ticket_answer_file

Remove a file attached to a specific ticket answer in TiFlux.

Parameters:

• answer_id (string, required): ID of the answer from which the file will be removed (obtained via list_ticket_answers or get_ticket_answer)
• file_id (string, required): ID of the file to remove (obtained via get_ticket_answer, field files[].id)

Example:

{
  "answer_id": "501",
  "file_id": "1"
}

Returns: Confirmation that the file was removed.

get_ticket_histories

List the event history (timeline) of a ticket, showing field changes, stage transitions, and other events. Paginated.

Parameters:

• ticket_number (integer, required): Ticket number to retrieve history for
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Events per page (default: 20, max: 200)
• history_of (integer, optional): Filter by ticket area (e.g., 1 = appointments)
• type_id_attr (integer, optional): Filter by attribute type
• operation (integer, optional): Filter by operation type — only valid when history_of=1

Returns:

For each event:

• Action description, user, date/time, event type and operation
• Diff of changed fields with old → new values

Example:

{
  "ticket_number": 123,
  "history_of": 1
}

reopen_ticket

Reopen a closed or canceled ticket. Tickets that have been billed cannot be reopened.

Parameters:

• ticket_number (integer, required): Ticket number to reopen
• disapproval_reason (string, optional): Required when reopening a ticket pending review (disapproval-based reopening)

Business Rules:

• Tickets that have been billed cannot be reopened (API returns 422)
• disapproval_reason is mandatory when reopening a ticket that is pending review/approval

Example:

{
  "ticket_number": 123,
  "disapproval_reason": "The solution did not resolve the issue"
}

get_internal_communication

Get a specific internal communication with full content.

Parameters:

• ticket_number (string, required): Ticket number containing the communication
• communication_id (string, required): ID of the internal communication to retrieve

update_internal_communication

Update the text of an existing internal communication in a ticket. Only the author of the communication can edit it.

Parameters:

• ticket_number (string, required): Ticket number where the communication exists (e.g., "123", "456")
• communication_id (string, required): ID of the internal communication to update (obtained via list_internal_communications or get_internal_communication)
• text (string, required): New content of the internal communication. Accepts Markdown (bold, lists, headings, code) — the MCP automatically converts it to HTML before sending to the API.

Example:

{
  "ticket_number": "123",
  "communication_id": "101",
  "text": "Updated communication content with **important** details."
}

Returns: Confirmation with updated communication content.

Note: The TiFlux API only allows the author of the communication to edit it. A 403 error will be returned if the authenticated user did not create the communication.

delete_internal_communication

Remove an internal communication from a ticket in TiFlux.

Parameters:

• ticket_number (string, required): Ticket number from which the communication will be removed (e.g., "123", "456")
• communication_id (string, required): ID of the internal communication to remove (obtained via list_internal_communications)

Example:

{
  "ticket_number": "123",
  "communication_id": "101"
}

Returns: Confirmation that the internal communication was removed.

---

⏱️ Appointments (Time Tracking)

⚠️ Disclaimer: Creating appointments (create_appointment) is only supported for tickets on desks configured with non-valued appointments. Listing appointments (list_appointments) works for any desk and renders valorization details when available.

create_appointment

Create a new appointment (work-hour record) on a specific ticket. Only works on tickets from desks configured with non-valued appointments.

Parameters:

• ticket_number (string, required): Ticket number where the appointment will be created
• date (string, required): Appointment date in YYYY-MM-DD format. Future dates are not allowed.
• init_time (string, required): Start time in HH:MM format (e.g. "09:00", "14:30")
• end_time (string, required): End time in HH:MM format. Must be greater than or equal to init_time.
• description (string, required): Description of the work performed

Example:

{
  "ticket_number": "123",
  "date": "2025-01-15",
  "init_time": "09:00",
  "end_time": "10:30",
  "description": "Investigation and fix of the reported issue"
}

list_appointments

List appointments (work-hour records) of a specific ticket with optional filters. When available, each appointment card includes valorization details (attendance type, contract or loose service, travel shift, value) and geolocation entries.

Parameters:

• ticket_number (string, required): Ticket number to list appointments from
• user_id (number, optional): Filter by the ID of the user who made the appointment
• start_date (string, optional): Return appointments from this date (YYYY-MM-DD)
• end_date (string, optional): Return appointments up to this date (YYYY-MM-DD)
• offset (number, optional): Page number (default: 1)
• limit (number, optional): Appointments per page (default: 20, max: 200)

Returns:

Each appointment card shows date, time range, attendant, client (when available), and description. When the desk has valorization enabled, the card also includes:

• Attendance type: External (Externo), Remote (Remoto), or Internal (Interno)
• Service type: Loose (Avulso) with loose service name, or Contract with contract name
• Travel shift name and value (when applicable)
• Guarantee and manual-value flags (shown only when true)
• Monetary value formatted as R$ X,XX

When valorization is null (desks configured without valorization), none of the above fields are shown.

Geolocation lines (📍 Localização: lat, lon) are rendered when the API returns locations for the appointment.

Example:

{
  "ticket_number": "123",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "limit": 50
}

---

🗨️ Chats

get_chat

Display details of a specific chat by ID. Returns a card with status, client, responsible, department, origin, rating, and dates.

Parameters:

• id (number, required): Numeric ID of the chat (also accepts numeric string — the handler calls parseInt)

Returns:

Card with all relevant chat fields including:

• Status (archived, canceled, online, waiting for answer)
• Client and requestor names
• Department and responsible attendant
• Origin channel and room
• Linked ticket number
• Assessment rating (1–5) if available
• Last client message (truncated at 150 chars)
• Timestamps (created, updated, assumed)

Example:

{
  "id": 42
}

list_inbox_chats

List inbox chats (unassigned chats) with optional filters for department, client, origin, and pagination.

Parameters:

• offset (number, optional): Page number (default: 1, minimum: 1)
• limit (number, optional): Chats per page (default: 20, max: 200)
• department_id (number, optional): Filter by department ID
• client_id (number, optional): Filter by client ID
• requestor_id (number, optional): Filter by requestor ID — must be greater than 0
• number (number, optional): Filter by WhatsApp contact number — requires WhatsApp license
• origins (string, optional): Comma-separated origin channels: chat, site_widget, campaign, whatsapp, whatsapp_web, gupshup, whatsapp_cloud
• started_by (string, optional): Chat initiator type: Client, Attendant, Campaign, API

Example:

{
  "origins": "whatsapp",
  "limit": 10,
  "offset": 1
}

list_my_chats

List chats assigned to the authenticated user (API key owner) with optional filters and pagination.

Parameters:

• offset (number, optional): Page number (default: 1, minimum: 1)
• limit (number, optional): Chats per page (default: 20, max: 200)
• department_id (number, optional): Filter by department ID
• client_id (number, optional): Filter by client ID
• requestor_id (number, optional): Filter by requestor ID — must be greater than 0
• number (number, optional): Filter by WhatsApp contact number — requires WhatsApp license
• origins (string, optional): Comma-separated origin channels (see list_inbox_chats)
• started_by (string, optional): Chat initiator type (see list_inbox_chats)

Example:

{
  "department_id": 3,
  "limit": 20
}

list_in_attendance_chats

List all chats currently in attendance across the organization with optional filters for responsible, status, and pagination.

Parameters:

• offset (number, optional): Page number (default: 1, minimum: 1)
• limit (number, optional): Chats per page (default: 20, max: 200)
• department_id (number, optional): Filter by department ID
• client_id (number, optional): Filter by client ID
• requestor_id (number, optional): Filter by requestor ID — must be greater than 0
• number (number, optional): Filter by WhatsApp contact number — requires WhatsApp license
• origins (string, optional): Comma-separated origin channels (see list_inbox_chats)
• started_by (string, optional): Chat initiator type (see list_inbox_chats)
• user_id (number, optional): Filter by responsible attendant ID
• status (string, optional): Filter by attendance status: waiting_client, waiting_attendance, triage

Example:

{
  "user_id": 7,
  "status": "triage"
}

list_archived_chats

List archived chats (finished or canceled) with optional filters. Displays the attendance rating and cancellation status.

Parameters:

• offset (number, optional): Page number (default: 1, minimum: 1)
• limit (number, optional): Chats per page (default: 20, max: 200)
• department_id (number, optional): Filter by department ID
• client_id (number, optional): Filter by client ID
• requestor_id (number, optional): Filter by requestor ID — must be greater than 0
• number (number, optional): Filter by WhatsApp contact number — requires WhatsApp license
• origins (string, optional): Comma-separated origin channels (see list_inbox_chats)
• started_by (string, optional): Chat initiator type (see list_inbox_chats)
• canceled (boolean, optional): true = only canceled chats, false = only normally finished, omitted = all archived chats

Example:

{
  "canceled": false,
  "limit": 50
}

update_chat

Update an existing chat: transfer the attendant (user_id), transfer the department (department_id), and/or link the chat to a ticket (ticket_number). Only chats that are not canceled or closed can be updated.

Parameters:

• id (number, required): Chat ID (accepts numeric string — handler runs parseInt)
• user_id (number, optional): Attendant the chat will be transferred to
• user_name (string, optional): Attendant name for automatic lookup (alternative to user_id; user_id takes precedence). Caveat (BL-007): requires an admin API key — GET /users returns 403 for non-admin accounts; in that case use user_id directly.
• department_id (number, optional): Department the chat will be transferred to. No department_name — the v2 API has no department search endpoint.
• ticket_number (number, optional): Ticket number to link to the chat

Note: At least one of user_id / user_name / department_id / ticket_number is required. If none is provided, the tool returns a friendly warning without calling the API.

Example:

{
  "id": 37,
  "user_id": 1,
  "ticket_number": 127
}

Returns: Markdown confirmation with the list of applied changes.

send_message

Send a WhatsApp message, creating the chat on send. Use a free-text message (message) or an HSM template / chat template (template_id), never both together.

⚠️ message is plain text (NOT Markdown/HTML). WhatsApp uses its own markup (asterisk for bold, underscore for italic); HTML would appear literally. Therefore, unlike a ticket description/answer, the content is not converted to HTML.

Parameters:

• number (number, required): Destination phone number. Validated as Brazilian by default; for another country also pass country_code.
• integration_id (number, required): WhatsApp integration ID. Accepted types: gupshup, whatsapp_cloud.
• message (string, optional): Free-text message (plain text). Use message OR template_id.
• template_id (number, optional): HSM / chat template ID. Use parameters/header_parameters for variables.
• country_code (string, optional): ISO 3166-1 alpha-2 country code (e.g. US). Default BR.
• name (string, optional): Requester name.
• department_id (number, optional): Link the created chat to a department.
• ticket_number (number, optional): Link the created chat to a ticket.
• client_id (number, optional): Link the created chat to a client.
• parameters (string[], optional): Values for the HSM body variables (template_id).
• header_parameters (string[], optional): Values for the HSM header variables — whatsapp_cloud only.
• archive (boolean, optional): Default false. true = create and send straight to the finished/archived box.

Note: Besides number + integration_id, at least one of message / template_id is required (validated locally). Success status from the API: 201.

Example (free message):

{
  "number": 5568976728276,
  "integration_id": 1,
  "message": "Olá, tudo bem?"
}

Example (HSM template with parameters):

{
  "number": 5519993017428,
  "integration_id": 1,
  "template_id": 1,
  "parameters": ["Valor 1", "Valor 2"]
}

Returns: Markdown confirmation with the send details (type, number, integration, links).

archive_chat

Finish (close) a chat. The API responds with 202 (Accepted) — the closing may be processed asynchronously; the tool treats 202 as success.

Parameters:

• id (number, required): Chat ID to finish (accepts numeric string — handler runs parseInt)
• services_catalogs_item_id (number, optional): Service catalog item ID. Conditional: required only when the organization is configured to "Usar catálogo de serviços no chat" — otherwise the API returns 422. No catalog_item_name: catalog item search requires a desk_id, which the chat does not provide; pass the ID directly when needed.

Example:

{
  "id": 37,
  "services_catalogs_item_id": 1
}

Returns: Markdown confirmation that the chat was finished (202 Accepted).

---

🖥️ Desk Tools

Explore and inspect desks (service queues) without leaving the chat. Use list_desks to discover available desks, get_desk to inspect full configuration, list_desk_priorities to discover priority IDs before creating tickets, and list_desk_services_catalogs to list service catalog containers linked to a desk.

list_desks

List desks available in the tenant for discovery and exploration. Returns a table with id, name, display name, active status, and appointment type. Use before creating tickets or to explore which desks exist.

Parameters:

• active (boolean, optional): Filter active (true) or inactive (false) desks. Default: true (active only)
• name (string, optional): Server-side filter by name or display_name (case-insensitive exact match)
• limit (number, optional): Results per page (default: 20, max: 200)
• offset (number, optional): Page number (default: 1)

Returns: Markdown table with id, name, display_name, active status and appointment_type.

Example:

{
  "active": true,
  "limit": 50
}

get_desk

Return the complete configuration of a desk (30+ fields) grouped into sections: Identification, Attendance, SLA, Ticket Behavior, and Required Form Fields. Empty or falsy fields are omitted automatically.

Accepts desk_id (direct) or desk_name (fuzzy, uses the same Smart Name Resolution mechanism). If both are provided, desk_id takes precedence.

Parameters:

• desk_id (number, optional): Numeric desk ID. If provided, used directly without name resolution
• desk_name (string, optional): Partial or full desk name — e.g. "cansados" resolves to "Dev - Cansados" (see Smart Name Resolution). Alternative to desk_id

Note: At least one of desk_id or desk_name is required.

Returns: Markdown with sections covering:

• Identification: name, display name, description, active status, internal desk flag, receiving new tickets
• Attendance: appointment type, attendance type, permissions, cancelable tickets, feedback, e-mail settings, desk exchange
• SLA: SLA active flag, SLA goal, can stop SLA, SLA time tracking
• Ticket Behavior: ticket review settings, reopening rules, time limits, billing behavior
• Required Form Fields: required fields, service catalog requirements

Example:

{
  "desk_id": 3
}

Or using fuzzy name resolution:

{
  "desk_name": "cansados"
}

list_desk_priorities

List priorities configured on a TiFlux desk. Use this to discover priority IDs before creating or updating tickets (e.g. "high priority" → priority_id). The priority_name filter is applied client-side with fuzzy matching after fetching records from the API.

Accepts desk_id (direct) or desk_name (fuzzy). If both are provided, desk_id takes precedence.

Parameters:

Parameter	Type	Required	Default	Description
desk_id	number	one of	—	Numeric desk ID. Used directly, no name lookup
desk_name	string	one of	—	Partial or exact desk name (fuzzy resolved). Alternative to desk_id
priority_name	string	no	—	Optional fuzzy filter on priority name (client-side). E.g. "alta"
limit	number	no	20	Results per page (max: 200)
offset	number	no	1	Page number

Returns: Markdown table with id, name, order, start_time, end_time.

Example — list all priorities by desk_id:

{
  "desk_id": 3
}

Example — filter by priority name using desk_name:

{
  "desk_name": "suporte",
  "priority_name": "alta"
}

Example response:

| ID | Nome | Ordem | Inicio | Fim |
|---|---|---|---|---|
| 17 | High | 1 | 04:00 | 24:00 |
| 18 | Low | 2 | 10:00 | 48:00 |

list_desk_services_catalogs

List service catalogs linked to a TiFlux desk. Catalogs are the parent containers — different from catalog items (use search_catalog_item for items selectable on tickets). The catalog_name filter is applied client-side with fuzzy matching.

Accepts desk_id (direct) or desk_name (fuzzy). If both are provided, desk_id takes precedence.

Parameters:

Parameter	Type	Required	Default	Description
desk_id	number	one of	—	Numeric desk ID. Used directly, no name lookup
desk_name	string	one of	—	Partial or exact desk name (fuzzy resolved). Alternative to desk_id
catalog_name	string	no	—	Optional fuzzy filter on catalog name (client-side). E.g. "infra"
limit	number	no	20	Results per page (max: 200)
offset	number	no	1	Page number

Returns: Markdown table with id, name.

Example — list all catalogs:

{
  "desk_name": "suporte"
}

Example — filter by catalog name:

{
  "desk_id": 3,
  "catalog_name": "infra"
}

Example response:

| ID | Nome |
|---|---|
| 6 | Catalogo 1 |
| 7 | Catalogo 2 |

list_entities

List custom field groups (entities) available in the TiFlux organization. Use to discover which custom field groups exist, which applications they apply to (ticket, client, etc.), and their IDs — required for list_entity_fields.

Parameters:

Parameter	Type	Required	Default	Description
active	boolean	no	—	Filter active (true) or inactive (false) entities
applied_in	string	no	—	Filter by application: "ticket", "client", "solicitant", "services_catalog", "services_catalogs_area", "services_catalogs_item", "equipment"
name	string	no	—	Filter by entity name (partial match)
limit	number	no	20	Results per page (max: 200)
offset	number	no	1	Page number

Returns: Markdown table with id, name, applied_in, active.

Example:

{
  "applied_in": "ticket"
}

Example response:

| ID | Nome | Applied In | Ativa |
|---|---|---|---|
| 10 | Classificação do Chamado | ticket | Sim |
| 11 | Dados do Atendimento | ticket | Sim |

list_entity_fields

List subfields (entity_fields) of a custom field group in TiFlux. Returns name, type, required status, and indicates which fields have selectable options (single_select/checkbox) — use list_entity_field_options in those cases.

Parameters:

Parameter	Type	Required	Default	Description
entity_id	number	yes	—	ID of the custom field group (entity). Obtain via list_entities
field_type	string	no	—	Filter by type: "text", "text_area", "currency", "phone", "email", "link", "date", "single_select", "checkbox"
required	boolean	no	—	Filter required (true) or optional (false) fields
name	string	no	—	Filter by field name
limit	number	no	20	Results per page (max: 200)
offset	number	no	1	Page number

Returns: Markdown table with id, name, field_type, required, and options hint for single_select/checkbox fields.

Example:

{
  "entity_id": 10,
  "field_type": "checkbox"
}

Example response:

| ID | Nome | Tipo | Obrigatorio | Opcoes |
|---|---|---|---|---|
| 81 | Categoria do Impacto | checkbox | Nao | Sim (use list_entity_field_options) |

list_entity_field_options

List options of a custom subfield (entity_field) of type single_select or checkbox. Use to get option IDs (entity_field_option_id) required when filling multiple-choice fields via update_ticket_entities.

Parameters:

Parameter	Type	Required	Default	Description
entity_field_id	number	yes	—	ID of the subfield (entity_field). Obtain via list_entity_fields
value	string	no	—	Filter options by value/text (partial match)
limit	number	no	20	Results per page (max: 200)
offset	number	no	1	Page number

Returns: Markdown table with option id, value, null_option.

Example:

{
  "entity_field_id": 81
}

Example response:

| ID | Valor | Opcao nula |
|---|---|---|
| 11 | Hardware | Nao |
| 12 | Software | Nao |
| 13 | Rede | Nao |
| 14 | (nenhuma) | Sim |

---

🔍 Search Heuristics — Desk-First

When a user references a name without explicitly qualifying the entity type, the following priority applies:

| User input | Filter to use |