MCP Service Integration

1. Basic concepts of MCP

1.1 What is MCP service

MCP (Model Context Protocol) service is a standardized service interface provided by the Commander platform, which allows external agents (AI Agents) to call the RPA automation capability of the platform through MCP protocol.

Through MCP services, intelligent agents can:

• Get the list of available task templates
• Create automated task based on task templates
• Query task execution status and results

1.2 Application Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      智能体平台                                  │
│                  (AI Agent Platform)                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ MCP协议调用
                              │ HTTPS + Bearer Token
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Commander MCP服务端点                         │
│                  https://example.com/               │
│                          /automation/mcp                         │
└─────────────────────────────────────────────────────────────────┘

---

2. Quick Start

2.1 Basic use of process

步骤1:获取Personal Access Token
  ├─ 登录机器人指挥官平台
  ├─ 点击右上角用户头像
  ├─ 选择"个人令牌"
  └─ 点击"立即生成"生成令牌

步骤2:配置MCP客户端
  ├─ 设置服务端点URL
  ├─ 配置认证令牌
  └─ 验证连接

步骤3:调用MCP工具
  ├─ 获取任务模板列表
  ├─ 创建新任务
  └─ 查询任务结果

2.2 Service endpoint information

configuration item	value
agreement	HTTPS
Endpoint Path	/automation/mcp
authentication method	Bearer Token
Token format	rk-{CompanyOpenId}-{randomString}

---

3. Personal token management

3.1 What is a Personal Access Token

A Personal Access Token is a secure credential used to make API calls on behalf of a user's identity. Through this token, external applications can call the MCP service of the platform on behalf of the user.

3.2 Accessing Token Management Page

1. Log in to the Commander platform
2. Click on the user name/avatar on the right side of the top navigation bar
3. Select 'Personal Token' from the dropdown menu

3.3 Generating Personal Tokens

3.3.1 Operation steps

1. Enter the personal token management page
2. If it is the first time using, click the 'Generate Now' button
3. The system automatically generates a token, which is named 'default' by default
4. Copy and properly save the token

3.3.2 Token Format Description

The generated token format is:

rk-{CompanyOpenId}-{32位随机字符}

Example:

rk-abc123def456-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p

Important Notice : After the token is generated, please copy it immediately and save it properly. After closing the page, you cannot view the complete token again.

3.4 Reset Personal Token

If you need to update the token (such as token leakage), you can perform a reset operation:

1. Find the token to reset in the token list
2. Click the reset button
3. Confirm reset operation

Attention : After resetting the token, the original token will immediately become invalid, and all external services using the original token will be unable to pass authentication. Please update all service configurations that use this token in a timely manner.

3.5 Delete Personal Token

1. Find the token to be deleted in the token list
2. Click the delete button
3. Confirm on delete

Attention : After deleting the token, all external services using the token will lose access to the platform services.

3.6 Checking Token Usage

The following information is displayed in the token list:

field	Explanation
Token Name	Token Name
Personal Access Token	Token value (partially hidden, replicable)
Created Time	Token creation time
Last Used Time	Last time the token was used (the last time it was successfully exchanged for system access credentials, not the last time it was called, please distinguish)

---

4. Use of MCP tool

4.1 Overview of Tool List

MCP services provide the following tools:

Tool Name	Functional Description
get_task_templates	Get the list of task templates that users can access
create_task	Create a new execution task
query_task_result	Query the execution status and results of task

4.2 get_task_templates tool

4.2.1 Function Description

Get the list of all task templates that the current user can access, and support keyword search and paging.

4.2.2 Request parameter

parameter name	Type	Required	Explanation
keyWord	string	No	The process name keyword is used to filter and use the template of the specified process. Only supports single characters or words as search keywords, and does not support using symbols such as spaces and commas to combine multiple keywords for queries
pageIndex	integer	No	Page numbers, starting from 1, default to 1
pageSize	integer	No	Quantity per page, default is 20, maximum is 50

4.2.3 Response Format Description

The return result of MCP tool is packaged in a JSON string, and the actual response format is:

{
  "result": "{\"return\": {...}, \"meta\": {...}}"
}

The client needs to parse first result Fields need to be parsed again after obtaining the JSON string to obtain complete business data.

4.2.4 Response Example

Example of parsed business data :

