markdown
Defining an MCP tool allows you to connect real-time data or operational capabilities from your external enterprise systems (such as order systems, CRM, ERP, membership platforms, etc.) to the 3Chat Agent. These capabilities enable 3Chat to execute an “intelligent marketing SOP” proactively in the pre-sales phase—guiding lead collection and conversions—and to act as a “business expert” in the post-sales phase—accurately performing operations such as refunds, rescheduling, and points issuance—significantly improving customer retention and repurchase rates.
Getting Started Tips
In traditional customer service scenarios, support or sales teams are often asked to help solve complex customer problems, for example:
- “Where is my order right now?”
- “Can you help me change the delivery address?”
- “I have 500 points. What can I redeem?”
- “Please cancel tomorrow’s appointment for me.”
These questions often require calling external system data or triggering business operations. A simple Q&A bot cannot answer highly time-sensitive questions using only the knowledge base. After escalating to a human, the agent still needs to check multiple platforms to handle a single inquiry—time-consuming and inefficient.
To address this, by integrating a custom MCP tool, the 3Chat Agent can fully understand user needs and automatically complete these actions—no human intervention required.
Navigation
After logging into the 3Chat console, configure MCP tools via: 3Chat Agent > MCP > Tool Invocation.
Quick Operation Guide
Prerequisites
- Decide which business operations and which external data (OpenAPI) you want the 3Chat Agent to access to assist customers.
- Ensure the execution performance of the external OpenAPI provided to the 3Chat Agent. The default timeout is 60 seconds. If exceeded, the 3Chat Agent will treat the request as timed out.
- To ensure secure and trustworthy calls to external OpenAPI, log into the corresponding external system and obtain valid access credentials. See: 创建外部系统的认证授权（Token） .
Configure a Custom MCP Tool
Example: Fetching order logistics information from Shopify
First, follow the navigation: [3Chat Agent] → [MCP] → [Tool Invocation] to open the Tool Invocation page. Click Add in the upper-right corner of the tool list to enter the tool configuration page.
Step 1: Fill in the Tool’s Basic Information
You need to define the tool name and provide a description explaining what the tool does and when the 3Chat Agent should use it.
getOrderDetail
Use this tool to retrieve detailed information about a customer’s orders. The tool provides details for all of the customer’s orders, including order status, fulfillment status, purchased items, shipping address, and more.
Recommendation — Be Clear in the Tool Description
Clearly state when to use the tool and what detailed information it should provide.
- Recommended example: Use this tool to get detailed customer order information. The returned data helps diagnose order-related issues. The tool provides all order details such as order status, purchased items, shipping address, tracking info, or other related data.
- Not recommended: Use this data connector to get order information.
Recommendation — Avoid Pronouns
Avoid pronouns like “we” or “they.” Replace them with explicit proper nouns (e.g., company name, external platform name).
- Recommended example: Use this tool to get all orders for the customer in the Shopify store 3Chat.
- Not recommended: Use this tool to get orders from our store.
Recommendation — Make Scenarios Concrete
Describe concrete usage scenarios.
- Recommended example: Use this tool to query unresolved issues—e.g., when the customer wants to know the handling status prior to resolution, whether it has been resolved, and whether performance can be restored after handling.
- Not recommended: Use this tool to query unresolved issues.
Recommendation — Include Customers’ Common Phrases
Refer to how customers typically phrase problems in past conversations and include their common keywords and phrases in the description.
Step 2: Configure Request Information
- Enter your external system’s API endpoint. For data security, HTTPS is mandatory. Select the correct HTTP method. Currently supported: GET, POST, PUT, DELETE.
[https://3chat-ai-demo.myshopify.com/admin/api/2025-07/graphql.json](https://3chat-ai-demo.myshopify.com/admin/api/2025-07/graphql.json)
- Select an authentication credential according to the HTTPS endpoint requirements. The chosen auth token will, by default, be added to Headers with the parameter name Authentication.
- Define the data the 3Chat Agent must collect before using the tool. All defined parameters must be used in the HTTPS URL or request body with the syntax
"{{data_name}}". Specifically:- Data missing parameter name, data type, or description will show “Undefined” in the Status column—prompting you to complete it.
- Data with all three attributes completed but unused in URL/body will show “Unused”—prompting you to use it.
- Only when all data statuses are “Used” and the request body is valid JSON can you proceed to the next step.
- If the tool requires no collected parameters, you may omit parameter definitions.
email, string, customer email
- Add necessary request headers. If the external API requires an auth token header name other than “Authentication”, specify it here.
The following token is for testing only and may expire at any time; please generate your own token.
Content-Type:application/json
X-Shopify-Access-Token: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
- Provide a JSON-formatted request body. In the body, assign values for each API parameter. You can reference collected parameters, default values, or 3Chat’s master data standard fields and custom fields (e.g., “Contact”).
{
"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}}'"
}
}
- You can proceed to Response Test when BOTH are satisfied:
- No collected parameters are required, or all required parameters are Used
- The request body is valid JSON
Step 3: Response Test
Response testing helps you verify whether the request configuration is correct. Two modes are available:
Mode 1: Live Response. For existing, stable HTTPS APIs—fetch the real response by making an actual request.
Mode 2: Sample Response. For APIs under development—complete the tool configuration first, then validate with a mock response.
3.1 Live Response Mode
If the request body or URL references collected parameters or master data variables, you must assign values before testing. After setting parameter values, click to run the API test and obtain the returned structure. Note: The API test sends a real request. Ensure the endpoint uses test data to avoid affecting production.
Sample parameter:
email:zhang[.zhiyu@xinheyun.com](mailto:.zhiyu@xinheyun.com)
Return value:
{
"data": {
"orders": {
"edges": [
{
"node": {
"id": "gid://shopify/Order/10194884526372",
"name": "#1001",
"createdAt": "2025-09-24T03:45:45Z",
"email": "[zhang.zhiyu@xinheyun.com](mailto: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](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](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](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 Sample Response Mode
Directly enter a JSON structure for the response body. Ensure the syntax is valid.
When the sample response’s JSON syntax is correct, proceed to the next step: Response Data Mapping.
Step 4: Response Data Mapping
Use this step to configure parameter mappings in the response structure and control 3Chat Agent accessibility.
- After completing the API test or manually entering a response, the system automatically extracts all parameters from the JSON response and creates a response parameter list. Original nesting is preserved in the parameter names.
- Configure transformation rules for response parameters as needed: click Edit at the end of the row to open the settings dialog.
- Response Parameter Name: The key from the response (keeps original JSON hierarchy)
- Sample Response Value: The value captured from the response structure
- Mapped Parameter Name: The parameter name visible to the 3Chat Agent (defaults to the original name)
- Data Type: The data type visible to the 3Chat Agent (defaults to the original type; you may convert types as needed)
- Accessible: Whether the 3Chat Agent can access this response parameter
- After mapping, the result appears as follows:
Suggestions for Parameter Transformations
| Suggestion | Effect |
|---|---|
When a parameter name does not clearly convey its meaning, rename it to a business-friendly name. For example, "abc": "O-250823-001" actually represents an order number, so map it to "orderCode". |
|
Convert response values to String. If a value uses numbers or cryptic strings to represent statuses, the 3Chat Agent cannot infer the meaning. For example, "orderStatus": 5 should map 5 → "Shipped". "orderStatus": "SHIP" should map "SHIP" → "Shipped". |
|
| When timestamps represent specific times, the 3Chat Agent cannot derive actual time from a raw timestamp. Change the type to Datetime to convert the timestamp to standard UTC time. |
Save and Run the Tool
After completing the above configurations, click Save to store the data and run the tool. The 3Chat Agent can then use this tool in production to handle customer inquiries. If you no longer want the 3Chat Agent to access this tool, simply pause/stop it.
