# Develpers call remote MCP server

Developers can integrate Lark MCP tool capabilities into their AI Agents or automated workflows via code to implement complex, customized business logic.
The remote call mode allows developers to connect directly to the official Lark-deployed and maintained MCP service via a unique service URL. This mode eliminates the complexity of local deployment and environment configuration, enabling you to integrate Lark capabilities into AI Agents as quickly as possible.
Currently supports "**Docs**" scenario. View [Supported MCP Tools](). More scenarios (such as Base and Calendar) will be released later. You are welcome to [provide feedback](https://bytedance.larkoffice.com/share/base/form/shrcnGy0YNaviYYLjAX8zMqIW3f) on your usage scenarios 🥳

## Prerequisites

Before starting the integration, please ensure you have completed the following preparations:
1. **Create a Custom App**: Create a custom application on the [Lark Open Platform](https://open.feishu.cn/app).
1. **Apply for Permissions**: Apply for the corresponding API permissions based on your tool's needs. For example, if your tool needs to read/write Docs, you must apply for permissions like "View, comment, and manage Docs" (`drive:document`). Refer to [Applying for API Permissions](https://open.feishu.cn/document/ukTMukTMukTM/uQjN3QjL0YzN04CN2cDN).
1. **Obtain Access Credentials**:
    - **User Access Token (UAT)**: A credential representing user identity, suitable for scenarios requiring simulation of specific user actions. Refer to [Get user_access_token](https://open.larkoffice.com/document/server-docs/api-call-guide/calling-process/get-access-token?#4d916fe0).
    - **Tenant Access Token (TAT)**: A credential representing application identity, suitable for server-to-server call scenarios. Refer to [Get tenant_access_token](https://open.larkoffice.com/document/server-docs/api-call-guide/calling-process/get-access-token?#95c7f5f5).

## Supported MCP toolswarning
- MCP tool input and output formats are subject to flexible adjustments. **Do not rely on the structure definitions of inputs and outputs when calling MCP.**
- If multiple permissions are involved, please **apply for all of them**. Complete the activation based on your calling identity (UAT or TAT) by referring to [Apply for API Permissions](https://open.feishu.cn/document/ukTMukTMukTM/uQjN3QjL0YzN04CN2cDN).

### General Tools

Tool Name | Description | Limitations | Scenarios | Support UAT/TAT | Required Permissions
---|---|---|---|---|---
<code>search-user</code> | Search for users within the enterprise by keywords to obtain user ID, name, and avatar.<br>**Notice**：If there are users with the same name, they are returned based on intimacy, with users closer to you ranked higher. | - Only supports calling via user identity (user_access_token).<br>- Cannot search for external enterprise users or resigned users. | - Quickly find colleagues by name or email without knowing their exact ID.<br>- Locate specific personnel when you need to contact someone or assign a task but only remember part of their name. | UAT | - Search users <code>contact:user:search</code>
<code>get-user</code> | Get the current user's personal information, or get other users' names and avatars via User ID. | - User info only includes: User avatar, name, open id<br>- Can only query users visible to you in the contacts. See Admin settings [Organization Visibility](https://www.feishu.cn/hc/zh-CN/articles/360049067480-%E7%AE%A1%E7%90%86%E5%91%98%E7%AE%A1%E7%90%86%E7%BB%84%E7%BB%87%E6%9E%B6%E6%9E%84%E5%8F%AF%E8%A7%81%E8%8C%83%E5%9B%B4#tabs0|lineguid-Gu5cE). | - Query the currently logged-in user's personal info (e.g., confirming own open id).<br>- Obtain an employee's avatar and name when the User ID is known (e.g., obtained from search results). | UAT/TAT<br>**When calling with TAT, the contact permission scope must include the corresponding user.** | - Get contact basic info <code>contact:contact.base:readonly</code><br>- Get user basic info <code>contact:user.base:readonly</code>
<code>fetch-file</code> | Get file content. Retrieve the binary content of a specified resource (file or image) in a document based on the file ID (file_token). | - File size limited to within **5 MB**<br>- Requires download permission for the material. In the document "**Permission Settings**", the current user must have download permission, as shown below:<br>![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/69ac46f8a5fc4f1ec132d87ee953622f_o7pqVUS4YY.png?height=1630&lazyload=true&maxWidth=80&width=1004) | - Read images, charts, or attachments embedded in Docs.<br>- Retrieve raw binary data of specific resources within a document for subsequent processing in automated workflows. | UAT/TAT | - Download image and file in document  <code>docs:document.media:download</code><br>- View board node <code>board:whiteboard:node:read</code>

### Docs
If using TAT (Tenant Access Token) invocation, please ensure the application has been authorized for the target document/knowledge base. Refer to [How to enable document permissions for apps or users](https://open.larkoffice.com/document/server-docs/docs/faq#16c6475a).

Tool Name | Description | Limitations | Scenarios | Support UAT/TAT | Required Permissions
---|---|---|---|---|---
<code>search-doc</code> | Search Cloud Docs. Perform precise or fuzzy searches in your Feishu Cloud Docs based on keywords, creator, and other criteria. | - Can only search <code>doc</code> and <code>docx</code> file types. | - Quickly locate key information buried in massive documentation. Collect relevant internal materials when writing reports or proposals.<br>- Review work output from specific periods or members. | UAT | - Search document <code>search:docs:read</code><br>- View all Wiki <code>wiki:wiki:readonly</code>
<code>create-doc</code> | Create a Cloud Doc. Create a new document in "My Library" or under a specific Knowledge Base node.<br>**Notice**：For content exceeding the client input limit, the model can call <code>update-doc</code> to continue writing. | - Does not support inserting existing Base (Multidimensional Tables), Sheets, OKR, Tasks, Calendar, or Feishu Project content.<br>- Cannot create document widgets, synced blocks, legacy flowcharts, or legacy mindnotes. | - Quickly save AI conversation content, ideas, or analysis results as formal Feishu Cloud Docs.<br>- Automatically generate formatted reports, meeting minutes, or task lists. | UAT/TAT | - Create upgraded Docs <code>docx:document:create</code><br>- View wiki space node information <code>wiki:node:read</code><br>- Create wiki space node<br><code>wiki:node:create</code><br>- Upload image and file to document <code>docs:document.media:upload</code><br>- Create Whiteboard node <code>board:whiteboard:node:create</code><br>- Edit upgraded Docs <code>docx:document:write_only</code><br>- View upgraded Docs<br><code>docx:document:readonly</code>
<code>fetch-doc</code> | View Cloud Doc. Retrieve the full content of a document via its link.<br>**Notice**：AI can read super-long document content in segments. | - Does not support content from Base, Sheets, OKR, Tasks, Group Cards, Calendar, or Feishu Project.<br>- Cannot read legacy flowcharts or legacy mindnotes. | - Let AI read a specific document to summarize, translate, answer questions, or rewrite content.<br>- Serves as a foundational operation for retrieving source content during cross-document information integration. | UAT/TAT | - View new Docs <code>docx:document:readonly</code><br>- View task details <code>task:task:read</code><br>- View group information <code>im:chat:read</code>
<code>update-doc</code> | Update Cloud Doc. Add content at a specific location in a document, or refine/replace specific content. | * Does not support positioning via link anchors. | * **Long Text Continuation**: Append content in batches at the end of the document to bypass single-output limits.<br>* **Content Correction & Polishing**: Overwrite or locally modify specific content to optimize existing drafts.<br>* **Structured Insertion**: Insert supplementary information (e.g., "Technical Plan") precisely after specific sections (e.g., "Business Goals").<br>* **Dynamic Maintenance**: Update project status, meeting conclusions, etc., at specific levels or positions based on the latest progress. | UAT/TAT | - Create upgraded Docs <code>docx:document:create</code><br>- View wiki space node information <code>wiki:node:read</code><br>- Create wiki space node<br><code>wiki:node:create</code><br>- Upload image and file to document <code>docs:document.media:upload</code><br>- Create Whiteboard node <code>board:whiteboard:node:create</code><br>- Edit upgraded Docs <code>docx:document:write_only</code><br>- View upgraded Docs<br><code>docx:document:readonly</code>
<code>list-docs</code> | Get a list of Cloud Docs under a specific Knowledge Base node. Supports pagination. | * Sub-nodes within a Knowledge Base node require the AI to traverse them independently. | * **Directory Browsing**: Quickly understand which documents are contained in a project folder or Knowledge Base node.<br>* **Batch Processing Preparation**: Retrieve a document list before performing batch summarization or analysis on a group of documents. | UAT/TAT | - View all Wiki <code>wiki:wiki:readonly</code>
<code>get-comments</code> | View full-text comments and inline comments in a specific Cloud Doc. | * Only supports emoji, text, and document-type comments. <br>* Does not support retrieving images within comments. | * **Feedback Collection**: Directly access modification suggestions or questions left by colleagues without opening the document.<br>* **To-Do Organization**: Extract comments from documents and convert them into next-step work plans or to-do items. | UAT/TAT | - Get comments in document <code>docs:document.comment:read</code><br>- Get basic information in contacts<code>contact:contact.base:readonly</code>
<code>add-comments</code> | Add Full-Text Comment. Add a document comment to a specific Cloud Doc. | * Only supports adding full-text comments; does not support inline comments.<br>* Does not support uploading images to comments. | * **Quick Interaction**: Directly post evaluations or feedback via chat after reading AI-summarized document content.<br>* **Audit Record**: Quickly record review opinions in collaborative documents to alert the author. | UAT/TAT | - Add and reply to comment in document <code>docs:document.comment:create</code>

## Integration Process

### Step 1: Initialize Connection (initialize)

Establish a connection with the MCP service, verify credentials, and return session information.
```
POST /mcp
Header: X-Lark-MCP-TAT: t-gxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Lark-MCP-Allowed-Tools:toolname1,toolname2,toolname3
Body: {"method": "initialize", ...}
```

### Step 2: List Available Tools (tools/list)

Query the list of MCP tools and their descriptions defined by the current credentials and `X-Lark-MCP-Allowed-Tools`.

```shell 
POST /mcp
Header: 
X-Lark-MCP-TAT: t-gxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Lark-MCP-Allowed-Tools:toolname1,toolname2,toolname3
Body: {"method": "tools/list", ...}
```

### Step 3: Call Tool (tools/call)

Execute a specific tool (the tool must be included in the request header `X-Lark-MCP-Allowed-Tools` list).

```
POST /mcp
Header:
Content-Type: application/json
X-Lark-MCP-TAT: t-gxxxxxxxxxxxxxxxxxxxxx
X-Lark-MCP-Allowed-Tools:toolname1,toolname2,toolname3
Body: {"method": "tools/call", "params": {"name": "toolname1", ...}}
```

## Authentication & Requests

### Request Path

All MCP API requests use a unified endpoint and HTTP method.

- **HTTP URL**: https://mcp.feishu.cn/mcp  
- **HTTP Method**: POST  

### Request Headers

MCP uses HTTP request headers for authentication and configuration.

Header | Required | Description | Example
---|---|---|---
<code>X-Lark-MCP-UAT</code> or <code>X-Lark-MCP-TAT</code> | Yes | Authentication credential; choose one. UAT represents user identity, TAT represents app identity. | <code>X-Lark-MCP-TAT: t-gxxxxxxxx</code>
<code>Content-Type</code> | Yes | Media type of the request body; must be <code>application/json</code>. | <code>application/json</code>
<code>X-Lark-MCP-Allowed-Tools</code> | No | List of tools allowed for this connection, consisting of tool names separated by commas. **If this header is not provided, AI will not be able to discover or call any tools.** | <code>create-doc,fetch-doc</code>

### Request Body

All request bodies follow the JSON-RPC 2.0 specification and include the following core fields:
- `jsonrpc`: (string) JSON-RPC protocol version, fixed as `"2.0"`.
- `id`: (integer) Unique identifier for the request, used to correlate the request and response.
- `method`: (string) Name of the method to be called.

Example:

```
POST /mcp HTTP/1.1
Host: mcp.feishu.cn
Content-Type: application/json
X-Lark-MCP-UAT: u-gxxxxxxxxxxxxxxxxxxxxx
X-Lark-MCP-Allowed-Tools: create-doc,fetch-doc
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize"
}
```

## Supported MCP Methods

Method | Function | Request Body Example | Response Body Example (Success)
---|---|---|---
<code>initialize</code> | Initialize an MCP session, verify authentication credentials, and return server information. | ```json<br>{<br>"jsonrpc": "2.0",<br>"id": 1,<br>"method": "initialize"<br>}<br>``` | ```json<br>{<br>"jsonrpc": "2.0",<br>"id": 1,<br>"result": {<br>"protocolVersion": "2024-11-05",<br>"serverInfo": {<br>"name": "Lark MCP Server",<br>"version": "1.0.0"<br>}<br>}<br>}<br>```
<code>tools/list</code> | List available tools in the current session. Returned tools are limited by the <code>X-Lark-MCP-Allowed-Tools</code> request header. | ```json<br>{<br>"jsonrpc": "2.0",<br>"id": 1,<br>"method": "tools/list"<br>}<br>``` | ```json<br>{<br>"jsonrpc": "2.0",<br>"id": 1,<br>"result": {<br>"tools": [<br>{<br>"annotations": {<br>"title": "View Cloud Doc",<br>"readonlyHint": false,<br>"destructiveHint": true,<br>"idempotentHint": false,<br>"openWorldHint": true<br>},<br>"description": "Retrieve Feishu Cloud Doc content...",<br>"inputSchema": {<br>"properties": {<br>"docID": {<br>"description": "Document ID",<br>"type": "string"<br>}<br>},<br>"required": [<br>"docID"<br>],<br>"type": "object"<br>},<br>"name": "fetch-doc"<br>}<br>]<br>}<br>}<br>```
<code>tools/call</code> | Call a specific tool and pass the tool name and required parameters via <code>params</code>. | ```json<br>{<br>"jsonrpc": "2.0",<br>"id": 2,<br>"method": "tools/call",<br>"params": {<br>"name": "fetch-doc",<br>"arguments": {<br>"docID": "xxxxxx"<br>}<br>}<br>}<br>``` | ```json<br>{<br>"jsonrpc": "2.0",<br>"id": 2,<br>"result": {<br>"content": [<br>{<br>"type": "text",<br>"text": "{\"data\": {...}}"<br>}<br>]<br>}<br>}<br>```

## Typical Framework Code Examples

### Nodejs

- **Langchain**: [Official Documentation](https://docs.langchain.com/oss/javascript/langchain/mcp#http)
- **ai-sdk**: [Official Documentation](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools#http-transport-recommended)
- **typescript-sdk**: [Official Documentation](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md)

### Python

- **Langchain**: [Official Documentation](https://docs.langchain.com/oss/python/langchain/mcp#http)
- **Python-sdk**: [Official Documentation](https://github.com/modelcontextprotocol/python-sdk)

### Go

- **Eino**：[Official Documentation](https://www.cloudwego.io/docs/eino/ecosystem_integration/tool)
- **mcp-go**: [Official Documentation](https://mcp-go.dev/clients/transports#streamablehttp-client-with-custom-configuration)
- **Go-sdk**: [Official Documentation](https://github.com/modelcontextprotocol/go-sdk)

### Java

- **Java-sdk**: [Official Documentation](https://github.com/modelcontextprotocol/java-sdk)
- **Spring**: [Official Documentation](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html#_streamable_http_transport_properties)

## Error Codes

HTTP Status Code | Error Code | Error Message | Troubleshooting Suggestion
---|---|---|---
400 | <code>-32700</code> | Parse error | Check if the request body is in valid JSON format.
400 | <code>-32600</code> | Invalid Request | JSON-RPC request structure does not meet specifications. Please check if the request body is a valid JSON object and ensure it includes the following necessary fields:<br>- <code>jsonrpc</code>: Fixed value <code>"2.0"</code>.<br>- <code>method</code>: Must be a non-empty string.<br>- <code>id</code>: Unique identifier for the request.<br>- <code>params</code>: Data type must match the interface definition.
404 | <code>-32601</code> | Method not found | - **Tool does not exist**: Check if the <code>tool</code> name is correct and if the method being called belongs to the allowed <code>tool</code> list.<br>- **Method does not exist**: Check if the method name is <code>initialize</code>, <code>tools/list</code>, or <code>tools/call</code>.
400 | <code>-32602</code> | Invalid params | Invalid parameters. Please check the <code>error.message</code> field in the response body for details.
500 | <code>-32603</code> | Internal error | Internal server error: Retry is recommended. If the issue persists, please contact technical support with the request time and key parameters (masked).
429 | <code>-32030</code> | Rate Limited | Request rate limit exceeded. Please reduce the call frequency or contact technical support to adjust the rate limit threshold.
401 | <code>-32011</code> | UAT TAT Required | Check if <code>X-Lark-MCP-UAT</code> or <code>X-Lark-MCP-TAT</code> is provided in the request header.
400 | <code>-32003</code> | Param Validate Error | Parameter validation error. The requested GrantToken/UAT/TAT is invalid or expired.
400 | <code>-32042</code> | Invalid Content Type | Check if the <code>Content-Type</code> request header is <code>application/json</code>.

## Error Response Format

- **Tool Execution Failure**: When the API request is successful but an error occurs within the tool execution, the HTTP status code remains `200`. This is indicated by `isError: true` in the `result` object and the error information in `content`.

```
{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "content": [
            {
                "type": "text",
                "text":"{"error":"[VALIDATION:1004] Document ID length is insufficient: 13 < 15\n💡 Suggestion: Please check if the document token is complete\n📍 Context: docID=ewqedwqeqwewq, length=13","log_id":"202512112222588228F6885BAECF6F6987"}"
            }
        ],
        "isError": true
    }
}
```
- **Call Failure**: When the request itself is invalid (e.g., authentication failure, incorrect method name), the top-level `error` object is returned directly.
```
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}
```