{
  "return": {
    "data": {
      "items": [
        {
          "name": "财务报表自动生成",
          "description": "自动生成月度,季度和年度财务报表",
          "template_detail": {
            "flowName": "finance_report_flow",
            "assignType": "automatic",
            "workerGroupName": "财务机器人组",
            "priority": "high",
            "parameters": [
              {
                "parameterName": "report_type",
                "parameterType": "string",
                "parameterRemark": "报表类型:monthly/quarterly/annual"
              }
            ]
          }
        }
      ],
      "pageIndex": 1,
      "pageSize": 20,
      "totalCount": 1
    },
    "code": "0",
    "message": ""
  },
  "meta": {
    "data_integrity": {
      "is_truncated": false
    }
  }
}

4.3 Create Task Tool

4.3.1 Function Description

Create a new automated task based on the specified process, and support parameter configuration and task scheduling settings. After the task is created, the task ID is returned immediately, and the task is executed asynchronously.

4.3.2 Request parameter

parameter name	Type	Required	Explanation
flowName	string	is	Name of RPA process to be executed
assignType	string	is	Allocation strategy: automatic/design
workerName	string	No	Specify the name of the robot during allocation, and pass null or "0" during automatic allocation
workerGroupName	string	No	The name of the robot group during automatic assignment. Null or "0" is passed when assigning
count	integer	No	Number of created task, default 1, range 1-100
departmentName	string	No	Department name, required when the user belongs to multiple departments
priority	string	No	Task priority: high/middle/low, middle by default
isRecord	boolean	No	Whether to record screen, default based on organizational configuration
hasMaxRunningTime	boolean	No	Whether to enable the Maximum Run Time limit? The default is false
maxRunningTime	integer	No	Maximum Run Time (minutes), it is recommended to fill in when limit is enabled
validityDays	integer	No	Task validity period (days), 30 by default
parameters	array	No	Process input parameter array. Each parameter needs to pass in the parameterName, parameterType and parameterValue fields. ParameterType supportstring,number,booleanThere are three types. The parameter of the credentials type is not supported to be transferred from the MCP client. See the example below.

parameters Field example:

[
{"parameterName":"example_name1","parameterType":"string","parameterValue":"example_value"},
{"parameterName":"example_name2","parameterType":"number","parameterValue":"1"},
{"parameterName":"example_name3","parameterType":"boolean","parameterValue":"False"}
]

4.3.3 Response Format Explanation

The return result of MCP tool is packaged in a JSON string, and the actual response format is:

{
  "result": "{\"return\": {...}, \"meta\": {...}}"
}

The client needs to parse first result Fields need to be parsed again after obtaining the JSON string to obtain complete business data.

4.3.4 Response Examples

{
  "return": {
    "data": {
      "taskIds": [4702818380283905, 4702818380283906]
    },
    "code": "0",
    "message": "Tasks created successfully"
  },
  "meta": {
    "data_integrity": {
      "is_truncated": false
    }
  }
}

4.4 Query_task_desult tool

4.4.1 Function Description

Query the execution status, results and details of the created task according to the task ID.

4.4.2 Request parameter

parameter name	Type	Required	Explanation
taskId	integer	is	Task ID to query

4.4.3 Response Format Description

The return result of MCP tool is packaged in a JSON string, and the actual response format is:

{
  "result": "{\"return\": {...}, \"meta\": {...}}"
}

The client needs to parse first result Fields need to be parsed again after obtaining the JSON string to obtain complete business data.

4.4.4 Response Examples

Example of parsed business data :

{
  "return": {
    "data": {
      "taskId": 4702818380283905,
      "departmentName": "Laiye Tech",
      "flowName": "财务报表自动生成",
      "state": "completed",
      "subStateMessage": "任务执行完成",
      "createTime": "2025-11-19T07:50:19Z",
      "startTime": "2025-11-19T07:51:00Z",
      "stopTime": "2025-11-19T08:05:30Z",
      "runningTime": 870
    },
    "code": "0",
    "message": ""
  },
  "meta": {
    "data_integrity": {
      "is_truncated": false
    }
  }
}

4.5 task Execution Status Description

status code	Status Name	Explanation
pending	Pending execution	Task created, waiting for robot to execute
running	Executing	Task is being executed on robot
completed	Execution completed	Successful execution of task
failed	Execution failed	An error occurred during the execution of the task
cancelled	Cancelled	Task cancelled by user
stopped	stopped	Task stopped by the system
expired	Expired	The task is not executed after the expiration date

Task sub state : Task results also include subState Field, used to describe the execution status of the task in more detail:

• success : Task executed successfully
• Other sub status codes are defined according to specific business scenarios

The response will also include subStateMessage Field, providing detailed description information of the status.

4.6 Data Analysis Explanation

Important : All responses from MCP tools require secondary JSON parsing:

