---
name: banyan-mcp-setup
description: "把榕树 banyan 的 MCP server 接进编码 Agent（Claude Code / Hermes / Codex 等）：token 从哪生成、stdio 启动方式（node 拉起客户端的 banyan-mcp.mjs）、通用 mcpServers 配置片段，以及三个具体落点。当 Agent 里找不到 banyan 工具、或出现 401 / 未授权时也用它排查。"
license: MIT
metadata: {"banyan-id": "banyan-mcp-setup", "banyan-mcp": "none"}
---

# 榕树 banyan — 把 MCP server 接进 Agent

榕树客户端内置一个 **stdio MCP server**（`banyan-mcp.mjs`）。它只做一件事：把 MCP 工具调用翻译成对榕树本地 API 的 HTTP 请求——业务逻辑不复制一份，认证靠环境变量。接上之后，Agent 就能用 `create_article` / `publish_article` / `claim_topic` 这类工具操作榕树。

## 什么时候用

- 用户说「把榕树接进 Claude Code / Hermes / Codex」「让 Agent 能用榕树的工具」；
- Agent 里**找不到 banyan 工具**、调用报 `401` / 未授权 / `fetch failed`；
- 换了 token、换了客户端安装目录、或多位作家要各自独立接入时。

## 第一步：拿 token

在榕树客户端 **「设置 → API 与 MCP」** 生成 / 查看 API token。注意：

- token 与账号或作家身份绑定——**每个接入方用各自的 token**，多个 Agent / 多位作家不要共用一个；
- 页面同时给出本机的接口地址与端口（默认 `http://127.0.0.1:5832`）；
- **token 是凭据**：只写进 Agent 的配置文件（见下），**不要写进 SKILL.md 正文、不要提交到 git 仓库、不要贴进聊天记录或公开 issue**。本文档里一律用 `<token>` 占位。

## 第二步：确认 MCP server 脚本路径

server 是打包进客户端的 `banyan-mcp.mjs`，用 `node` 直接拉起：

| 场景 | 脚本路径 |
|---|---|
| 装好的客户端（macOS） | `/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs` |
| 装好的客户端（Windows） | `<安装目录>\榕树\resources\banyan-mcp.mjs` |
| 开发态源码 | `<榕树项目目录>/resources/banyan-mcp.mjs` |

路径不确定时，在客户端「设置 → API 与 MCP」里有对应的 stdio 启动命令可直接复制。

**环境变量**（由 Agent 在拉起进程时注入）：

| 变量 | 必填 | 说明 |
|---|---|---|
| `BANYAN_TOKEN` | 是 | API 认证 token，从「设置 → API 与 MCP」取 |
| `BANYAN_BASE_URL` | 否 | API 地址，默认 `http://127.0.0.1:5832`；改过端口 / 地址时用 |

启动命令就是：

```bash
BANYAN_TOKEN=<token> node "/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"
```

## 通用配置片段

大多数 Agent 的 MCP 配置都是「一个 JSON 对象 + 一条 server 定义」，形状如下（占位符原样替换）：

```json
{
  "mcpServers": {
    "banyan": {
      "command": "node",
      "args": ["/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"],
      "env": { "BANYAN_TOKEN": "<token>" }
    }
  }
}
```

外层键名按各家约定（`mcpServers` / `mcp.servers` 等），内层 `command` / `args` / `env` 三件套一致。

## 三个具体落点

### Claude Code

用官方 CLI 注册，`-s user` 表示用户级（任何目录启动的会话都能用，`local` 只在本项目生效）：

```bash
claude mcp add banyan -s user --env BANYAN_TOKEN=<token> -- node "/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"
```

同名 server 已存在时 **CLI 不会用新的 `--env` 覆盖旧 token**——先 `claude mcp remove banyan -s user`，再 `add`。

### Hermes Agent

写 `config.yaml`（默认 `~/.hermes/config.yaml`；多 profile 时写 `~/.hermes/profiles/<name>/config.yaml`，各 profile 独立）的 `mcp_servers:` 段：

```yaml
mcp_servers:
  banyan:
    command: node
    args:
      - /Applications/榕树.app/Contents/Resources/banyan-mcp.mjs
    env:
      BANYAN_TOKEN: <token>
```

改完重启 Hermes 会话，工具才会出现在工具目录里。

### Codex

写 `~/.codex/config.toml` 的两个表（server 定义 + env 子表）：

```toml
[mcp_servers.banyan]
command = "node"
args = ["/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"]

[mcp_servers.banyan.env]
BANYAN_TOKEN = "<token>"
```

## 第三步：验证

1. **客户端在运行**：MCP server 只是本地 API 的代理，榕树客户端没起着就一定失败。
2. 重启 Agent（或新开一个会话）后，先做一个只读调用，如 `list_platforms` / `list_accounts`——能返回平台列表就算接通。
3. 直连探活（可选）：`curl -s -m 8 http://127.0.0.1:5832/health`
   - `connection refused` → 客户端没在运行；
   - 返回 `未授权：缺少 Bearer token` → 服务已在监听（缺 token 才会 401），说明地址端口是对的。
4. 报 `login_required` /「生成草稿需要先登录榕树账号」→ 这是**客户端账号未登录**，与 MCP 配置无关，只能由用户在客户端登录，不要反复重试。

## 常见问题

**Q：报 401 未授权，但接口地址明明是对的？**
A：token 失效或写错了。去「设置 → API 与 MCP」重新生成，然后**更新 Agent 配置里的 env**——旧 token 不会自动同步。

**Q：工具列表里没有 banyan？**
A：三种常见原因：配置写进了错误的 profile / 作用域（如 Claude Code 用了 `local` 却在别的目录启动）、配置格式没被解析（JSON 有注释或语法错误）、或改完没重启会话。

**Q：`fetch failed` 是什么意思？**
A：MCP 代理连不上榕树本地 API——客户端没启动或正在启动。等它就绪后重试即可，不是配置错。

**Q：多位作家 / 多个 Agent 怎么办？**
A：每位用各自的 token、各自的 server 名（如 `banyan-<名字>`），互不干扰；共用 token 会让写操作落到同一个身份上。

**Q：可以把 token 直接写进 SKILL.md 吗？**
A：不可以。SKILL.md 会被安装、复制、可能被提交到仓库或分享给别人；token 只进 Agent 的 MCP 配置（`--env` / `env` 字段）。泄露后立即在客户端重新生成。