# feishu-project-mcp — auth permission

### 方式A：MCP Token 直连（推荐）

1. 用户在飞书项目中获取 MCP Token：打开帮助中心 → 「功能入口」 → 复制域名和 X-Mcp-Token
2. 配置到 `~/.hermes/config.yaml`：

```yaml
mcp_servers:
  feishu-project:
    url: https://project.feishu.cn/mcp_server/v1
    transport: streamable_http  # ⚠️ 飞书 MCP 用 Streamable HTTP（POST JSON-RPC），不是 SSE！
    headers:
      X-Mcp-Token: "m-xxxxxxxxxx"
```

3. 验证连接：

   **A) `hermes mcp test`（最简单）**：
   ```bash
   hermes mcp test feishu-project
   ```
   正确配置后应显示 `✓ Connected` + `✓ Tools discovered: 48`。

   **B) 直接 curl 测试（手动验证）**：
   ```bash
   curl -s -w "\nHTTP %{http_code}" \
     -X POST "https://project.feishu.cn/mcp_server/v1" \
     -H "X-Mcp-Token: m-xxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | head -20
   ```
   返回 HTTP 200 且包含 `"result":{"tools":[` 即为正常。


### ⚠️ MQL 字段级权限（2026-07-26 实战）

某些字段可能返回 `no permission`，导致查询 `total=0`（非 HTTP 错，而是 MQL 语义错被静默吞掉）：

```
attribute key or value error (Code: 3010)
attribute[field_ec1e8b]: no permission
```

**排查**：逐个字段二分法测试。先最小字段集（`name, work_item_id`）验证查询可通，再逐个加字段定位无权限字段。已确认：客户类型的 `field_ec1e8b`（行业）、`field_e769ee`（国家）当前 MCP token 无读权限。

**修复**：从 MQL SELECT 移除无权限字段，或向 MCP token 管理员申请字段级读权限。