1. First parsing: Obtain from MCP tool response result The string value of a field
2. Second analysis: will result Parse the string value of the field into a JSON object and retrieve it return and meta field
3. Third parsing (if necessary): return.data The field is also in JSON string format and needs to be parsed again

---

5. Integration Guide

5.1 MCP Client Configuration

5.1.1 Basic Configuration

# MCP客户端配置示例
mcp_client:
  server_url: "https://example.rpa.com:8182/automation/mcp"
  authentication:
    type: "Bearer"
    token: "rk-{CompanyOpenId}-{randomString}"
  timeout: 30000
  retry:
    max_attempts: 3
    backoff: 1000

5.1.2 Authentication Request Header

Authorization: Bearer rk-{CompanyOpenId}-{randomString}
Content-Type: application/json

5.2 Typical Integration Scenarios

Scenario 1: Intelligent customer service automatically creates RPA task

1. Users submit financial statement generation requests to intelligent customer service
2. Intelligent customer service call get_task_templates Get available templates
3. Intelligent customer service selects the template for "automatic generation of financial statements"
4. Call create_task Create a task and pass in the report type and time range parameter
5. Return the task ID to the user
6. The user uses the task ID to pass the query_task_result Query execution status

Scenario 2: Integration of Timed Scheduling System

1. The scheduling system triggers a timed task
2. Call get_task_templates Obtain relevant templates
3. Call create_task Batch Create task
4. Record the returned task ID list
5. Regular backend calls query_task_result Check task status

5.3 Error Handling

5.3.1 Authentication Error

{
  "return": {
    "code": "401",
    "message": "Invalid or expired access token"
  }
}

Handling suggestions :

• Verify if the token format is correct
• Check if the token has been refreshed or deleted
• Contact the user to regenerate the token

5.3.2 Permission Error

{
  "return": {
    "code": "403",
    "message": "Access denied: insufficient permissions"
  }
}

Handling suggestions :

• Verify whether the user has permission to use the requested resources
• Check the user permission range corresponding to the token

5.3.3 parameter error

{
  "return": {
    "code": "400",
    "message": "Invalid parameter: flowName not found"
  }
}

Handling suggestions :

• Check whether the parameter value meets the requirements
• Call first get_task_templates Get a valid process name

5.4 Guidelines for Writing Prompt Words for Intelligent Agents

When integrating the MCP service of the Commander into the agent (AI Agent), a reasonable prompt design is essential to guide the agent to call tools correctly.

5.4.1 Writing principles for prompt words

Principle	Explanation
Clarify the automation scenario	Clearly inform the intelligent agent which business scenarios can be automated using RPA
Establish business associations	Establish a clear mapping relationship between business terms and MCP tools
Guide tool call	Clearly tell the agent when to call which tool
Explain parameter requirements	Tell the agent what parameter information is needed when calling the tool
Set response expectations	Tell the agent how to feed back the task execution results to the user

5.4.2 Basic prompt word template

The following is a universal prompt word template that can be adjusted according to actual business scenarios:

你是一个智能助手,可以为用户调用RPA自动化服务来处理重复性,规则性的业务任务.

[可用的自动化能力]
你可以通过调用以下MCP工具为用户提供自动化服务:

1. get_task_templates - 查询可用的任务模板列表
   - 当用户询问"可以自动完成什么任务"或"有哪些自动化能力"时调用
   - 可以使用关键字搜索特定类型的任务模板

2. create_task - 创建并执行自动化任务
   - 当用户明确要求执行某个自动化任务时调用
   - 需要先通过get_task_templates确认任务模板存在

3. query_task_result - 查询任务执行状态和结果
   - 当用户询问任务执行进度或结果时调用

[触发条件]
当用户的需求包含以下特征时,考虑调用MCP工具:
- 提到"自动","自动化","机器人"等关键词
- 描述的是重复性,规则性的操作(如数据录入,报表生成,文件处理等)
- 需要在多个系统之间进行数据同步或传输
- 需要定时执行的任务

[工作流程]
1. 理解用户需求,判断是否属于可自动化的场景
2. 调用get_task_templates查询相关的任务模板
3. 向用户说明可用的自动化选项
4. 获取用户确认和必要的参数
5. 调用create_task创建任务
6. 告知用户任务ID,并说明可以使用query_task_result查询进度

[注意事项]
- 在不确定用户需求时,先询问清楚再调用工具
- 对于需要用户提供参数的任务(如时间范围,文件路径等),务必先获取这些信息
- 任务执行是异步的,需要告知用户任务不会立即完成
- 如果找不到匹配的任务模板,诚实地告知用户当前不支持该自动化场景

5.4.3 Example of Scenario based Prompt Words

