Windsurf MCP 教程笔记：架构和接 Slack

MCP 听起来像又一个协议缩写，落到 Windsurf 里其实就一件事：让 Cascade（或现在的 Devin Local）能调用编辑器之外的工具。Slack 是官方教程里最常拿来演示的例子，配好之后，Agent 可以搜频道、读线程、把改动摘要发回工作区。下面按「架构先搞清，配置文件别写错路径，再接 Slack」走一遍。

MCP 在 Windsurf 里扮演什么角色

MCP（Model Context Protocol）把模型和外部系统拆开：客户端负责发现工具、发起调用；服务器负责真正去查 GitHub、查数据库、读写 Slack。Windsurf 这边的客户端是 Cascade；服务器可以是本机进程，也可以是远端 HTTP 端点。

官方文档写得很直白：Cascade 向 MCP 服务器发请求，用服务器暴露的 tools、resources、prompts。Enterprise 用户要在设置里手动打开 MCP。

对日常写代码的人，核心价值就三条：

• 不用给模型塞整段 API 文档。工具列表由服务器动态声明。
• 权限边界在服务器一侧。Slack 服务器只能做你给它的 OAuth scope，文件系统服务器只能碰到你写进 args 的目录。
• 同一套服务器可以接到 Cursor、Claude Code、Windsurf，换客户端不用重写业务。

架构：Host、Client、三种传输

可以把它想成三层：

传输有三种，文档写在 Cascade MCP：

1. stdio：本机起一个进程，stdin/stdout 说话。npx 和 Docker 交互式进程都是这条路。Slack 早期教程也是这条。
2. Streamable HTTP：远端服务器，配置里写 serverUrl（注意不是 Cursor 那套 url，抄错了会静默失败）。Slack 官方现在走这条，端点是 https://mcp.slack.com/mcp。
3. SSE：旧的远端传输，Windsurf 仍支持，新服务优先 HTTP。

三种传输都支持 OAuth。HTTP 服务器的 URL 一般长得像 https://example.com/mcp。

还有一个容易踩的坑：Cascade 任意时刻最多能看到 100 个工具。Slack 加上 GitHub、Postgres 再加几个社区服务器，工具数会很快顶满。每个 MCP 的设置页可以单独开关工具，用不到的关掉。

配置文件写在哪

Cascade 读的是：

Windows 对应 %USERPROFILE%\.codeium\windsurf\mcp_config.json。目录名还留着 Codeium，别写成 ~/.windsurf/。

2026 年编辑器这边还有一层变化：新标签默认可能是 Devin Local，不是 Cascade。官方 MCP 页写得很清楚：该页配置只作用于 legacy Cascade；Devin Local 跟 Devin CLI 共用另一套文件：

密钥放 local 那份。看左下角 Agent 选择器确认自己在用哪一个，别改完 Cascade 的文件却在 Devin Local 里干等。

JSON 语法错了，整份配置会静默失效，没有大红报错。改完用校验器扫一眼，再完全退出编辑器重开。

先走 Marketplace，找不到再手写

Cascade 面板右上角有 MCPs 图标，设置路径是 Windsurf Settings > Cascade > MCP Servers。列表里带蓝色对勾的是官方服务器，点 Install 就行。

Marketplace 没有的，再编辑 mcp_config.json。结构是顶层一个 mcpServers 对象，每个 key 是服务器名字。本机 stdio 服务器用 command 加 args，密钥放 env，不要写进会提交的文件。

远端 HTTP 不要抄 Cursor 的 url 字段，Windsurf 要 serverUrl：

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "https://example.com/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

command、args、env、serverUrl、url、headers 都支持插值：${env:VAR_NAME} 读环境变量，${file:~/.secrets/key.txt} 读文件。

接 Slack：两条路

路一：官方文档里的本机 stdio（适合先跑通）

Windsurf 文档给的 Slack 示例是本机起一个服务器。command 用 npx，再配上文档里的官方包名：

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "<YOUR_SLACK_BOT_TOKEN>",
        "SLACK_TEAM_ID": "<YOUR_SLACK_TEAM_ID>"
      }
    }
  }
}

旧的 community slack 包已经停更，新配优先用文档里的 @anthropic/mcp-server-slack。

准备步骤：到 api.slack.com/apps 用 From scratch 建应用，选工作区。在 OAuth 权限里给 channels:read、channels:history、chat:write、users:read。私频道或私信再加 groups:history 和 im:history。装到工作区后复制 Bot User 凭证，Team ID 以 T 开头。机器人进不了没邀请过的频道，到目标频道邀请它。

