Create API Tools
This guide walks you through creating a new MCP tool on the platform.
API tools integrate external services and automate workflows.
What Is an API?
An API (Application Programming Interface) bridges communication between different software systems. Simply put, it acts like a "waiter" in the software world, helping programs exchange information and perform functions.
Imagine dining at a restaurant:
You: The customer who needs food (the application)
Kitchen: Where food is prepared (the system providing the service)
Waiter: Relays messages between you and the kitchen (API)
You do not need to enter the kitchen yourself. Tell the waiter what you want, and the waiter relays your request to the kitchen and brings the finished meal to you.
API tools help automate standardized workflows, define specific response formats, and retrieve information from your systems, for example:
E-commerce Customer Service Automation
Marketing Campaign Management
Online Course Platform:
With API tools, an AI assistant evolves from a simple chatbot into an intelligent assistant that executes business workflows, greatly improving efficiency and automation.
Quickly Create an API Tool
1. Open Tool Management
First, open the "AI Features" section in the left navigation bar, then click "🔧 Tools". On the tool list page, click "➕ Add Tool" in the upper-right corner.
2. Select the Tool Type
Select API as the tool type.
3. Set the Display Name
Give the tool a clear display name. Here, use google calendar.
Purpose: This name appears in the platform interface for all users to see.
Recommendation: Choose a name that clearly describes the tool's main function so users can understand it easily. There are no strict format restrictions for this name.
4. Set the Tool Name
Next is the "Tool Name" field.
Purpose: This name is the unique identifier the AI assistant uses internally to call and identify the tool.
Naming Rules (Important):
Use English characters.
Only the following characters are allowed:
Lowercase letters (a-z)
Uppercase letters (A-Z)
Numbers (0-9)
Underscores (
_)Hyphens (
-)
Examples:
get_weather_forecast,database-query-tool
The example below uses google_calendar_retriever
5. Write the Tool Description
Provide a clear, detailed explanation in the "Tool Description" field.
Why It Matters: A good description helps the AI assistant understand more accurately:
The tool's function and purpose.
When to use the tool.
How to interpret its output.
Recommended Content: Explain what the tool does, its inputs and outputs, and any usage considerations.
6. Configure the API Details
a. 🔗 API URL
Enter the full URL of the target API endpoint (including
http://orhttps://).Example:
https://api.opencalendar.org/data/2.5
b. 📮 HTTP Method
Select the HTTP verb required by the API service from the dropdown:
GET: Typically used to retrieve resources.POST: Typically used to create new resources or submit data.PUT: Typically used to fully replace or update resources.DELETE: Typically used to delete resources.
c. 📰 Headers
Headers are like the "envelope" of a letter: they provide important information to the recipient before the actual data is read. Without the correct headers, an API request may fail authentication, or the recipient may be unable to parse the data correctly.
Common Uses:
Authentication (
Authorization,X-API-Key)Specifying the content type (
Content-Type)Specifying the accepted response format (
Accept)
To add headers:
Click "➕ Add Header" to define the HTTP headers sent with the request.
Format: Use a valid JSON object, where each key is a header name and each value is the header content (a string).
Example:
d. 🔎 Query Parameters (Query Params)
Query parameters are the query string appended after the question mark in a URL (for example, ?format=json&limit=10). They are sent with every request. Use them for fixed query conditions or API keys that can only be passed through a query string.
Click "Available Context Variables" to expand the list of supported variables (contact ID, conversation ID, inbox ID, and more).
Format: A valid JSON object, where each key is a parameter name and each value is the parameter content (a string).
Values can be fixed text, or you can use
{{參數名}}to reference a parameter declared in Parameters Schema that the AI assistant fills in when calling the tool. This lets you configure query conditions with a fixed beginning and a user-provided ending. See Reference AI Assistant Parameters in Query Parameters below.Example:
e. 🧩 Parameters Schema
The parameters schema is like an "order form", telling the AI assistant what data it can request from the API and how to request it.
Core Configuration: Define which parameters the AI assistant can or must provide when calling this tool (the content sent to the system for processing), along with their formats.
Format: Use standard JSON Schema.
Key Elements:
type: "object": Indicates that the parameters form an object.properties: Defines the object for each parameter.Parameter Name (for example,
"search"): The corresponding object contains details about that parameter.type: The parameter's data type (string,integer,number,boolean,array,object).description: Explains the parameter's meaning to the AI assistant.default(optional): The parameter's default value.enum(optional): Lists the allowed options if the parameter can only take certain values.
required: An array containing the names of all required parameters.
Example (media search tool):
f. Path Parameters and Parameter Locations
Use {參數名} in an API URL to mark variable path segments, for example, /users/{userId}/orders/{orderId}. To substitute values provided by the AI assistant into the URL, define parameters with matching names in Parameters Schema and set their location to "Path". Before sending the request, the system URL-encodes each value and substitutes it into the URL. For example, A/B 01 becomes A%2FB%2001, so slashes or spaces in a value do not change the URL structure.
Use Case: Customer service supervisor Mai wants the AI assistant to query a single order through the company's order API using a customer ID and an order ID. She creates an API tool, sets both IDs as path parameters, and assigns the tool to the AI assistant. When a colleague enters "Look up order order-25 for customer customer-01" in the conversation, the AI assistant places both IDs in the correct URL positions and sends the query. If the order ID is missing, the tool reports the missing value immediately and does not send an incomplete request.
Set an API URL with Path Parameters
Add a tool by following "Quickly Create an API Tool" above. For practice, use the public httpbin response service and set API URL to:
A URL can contain multiple path parameters. After you enter it, "Detected Path Parameters" appears below the field and lists userId, orderId. If these names are not yet defined in the parameters schema, a red message also appears: "Please define them in Parameters Schema".
Declare Parameters with Matching Names in Parameters Schema
Enter the following in Parameters Schema (JSON Schema):
Parameter names must exactly match the names inside braces in the URL, including capitalization. required tells the AI assistant to provide both values on every call.
After you enter the schema, each parameter appears below it with a location dropdown set to "Default". A red message appears below API URL: "The following parameters are not located in Path; the URL placeholders will not be substituted". This means you still need to complete the next step.
Set the Parameter Location to Path
Below the parameters schema, change the location dropdowns for both userId and orderId to "Path".
Once selected, the system automatically adds "location": "path" to the parameters schema, and the red warning below API URL disappears. Verify the settings and click "Confirm" to save the tool.
Parameters whose location remains "Default" are not substituted into the URL. Even if the AI assistant provides a value, {userId} in the URL still lacks a value, so the tool reports an error and does not send the request. Set every parameter used in the URL to "Path".
Assign the Tool to an AI Assistant and Verify It
Follow Configure Tools for an AI Assistant to add the tool to an AI assistant in Agent mode. Then open "Agent Marketplace" in the left navigation bar, switch to "Organization-Built", select the AI assistant, and enter "Look up order order-25 for customer customer-01". After the AI assistant calls the tool, httpbin returns the request URL it actually received: https://httpbin.org/anything/users/customer-01/orders/order-25.
To view the URL actually sent on each call, open "AgentOps" → "Tool Execution Logs" in the left navigation bar. Click the eye icon in the record's action column to open "Details", then view "Request URL" under "Request Information". The example below uses a customer ID containing a slash and a space (A/B 01); you can see that the value has been URL-encoded.
After completing the exercise, replace the public demo URL with your company's order API URL.
Parameter Location Options
Each parameter in the parameters schema can have a location that determines where its value goes in the request:
Default
Retains the original behavior: GET places values in the query string; POST, PUT, and PATCH place them in the body. DELETE does not automatically include values; explicitly select a location when you need to pass a value
Path
Substitutes the value into the matching {參數名} in API URL
Query
Appends the value to the query string after the question mark in the URL
Body
Places the value in the JSON body
Header
Sends the value as an HTTP header using the parameter name; if Headers (JSON) already defines a header with the same name (case-insensitive), the configured content takes precedence
Existing tools without a location setting retain their behavior.
No Request Is Sent When a Path Parameter Value Is Missing
If any path parameter in the URL lacks a value on a call (the AI assistant did not provide it, the value is empty, or the parameter location is not Path), the tool stops immediately and reports "Path parameter {orderId} has no value in this call". It does not send a URL containing {orderId}. The AI assistant explains why the query failed in the conversation. In "Tool Execution Logs", the record is marked as failed, "Request Information" contains no request content, and "Error Message" identifies the parameter missing a value.
URL Syntax Restrictions
Path parameter names can contain only letters, numbers, and underscores, and cannot start with a number, for example,
{order_id}. Names such as{order-id}cannot be saved.Place
{參數名}in the URL path. For values that belong in the query string, set the parameter location to "Query" or reference them with{{參數名}}in Query Params.API URL does not support double-brace syntax such as
{{變數}}. When you save, an "Error Notification" appears: "Path parameters must use {identifier} syntax." In API tools, use{{參數名}}in Headers (JSON) and Query Params (JSON).
Custom actions in Google Style REST can retain their colon suffix, for example, a Google Weather query:
7. 💾 Save the Tool
Verify all settings, scroll to the bottom of the page, and click "Confirm". Your new tool is now ready!
Reference AI Assistant Parameters in Query Parameters
Many third-party APIs require query conditions as a single string combining fixed syntax with a user-provided value, such as an OData-style $filter=ProductName eq 'Chai' or the q= parameter of a search API. These APIs require the value to be embedded in a fixed string rather than sent as a separate parameter.
Enter {{參數名}} in a Query Params value. When the AI assistant calls the tool, MaiAgent substitutes the value of the matching parameter from Parameters Schema before sending the request. The person configuring the tool defines the fixed structure, while the AI assistant only supplies values, so the model no longer has to determine the correct syntax.
Use Case
The purchasing department wants the company's internal AI assistant to directly answer "What are the current unit price and stock level of a product?" using the OData query service provided by the company product catalog system. Previously, each API required custom code for this type of query. Now, a purchasing specialist can create an API tool, set the query condition to ProductName eq '{{product_name}}', and assign the tool to the AI assistant. When a colleague asks "What are the unit price and stock level of Chai?", the AI assistant automatically inserts Chai into the query condition, calls the API, and responds with the product name, unit price, and stock level.
Setup Steps
The following example uses the public Northwind demo data service (OData). You can follow these steps directly:
Assign the Tool to an AI Assistant and Test It
Follow Configure Tools for an AI Assistant to add this tool to an AI assistant in Agent mode and save. Then open "Agent Marketplace" in the left navigation bar, switch to "Organization-Built", and select the AI assistant to start a conversation. Enter "What are the unit price and stock level of Chai?". The AI assistant displays "Tool Used" and responds with Chai's unit price and stock level.
Substitution Rules
Variable names must match the parameter schema
{{product_name}} corresponds to a parameter name in properties in the "Parameter Schema"; capitalization must match exactly
Only values are substituted
Templates apply only to Query parameter values; keys remain unchanged and are not substituted
Values are substituted as literal text
Parameter values are always substituted as literal text without numeric conversion; for example, leading zeros in the business registration number 04595257 are preserved
Missing values stop execution
If the AI assistant does not provide the parameter for this call (or its value is empty), the tool stops with an error identifying the missing parameter, rather than sending {{product_name}} unchanged
Context variables take precedence
If a parameter name matches a context variable (such as contact_id or conversation_id), the context variable's value is always substituted; values provided by the AI assistant do not override it
Referenced parameters are still sent separately
Parameters referenced by a template are still sent as separate query parameters, following the original behavior (for example, product_name=Chai is also sent); most APIs ignore extra parameters
Parameter names are preserved
Query parameter keys containing underscores or uppercase letters (such as Business_Accounting_NO) are preserved exactly and are not rewritten by the system
Existing tool settings without {{ }} are unaffected. If the system previously rewrote a Query parameter name in an older tool (for example, changing Business_Accounting_NO to business__accounting_no), reopen the tool, restore the correct name, and save. When you reopen the editing window, Query parameter values appear masked as ****; saving directly preserves the original values.
⚠️ Important Notes
Connection Testing
After creating a tool, test whether the API works properly
You can use testing tools to verify tool functionality, such as:
POSTMAN
An API request testing platform built by your organization
Permission Management
Regularly review tool usage and access permissions
Last updated
Was this helpful?