Scenario 1: Automated Financial Reimbursement

你是一个财务助手,可以帮助用户处理与财务报销相关的自动化任务.

用户可能会用以下方式表达需求:
- "帮我自动完成报销申请"
- "发票信息能自动填到报销系统吗"
- "每个月的报表能不能自动生成"

当用户提到"报销","发票","报表"等财务相关词汇,且带有"自动"的意思时:
1. 首先调用get_task_templates,使用关键字如"报销","发票","报表"进行搜索
2. 将找到的模板及其描述展示给用户
3. 如果用户需要执行某项任务,获取必要的参数(如发票文件,时间范围等)
4. 调用create_task创建任务
5. 返回任务ID给用户,说明任务正在后台执行

Scenario 2: Data entry and synchronization

你是一个数据管理助手,可以帮助用户处理数据录入和数据同步的自动化任务.

当用户的需求涉及:
- 从Excel/CSV文件批量录入数据到系统(如CRM,ERP)
- 在多个系统之间同步数据
- 定期拉取某个系统的数据并生成报告

工作流程:
1. 理解用户的数据源和目标系统
2. 调用get_task_templates搜索相关模板(关键字:"数据","同步","导入"等)
3. 确认用户的执行意图,获取必要的文件路径,时间范围等参数
4. 创建自动化任务并反馈任务ID

Scenario 3: Mail and document processing

你是一个办公助手,可以帮助用户处理邮件和文档相关的自动化任务.

支持的自动化场景包括:
- 自动识别邮件中的发票,合同等文档
- 自动分类和归档邮件
- 批量处理文档(如格式转换,信息提取)
- 自动生成并发送标准邮件

当用户提到"邮件","文档","自动处理","识别"等词汇时:
1. 调用get_task_templates查看相关能力
2. 向用户说明可用的自动化选项
3. 获取必要的参数(如邮箱账号,文件位置,规则条件等)
4. 创建任务并跟踪执行状态

5.4.4 Advanced Tip Word Techniques

skill	Explanation	example
Few Shot Example	Provide specific dialogue examples for intelligent agents	User: "Can invoices be automatically processed?" → The intelligent agent calls get_task_templates to search for "invoices"
Chain-of-Thought Prompting	Guide intelligent agents to gradually think	"When users propose demand, first judge: 1. Whether it is an automation scenario 2. Query available templates 3. Confirm parameter and then create task"
Negative Example	Clearly tell the intelligent agent what situations should not be called	"If the user's demand is a one-time operation or requires creative judgment, do not call the automation tool"
Role setting	Set clear business roles for intelligent agents	"As an RPA automation expert, you are familiar with various automation process of the enterprise"

5.4.5 Suggestions for debugging prompt words

Before deploying the intelligent agent, it is recommended to conduct the following tests:

Test Type	Test content	Expected Behavior
Positive testing	Use clear automation demand scripts	Agents should actively query and create task
Negative testing	Using unrelated language	Intelligent agents should not call MCP tools
Boundary Testing	Using vague language	Intelligent agents should proactively inquire and clarify
Parameter test	The test lacks the necessary parameter	Agents should actively ask for missing parameter

---

6. Best practices

6.1 Token Security Management

Suggestion	Explanation
Regularly refresh tokens	Suggest refreshing personal tokens every 90 days
secure storage	Store tokens in a secure key management system
Minimum privilege principle	Only allocate necessary permissions for integrated accounts
Monitor usage	Regularly check the last usage time of the token and promptly handle any abnormalities found

6.2 Suggestions on task Creation

Suggestion	Explanation
parameter validation	Call before creating a taskget_task_templatesVerify the validity of parameter
asynchronous processing	Return immediately after the task is created, and use the background task to poll the execution results
Error Retry	Implementing a retry mechanism for exponential backoff to handle network failures
Batch operation	Use the count parameter to batch create task with the same configuration

6.3 Optimization of Status Query

Suggestion	Explanation
Reasonable polling	At the initial stage of task execution, a short polling interval (such as 30 seconds) is used, which is extended to 2-5 minutes after stabilization
Avoid excessive queries	There is no need to continue querying for completed/failed task
Result cache	Cache the queried task results to avoid repeated queries

6.4 Data integrity processing

The MCP service has an 8KB size limit for returned data. Data exceeding the limit will be truncated.

{
  "meta": {
    "data_integrity": {
      "is_truncated": true,
      "truncation_reason": "size_limit_exceeded",
      "original_size": 12288,
      "size_limit": "8192"
    }
  }
}

Handling suggestions :

• Check the response data_integrity.is_truncated field
• If the data is truncated, complete data can be obtained through the platform UI

