Defining MCP Tools allows you to connect real-time data or operational capabilities from your external systems (such as order systems, CRM, ERP, membership platforms, etc.) to 3Chat Agent. These capabilities can drive 3Chat to execute the “Intelligent Marketing SOP” in the pre-sales phase—proactively guiding data collection and conversion; and in the post-sales phase, act as a “business expert”—precisely executing refund, rescheduling, points distribution, and other operations to comprehensively improve customer retention and repurchase rates.
Getting Started Recommendation:
In traditional customer service scenarios, customer service or sales teams are often asked to assist with complex customer issues, such as:
-
“Where is my order now?”
-
“Can you help me change my delivery address?”
-
“I have 500 points, what can I exchange them for?”
-
“Help me cancel tomorrow’s appointment”
These questions often require calling external system data or triggering business operations. Simple Q&A bots cannot respond to these high-requirement questions based solely on the knowledge base. After handover to human agents, the agents often need to query multiple platforms to resolve a customer’s inquiry, which is time-consuming and labor-intensive.
To address these challenges, by integrating custom MCP tools, 3Chat Agent can fully understand customer needs and automatically complete these tasks without human intervention.
Navigation Guidance
Log in to the 3Chat backend, and you can configure MCP tools through the following path:
3Chat Agent → MCP → Tool Invocation
Quick Operation Guide
Pre-requisite Tasks
1.Think about which business operations you want 3Chat Agent to assist customers with and which external data it needs to access (OpenApi).
2.Ensure the performance of the external OpenApi that 3Chat Agent will use. The default timeout is 60 seconds. If this time is exceeded, 3Chat Agent will consider the request as timed out.
3.To ensure 3Chat Agent can securely and reliably call the external OpenApi, you need to log in to the corresponding external system and obtain valid access authorization. For specific operations, refer to: Create External System Authentication (Token).
Configuring Custom MCP Tools
For example, to obtain order logistics information from Shopify:
Navigate to [3Chat Agent] → [MCP] → [Tool Invocation] to enter the tool invocation page. In the upper-right corner of the tool list, click Add Operation to enter the tool configuration page.
Step 1: Fill in Basic Tool Information
Define the tool’s name and provide a description of the tool, explaining its function and when 3Chat Agent should use it.
Example:
getOrderDetail
This tool fetches detailed information about customer orders. It provides all the details of the customer’s orders, including order status, shipping status, purchased items, delivery address, etc.
Tool Description Suggestions - Be clear.
Clearly explain when to use this tool and the detailed information it should provide.
- Recommended example: Use this tool to get detailed information about a customer’s order. The information retrieved can help troubleshoot order-related issues. The tool will provide all order details, including order status, purchased items, delivery address, logistics tracking information, or other related order data.
- Not recommended example: Use this data connector to get order information.
Tool Description Suggestions - Avoid pronouns.
Avoid using pronouns such as “we” or “they”. Use specific proper nouns, such as the company name or the name of the external platform.
- Recommended example: Use this tool to get all order information from the customer’s Shopify store in 3Chat.
- Not recommended example: Use this tool to get orders from our store.
Tool Description Suggestions - Be specific about the scenario.
Describe the specific scenario in which the tool should be used.
- Recommended example: Use this tool to check unresolved issues, such as whether the customer wants to know the status of an issue or whether the system can restore its functionality after resolution.
- Not recommended example: Use this tool to check unresolved issues.
Tool Description Suggestions - Include common phrases used by customers.
Refer to common phrases customers have used in past conversations and include them in the description along with relevant keywords and phrases.
Step 2: Configure Request Information
Fill in your external system’s API endpoint. To ensure data security, we require the use of HTTPS endpoints. Choose the appropriate tool execution method. Currently, GET, POST, PUT, and DELETE are supported.
Example URL:
https://3chat-ai-demo.myshopify.com/admin/api/2025-07/graphql.json
-
Based on the requirements of the HTTPS endpoint you entered, select an already filled authentication authorization. The selected authorization token will be automatically added as the Authentication parameter in the headers.
-
Define the data that 3Chat Agent needs to collect before using the tool. All parameters defined here must be used in the HTTPS request URL or body, with the syntax “{{data_name}}”. Among them:
-
Data with incomplete parameter names, data types, and parameter descriptions will be marked as “Not Defined” in the status column, prompting you to complete the fields.
-
Data with all three parameters defined but not used in the request URL or body will be marked as “Not Used” in the status column, prompting you to use this parameter.
-
-
Once all data statuses are marked as “Used” and the request body’s JSON format is valid, the next operation will be allowed.
-
If the tool does not need to collect any data before being used by 3Chat Agent, you can skip defining collection parameters.
email, string, customer email
Here’s the translation of the provided content:
- Add the necessary request header parameters. If the HTTPS request requires authentication (excluding the “Authentication” header), other required parameters can be included in the request header.
The token below is for testing purposes only and may expire at any time. It is recommended to generate your own token.
Content-Type: application/json
X-Shopify-Access-Token: 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
Here’s the translation of the provided content:
- Write in JSON format. In the request body, each parameter can have a defined value for the HTTPS request. It supports specifying pre-defined collection parameters, with default values being the main data standard fields of 3Chat and custom characters, such as “Contact Person,” etc.
{
“query”: “query OrdersByEmail($q: String!) { orders(first: 50, query: $q, sortKey: CREATED_AT, reverse: true) { edges { node { id name createdAt email displayFulfillmentStatus fulfillments(first: 10) { id status displayStatus createdAt inTransitAt deliveredAt trackingInfo { company number url } } } } pageInfo { hasNextPage endCursor } } }”,
“variables”: {
“q”: “email:‘{{email}}’”
}
}
-
When the following two conditions are met, you can perform the next operation: Test request
-
The collection parameters that are not specified or the defined collection parameters have all been used.
-
The request body is in JSON format.
-
Step 3: Response Testing
Response testing helps verify if the request configuration is correct. It provides two modes:
-
Real-time response: Suitable for existing mature HTTPS interfaces, getting real response structures from actual API requests.
-
Sample response: Suitable for development interfaces, allowing for tool configuration and synchronization testing with the interface.
Here’s the translation of the provided content:
3.1 Real-time Application Method
If the request body or HTTPS request URL specifies a collection parameter or the primary data quantity of the collection parameter, it is necessary to perform the interface test operation after the specified parameter is provided. After completing the request parameters, click the “Test Interface” operation to get the interface response structure.
Note: The test will execute the actual interface and request data from the interface you specified, but it will not affect your actual business data.
Example parameters:
email: zhang.zhiyu@xinheyun.com
Here’s the translation of the provided content:
Returned Value:
{
"data": {
"orders": {
"edges": [
{
"node": {
"id": "gid://shopify/Order/10194884526372",
"name": "#1001",
"createdAt": "2025-09-24T03:45:45Z",
"email": "zhang.zhiyu@xinheyun.com",
"displayFulfillmentStatus": "PARTIALLY_FULFILLED",
"fulfillments": [
{
"id": "gid://shopify/Fulfillment/5867516100900",
"status": "SUCCESS",
"displayStatus": "FULFILLED",
"createdAt": "2025-09-24T05:54:15Z",
"inTransitAt": null,
"deliveredAt": null,
"trackingInfo": [
{
"company": "SF Express",
"number": "SF3237923216655",
"url": "https://www.sf-express.com/we/ow/chn/en/waybill/waybill-detail/SF3237923216655"
}
]
},
{
"id": "gid://shopify/Fulfillment/5867458003236",
"status": "CANCELLED",
"displayStatus": "CANCELED",
"createdAt": "2025-09-24T04:23:45Z",
"inTransitAt": null,
"deliveredAt": null,
"trackingInfo": [
{
"company": "SF Express",
"number": "SF0288599313823",
"url": "https://www.sf-express.com/we/ow/chn/en/waybill/waybill-detail/SF0288599313823"
}
]
},
{
"id": "gid://shopify/Fulfillment/5867455840548",
"status": "CANCELLED",
"displayStatus": "CANCELED",
"createdAt": "2025-09-24T04:19:06Z",
"inTransitAt": null,
"deliveredAt": null,
"trackingInfo": [
{
"company": "Amazon Logistics",
"number": "188888111",
"url": "https://track.amazon.com/tracking/188888111"
}
]
}
]
}
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "eyJsYXN0X2lkIjoxMDE5NDg4NDUyNjM3MiwibGFzdF92YWx1ZSI6MTc1ODY4NTU0NTAwMH0="
}
}
},
"extensions": {
"cost": {
"requestedQueryCost": 23,
"actualQueryCost": 5,
"throttleStatus": {
"maximumAvailable": 2000,
"currentlyAvailable": 1995,
"restoreRate": 100
}
}
}
}
3.2 Example Response Mode
You can directly fill in the response body’s JSON structure. Please ensure the syntax is correct.
When the JSON format syntax in the response example is correct, you can proceed to the next step: Response Data Mapping Translation.
Step 4: Response Data Mapping
This step configures the parameter mapping in the response structure and the accessibility of these parameters for 3Chat Agent.
1.After completing the interface test or manually entering the response structure, the system will automatically extract all response parameters and create a parameter list.
2. According to the configuration transformation rules for the requested parameters:
At the end of the data row, click “Edit” to enter the configuration window.
Example 1: trackingInfo.company
Example 2: trackingInfo.number
Here’s the translation of the provided content:
-
Response Parameter Name: The name of the response parameter (Key), retains the original layer in the JSON structure.
-
Example Response: The response parameters are retrieved from the body of the response.
-
Response Parameters: 3Chat Agent’s available parameters, the default value is the parameter name from the original response body.
-
Data Type: The data type that 3Chat Agent can handle, the default is the original data type from the response body. The type can be transformed based on the specified parameter type.
-
Accessible: Identifies if the 3Chat Agent can access these response parameters.
3. The result after modifying the mapping is displayed as shown below.
-
(Before Mapping)
-
(After Mapping)
Recommendation for Configuration Parameter Transformation
-
Recommendation:
When the response parameter’s name cannot realistically represent the required meaning, you can modify it to make it more business-friendly.
For example, instead of “abc” use “O-250823-001” to represent an order number, and suggest using “orderCode” as the response parameter name. -
Response Parameter Value Conversion (String)
When the response parameter’s value is represented by a number or an inappropriate string, 3Chat Agent cannot measure the status described by the number or string. For example, for an order status like “orderStatus”: 5, you need to specify 5 as “Shipped”. If the orderStatus is “SHIP”, you need to specify “SHIP” as “Shipped”. -
Response Parameter with Time Representation
When the response parameter is represented by a specific time, 3Chat Agent cannot read the time directly in the original format. You need to specify the time type as Datetime, and then convert the time to UTC.
Save and Run the Tool
After completing the configuration, click Save Data and Run this Tool. The 3Chat Agent will be able to use this tool to handle customer inquiries in the production environment.
When this tool is no longer needed to be accessed by the 3Chat Agent, you can pause or stop the tool.
Making 3Chat Agent Execute Tool Calls in AI Tasks
By integrating the MCP (Model Context Protocol) standard, 3Chat Agent can flexibly call the tools that have been created and are running. All you need to do is use the AI Tasks feature, clearly telling 3Chat Agent when to “reach out” and what actions to take.
In the execution steps of an AI Task, you need to describe the business process rules and provide two pieces of information to 3Chat Agent:
- Condition (When something needs to be done):
When the user inquires about the order shipment status.
- Action (Which MCP tool should be used):
If the user input or the context contains an email → call {{tool.update.visitor.email}} to record the email.
If not, politely ask, "What is your email? It will help me check the order status."
If {{var.visitor.email}} is not empty, call the tool getOrderDetail. From the returned values, find the 'logistics company' and 'tracking number,' and return this to the user.
We name this task as “Return Order Logistics Information”.
Result Feedback
-
When the user inquires about the order shipment status, the AI task is triggered, and “Return order logistics information” is sent.
-
The AI task could not identify the email, so it prompts the user to provide their email.
-
After the user replies with the email, the Agent calls the MCP tool and successfully returns the logistics information.