改完配置后完全退出 Windsurf 再打开。Cascade 的 MCP 面板里 Slack 应显示已连接。先让它列出公开频道，再让它摘要某个频道最近二十条，能读到历史就算通了。

路二：Slack 官方远程 MCP（2026 更稳的生产向）

Slack 自己托管了一套 MCP，传输是 JSON-RPC 2.0 over Streamable HTTP，端点固定为 https://mcp.slack.com/mcp 。

它不支持 SSE，也不做 Dynamic Client Registration。客户端必须绑一个有固定 App ID 的 Slack 应用（Marketplace 上架的，或 Internal App），方便管理员审批、记审计日志、套速率限制。

能力比早期 stdio 包完整：搜消息和文件、读写频道和线程、发消息或草稿、建频道、加 reaction、读写 Canvas、查用户和成员。每类动作走 Slack Web API 同一套 rate limit，例如搜用户或频道大约 Tier 2（每分钟 20+），读频道或线程是 Tier 3（每分钟 50+）。

在 Windsurf 里可以写成：

{
  "mcpServers": {
    "slack": {
      "serverUrl": "https://mcp.slack.com/mcp"
    }
  }
}

保存后走授权流程。Slack 会按工具要不同的 user scope，和 Bot 凭证不是同一套。常见对应：

官方目前列出的现成客户端是 Claude.ai、Claude Code、Perplexity、Cursor。Windsurf 和 Devin Local 走 serverUrl 加授权也能连，但工作区管理员要先批准这个客户端。公司 Slack 打不开授权页，多半是这一步没过，不是 JSON 写错。

Devin CLI 可以先 add 这个远端地址，再单独做一次授权。CLI 和桌面客户端的授权会话是分开的，在 Cursor 里登过不等于 Devin 里已经登过。

实战：让 Agent 围着一个频道转

配置亮绿灯之后，别一上来就「帮我看遍整个工作区」。先钉一个频道 ID（频道名右键，查看频道详情，最底下那串 C 开头的 ID），把任务写具体：

1. 读需求再改代码。 「去 #product 把昨天关于登录超时的讨论摘要出来，对照 src/auth/ 看现在代码差在哪。」Cascade 会先调 Slack 工具拿历史，再碰仓库。
2. 改完回写。 「把这次 diff 的要点发到 #eng，不要群发提醒，提一句 PR 编号就行。」
3. 搜决策。 「搜索 rate limit 429 相关消息，只看过去 30 天，列出结论和发言人。」官方远程 MCP 的 search 工具带日期和用户过滤，比把频道历史整段塞进上下文干净。

Devin Local 默认每次调 MCP 都会问你。信任这个 Slack 服务器之后，可以按服务器或按工具做成当前会话或永久允许，省得每条消息点一次。

常见翻车

• 服务器连上了但读不到频道。 机器人没被邀请，或用了 Bot 凭证却去读私频道。stdio 那条路必须先邀请机器人。
• 远程 MCP 授权成功，工具是空的。 管理员没批这个客户端，或应用不是 Internal / Marketplace 上架类型。
• Windsurf 里远端服务器完全没出现。 配置写成了 url 而不是 serverUrl；Teams / Enterprise 还可能被管理员关掉远程传输。
• 工具突然消失。 超过 100 个工具上限，或 JSON 改坏了整份配置被丢掉。
• 凭证写进了会提交的文件。 用环境变量插值或 .devin/mcp_config.local.json。

本机 stdio 服务器等于在你的用户权限下跑任意代码。只装官方或你审查过的包，不要把来路不明的 npx 命令写进配置。

相关链接

• Windsurf Cascade MCP：https://docs.windsurf.com/windsurf/cascade/mcp
• 中文版同一页：https://docs.windsurf.com/zh/windsurf/cascade/mcp
• Devin Local 与 Cascade 的差异（含 MCP 配置范围）：https://docs.windsurf.com/windsurf/devin-local
• Devin CLI 的 MCP 配置：https://docs.devin.ai/cli/extensibility/mcp/configuration
• Slack 官方 MCP：https://docs.slack.dev/ai/slack-mcp-server
• 建 Slack 应用：https://api.slack.com/apps
• MCP 协议说明：https://modelcontextprotocol.io

先把 Marketplace 或 stdio 示例跑通，确认 Cascade 能列出频道，再决定要不要切到 Slack 官方远程端点。架构弄清楚之后，接 GitHub、Postgres 也是同一份 mcpServers 再加一个 key。