---

7. Common Problems

7.1 Token related

Q1: Does a personal token have an expiration date?

A: The personal token itself does not have an expiration date, but it is recommended to refresh it every 90 days to ensure security.

---

Q2: What should I do if I forget to save my token?

A: If the token has been generated but not saved, please refresh the token to generate a new one. Old tokens cannot be retrieved.

---

Q3: How many personal tokens can a user create?

A: The current version limits each user to 1 personal token.

---

Q4: How to deal with token leakage?

A: Please refresh the token immediately to invalidate the old token and update all service configurations that use the token.

7.2 Tool Call Related

Q5: Why is the task not executed immediately after create_task is called?

A: After the task is created, you need to wait for the robot to be free before executing it. This is a normal phenomenon, please proceed through query_task_result Query task status.

---

Q6: How to judge the completion of task execution?

A: Call query_task_result Query task status, when state For completed , failed , cancelled , stopped or expired When, the task is over.

---

Q7: How to view the cause of the error after a failed task execution?

A: Call query_task_result In response subStateMessage The field contains detailed error information.

---

Q8: Can I create task in batch?

A: Okay. Call create_task Time setting count Parameter (range 1-100) can be used to batch create task with the same configuration.

7.3 Technology Integration Related

Q9: What MCP protocol versions are supported by MCP services?

A: The MCP service uses the Streamable HTTP protocol and is compatible with the latest version of the MCP protocol.

---

Q10: Does the MCP service have a frequency limit for calling?

A: There is no clear frequency limit for calls in the current version, but it is recommended to control the call frequency reasonably to avoid putting pressure on the system.

---

Q11: How to handle network timeout?

A: Suggest setting a timeout of 30 seconds and implementing an exponential backoff retry mechanism.

---

Q12: What if the returned data is truncated?

A: Check the response meta.data_integrity Fields. If the data is truncated, complete data can be obtained through the UI of the Commander platform.

---

8. Troubleshooting

8.1 Troubleshooting of Connection Issues

Problem 1: Unable to connect to MCP service

phenomenon	Connection timeout or denied connection
Possible reasons	1. Service endpoint URL configuration error 2 Network connection issue 3 Firewall blocking
Troubleshooting steps	1. Verify that the service endpoint URL format is correct. 2 Check network connection 3 Confirm firewall rules allow HTTPS access
Solution	Fix configuration, check network, adjust firewall rules

Problem 2: Authentication failed

phenomenon	Return 401 Unauthorized
Possible reasons	1. Token format error 2 The token has been refreshed or deleted Token revoked
Troubleshooting steps	1. Verify that the token format isrk-{CompanyOpenId}-{randomString}2. Check the status of the token
Solution	Use valid tokens

8.2 Troubleshooting of Tool Call Issues

Question 3: get_task_templates returns an empty list

phenomenon	No task template returned
Possible reasons	1. The user does not have permission to use any task template 2 There are no matching results for the search keywords
Troubleshooting steps	1. Try again without keyWord parameter 2 Confirm user permissions
Solution	Contact the owner of the task template to assign permission

Problem 4: The create_task parameter is incorrect

phenomenon	Return 400 Bad Request
Possible reasons	1. The process corresponding to the flowName does not exist 2 Insufficient permissions 3 The parameter value does not meet the requirements
Troubleshooting steps	1. First call get_task_templates to verify the process name 2 Check user permissions 3 Verify parameter values
Solution	Call again with valid parameter values

Problem 5: The query_task_result task does not exist

phenomenon	Return 404 Not Found
Possible reasons	1. The taskId is incorrect. 2 Task has been deleted 3 The user does not have access to the task
Troubleshooting steps	1. Verify taskId format 2 Confirm that the task is created successfully 3 Check user permissions
Solution	Use the correct taskId to query

---

Appendix

Appendix A: Glossary of Terms

term	English	Explanation
MCP	Model Context Protocol	Model Context Protocol, a standardized protocol for AI agents to interact with services
Personal Access Token	-	Personal access token, a security credential used for API calls
Task Template	-	Task template, predefined task configuration
Flow	-	Process, definition of RPA automation process
Worker Robot	-	Worker, robot or robot group that executes RPA process
Asynchronous Execution	-	Asynchronous execution. The task is executed in the background, and the call returns immediately

Appendix B: HTTP Status Code Explanation

status code	Explanation
two hundred	Request successful
four hundred	Request parameter error
four hundred and one	Authentication failed, token is invalid or expired
four hundred and three	Insufficient permissions to access the requested resource
four hundred and four	Resource does not exist
five hundred	Internal server error