# Understanding the Kustomer MCP Server tools > The Kustomer MCP Server gives connected AI agents and automations access to Kustomer data through a set of purposebuilt tools These tools can search retrieve Source: https://help.kustomer.com/en_us/understanding-the-kustomer-mcp-server-tools-ry1KuLVXMx Last updated: 2026-09-04T21:01:42.928Z The Kustomer MCP Server gives connected AI agents and automations access to Kustomer data through a set of purpose-built tools. These tools can search, retrieve, inspect, and troubleshoot records across conversations, messages, customers, companies, notes, custom objects, workflows, users, teams, and search metadata. Use this guide to understand what each tool does and when to use it. ### In this article * Understanding MCP Server tools * Choosing the right tool * Searching across Kustomer records * Working with conversations * Working with messages * Working with customers * Working with companies * Working with notes * Working with custom objects * Working with workflows * Working with users and teams * Using search utility tools * Testing the MCP Server connection ### Choosing the right tool Choose a tool based on the type of record you need and how specific your query is. The `search` tool is the flexible option when you need advanced query logic (AND/OR/NOT, sorting, pagination) for a **single entity type**. Set `queryContext`to choose which record type to search. Use entity-specific search tools, such as **search-conversations** or **search-customers**, when you already know which record type you need. Use **get-\*-by-id** tools when you already have the record ID and need the full record. Use **get-\*-search-fields** or **get-\*-sort-fields** tools before building complex queries. These tools help confirm which fields and operators are available. Use **ping** to confirm that the MCP Server connection is available before running other tools. ### Searching across Kustomer records Universal search is useful when your query spans multiple Kustomer entity types. Tool What it does Example use case **search** Searches across customers, conversations, messages, notes, custom objects, and companies. Supports flexible AND, OR, and NOT condition logic. A support operations analyst needs to find every conversation tagged `billing-dispute` that also involves a customer in the enterprise segment. ### Working with conversations Conversation tools help you search for support tickets, retrieve a specific conversation, or inspect a conversation’s message thread. Tool What it does Example use case **search-conversations** Searches support tickets and conversations. Results are sorted by most recent update. Supports filters for status, priority, assignment, tags, and channel. A team lead needs a live view of all open, high-priority conversations assigned to Tier 2 before redistributing workload. **get-conversation-by-id** Retrieves full details for one conversation, including status, priority, assignments, SLA data, tags, sentiment, and linked conversations. An agent investigating an escalation needs to confirm why a conversation was marked high priority and who owns it. **get-messages-by-conversation** Retrieves a paginated message thread for a conversation. Supports filtering by channel and direction, and sorting by chronological or most recent order. A QA reviewer needs to read the full email exchange for a complaint in chronological order. Use **search-conversations** when you need to find conversations that match a set of conditions. Use **get-conversation-by-id** when you already have the conversation ID. Use **get-messages-by-conversation** when you need the full message history for a conversation. ### Working with messages Message tools help you retrieve specific messages, search message content and metadata, and inspect available message search fields. Tool What it does Example use case **get-message-by-id** Retrieves the full content, attachments, and delivery metadata for one message. A manager needs to confirm whether an outbound email included the expected attachment. **search-messages** Searches individual messages across all channels. Includes voice call analytics, such as talk time, hold time, and IVR time. An operations manager needs to identify all voice calls longer than 5 minutes from the past week. **get-message-search-fields** Lists searchable fields and supported operators for the message entity. An analyst checks which voice analytics fields are available before writing a search query. **get-message-sort-fields** Lists the fields available for sorting message search results. An analyst building a voice call report confirms whether messages can be sorted by talk time before finalizing the query. Use **search-messages** when the message itself is the target of the search. Use **get-message-by-id** when you need exact message content or delivery details. Use **get-message-search-fields** before building a complex message search. ### Working with customers Customer tools help you search, retrieve, list, and inspect customer records. Tool What it does Example use case **search-customers** Searches customers across more than 50 attributes, including contact information, satisfaction scores, activity dates, and tags. A CS leader needs to find customers with more than 10 conversations and a satisfaction score below 3. **get-customer-by-id** Retrieves a complete customer profile, including contact details, custom attributes, segments, tags, and relationship data. Supports optional field projection. An account manager reviews a customer’s profile before a renewal call. **get-customers** Lists customers with pagination. Supports filtering only by `updatedAt` and sorting only by `updatedAt`. A data engineer pulls all customers updated in the past 24 hours for a nightly CRM sync. **get-customer-search-fields** Lists searchable fields and operators for the customer entity. An admin checks whether satisfaction score fields are available for a saved customer search. **get-customer-sort-fields** Lists fields available for sorting customer search results. A reporting analyst checks which fields can rank customers by conversation count. Use **search-customers** for targeted customer queries. Use **get-customers** for basic browsing or sync jobs based on update time. Use **get-customer-search-fields** and **get-customer-sort-fields** before building advanced customer searches. ### Working with companies Company tools help teams search and retrieve account-level records. Tool What it does Example use case **search-companies** Searches company or account records by name, tags, and metadata. An enterprise account team searches for companies tagged `enterprise` before quarterly business review outreach. **get-company-by-id** Retrieves the full profile for one company, including custom attributes and associated customer relationships. A support lead checks whether other contacts from the same company have open issues. **get-company-search-fields** Lists searchable fields and operators for the company entity. An admin checks which company fields can support filtering by contract tier. **get-company-sort-fields** Lists fields available for sorting company search results. An analyst checks whether companies can be sorted by creation date. Use company tools when you need account-level information instead of individual customer-level information. ### Working with notes Note tools help teams search internal-only notes and annotations. Tool What it does Example use case **search-notes** Searches internal agent notes and annotations. Supports filtering by author, content, and linked conversation or customer. A team lead searches notes containing `escalation` from the past month to audit how agents flag issues internally. Use **search-notes** when the information you need is likely stored in internal comments instead of customer-facing messages. ### Working with custom objects Custom object tools help teams search, list, and inspect custom business objects and their schemas. Tool What it does Example use case **search-kobjects** Searches custom business objects, such as orders, deals, or tickets. Supports revenue attribution and custom klass-specific fields. A revenue operations analyst searches for closed-won deal objects with attributed revenue over `$1,000`. **list-kobjects** Lists paginated instances of a specific custom object type, or klass, by name. A support manager browses all warranty claim objects to review current claim volume. get-kobject Retrieves full details for one custom object instance by its ID, including all field values and relationship data. A developer inspects a specific order object after a workflow fails to process it, to confirm the field values it contained at the time. **get-kobject-search-fields** Lists searchable fields and operators for the kobject entity. Available fields vary by klass. A developer checks which fields exist before searching subscription objects. **get-kobject-sort-fields** Lists fields available for sorting kobject search results. An analyst confirms whether order objects can be sorted by order value. **get-klass** Retrieves the schema or definition for a specific custom object type by ID. Shows the structure and configured fields. A developer inspects a klass definition before integrating the custom object into a workflow. **list-klasses** Lists all custom object schemas configured in the organization. Supports filtering by enabled or disabled status. An admin audits enabled klasses to document which custom object types are active. Use **get-klass** or **list-klasses** when you need to understand the object model before searching custom objects. Use **search-kobjects** when you need to query object instances by field values. Use **list-kobjects** when you need a paginated list of instances for one klass. For more information, see [Data model overview](https://help.kustomer.com/en_us/data-model-overview-SyIS1S3zM) for more details.  ### Working with workflows Workflow tools help admins and developers inspect automation configuration and revision history. Tool What it does Example use case **get-workflows** Lists automation workflows. Supports filters for trigger event, enabled status, and whether the workflow was created manually or by an app. An admin lists enabled workflows triggered by `conversation.create` to troubleshoot unexpected ticket assignment. **get-workflow-by-id** Retrieves the complete configuration of one workflow, including trigger conditions, action steps, and current status. An admin inspects a workflow to see which fields it updates and under which conditions. **get-workflow-revisions** Lists the revision history of a workflow, including who changed it and when. An admin checks whether a recent workflow edit caused an escalation issue. **get-workflow-revision-by-id** Retrieves the full configuration of one historical workflow revision. An admin compares a historical revision with the current live version. **get-workflow-variables** Lists all variables defined for a specific workflow, including their names and configured values. An admin audits a complex routing workflow to confirm which variables are in scope before editing its logic. Use workflow tools when you need to troubleshoot automation behavior or review workflow configuration changes. ### Working with users and teams User and team tools help admins inspect access, memberships, assignments, and team records. Tool What it does Example use case **get-users** Lists organization users with pagination. Supports filters for `deleted`, `pending`, `userType`, `roleGroups`, `orgOwner`, `machine`, `app`. An IT admin audits machine and app-type users with active API access. **get-user-by-id** Retrieves full profile details for one user, including role groups and team memberships. A manager confirms an agent’s role group before granting access to a sensitive workflow. **get-user-teams** Retrieves all teams a user belongs to. Can include role group details. A supervisor checks an agent’s team memberships before reassigning work. **get-current-user** Retrieves identity, permissions, and role information for the currently authenticated API user. An integration developer confirms the connected account’s permissions before attempting write operations. **list-teams** Lists teams in the organization with pagination. Supports filtering by deletion status and role group. An admin lists all active teams before merging underused queues. **get-team-by-external-id** Looks up a team by an external system’s reference ID instead of the Kustomer internal ID. An integration syncs team data from an HR system using the HR system’s team ID. **get-team** Retrieves detailed information about one team by its internal team ID. A workflow administrator resolves a team ID from an assignment field back to a readable team name. Use **get-current-user** early in an integration session to verify identity and permissions. Use **get-user-teams**, **get-team**, and **list-teams** when troubleshooting assignment, routing, or permissions-related behavior. ### Using search utility tools Search utility tools help you discover which fields and sorting options are available before building queries. Tool What it does Example use case **get-search-fields** Discovers searchable fields and supported operators for an entity type, such as customer, conversation, message, note, kobject, or company. A developer checks the exact field name and valid operators for SLA breach status before building a query. **get-sort-fields** Lists fields that support sorting for a given entity type. Includes guidance on ascending and descending syntax. A developer checks whether conversation results can be sorted by SLA due time. **get-conversation-search-fields** Lists searchable fields and operators for the conversation entity. An admin checks the correct assignment field before building a saved view for unassigned conversations. **get-conversation-sort-fields** Lists fields available for sorting conversation search results. Includes common sort pattern examples. A dashboard builder confirms how to sort conversations by priority and creation date. Use search utility tools when you are unsure which fields, operators, or sort options are valid. This is especially useful before building saved searches, dashboards, reporting queries, or integration logic. ### Testing the MCP Server connection Use the diagnostic tool to confirm that the MCP Server connection is available. Tool What it does Example use case **ping** Sends a simple echo or connectivity check. Returns the input text that was sent. A developer sends a ping before running a batch of queries to confirm that the MCP Server is active and responding. Use **ping** before running a series of queries or troubleshooting unexpected tool failures. ### Example workflow: troubleshooting unexpected assignment An admin can use multiple MCP Server tools together to investigate unexpected ticket assignment. To troubleshoot unexpected assignment: 1. Use **search-conversations** to find conversations assigned to the wrong team. 2. Use **get-conversation-by-id** to inspect the conversation’s current assignment, status, priority, tags, and SLA details. 3. Use **get-workflows** to list enabled workflows triggered by conversation events. 4. Use **get-workflow-by-id** to inspect workflow conditions and actions. 5. Use **get-workflow-revisions** to check whether the workflow changed recently. 6. Use **get-team** to resolve team IDs from assignment fields. 7. Use **get-current-user** to confirm that the connected account has the required permissions to inspect the relevant records. ### Example workflow: building a customer risk report A CS or operations team can combine customer and conversation tools to identify accounts that need attention. To build a customer risk report: 1. Use **get-customer-search-fields** to confirm which customer fields are available. 2. Use **search-customers** to find customers with low satisfaction scores or high conversation volume. 3. Use **get-customer-by-id** to inspect a specific customer’s profile, tags, segments, and relationship data. 4. Use **search-conversations** to find recent open or high-priority conversations for those customers. 5. Use **get-messages-by-conversation** to review the message history for selected conversations. ### Example workflow: inspecting custom object data A developer can use custom object tools to understand the organization’s data model and query object records. To inspect custom object data: 1. Use **list-klasses** to see which custom object schemas are enabled. 2. Use **get-klass** to inspect the schema for the relevant klass. 3. Use **get-kobject-search-fields** to confirm searchable fields and supported operators. 4. Use **get-kobject-sort-fields** to confirm available sort fields. 5. Use **search-kobjects** to find matching object records. 6. Use **list-kobjects** to browse object instances for a specific klass. ### Best practices Use the most specific tool available. Entity-specific tools are easier to reason about than broad cross-entity searches. Check available fields before building complex queries. Search fields and sort fields can vary by entity type and custom object schema. Use record ID tools when you need full details for one known record. Use search tools when you need to find matching records across a broader dataset. Use **ping** before running a batch process or when troubleshooting connection issues. Verify permissions with **get-current-user** before attempting actions that depend on the connected account’s access.