1.3 远程服务器：streamable-http

什么时候用 HTTP

服务器不在你机器上，而是别人托管好的服务。典型如 Notion、Slack、Sentry、Stripe 的官方端点。

优势很明显：不用装任何东西，通常走 OAuth 授权，权限跟着你已有的账号体系走。对团队来说，这意味着不用在每台开发机上配置同一套密钥——权限在云端账号里统一管。

前提只有一条，但很硬：上游服务必须已经运行。 DSH 不会替你把远程服务拉起来，它只负责连过去。

配置形状

远程服务器改用 transport: streamable-http、url 和 headers：

- insert:
    - id: notion
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: notion
        transport: streamable-http
        url: https://mcp.notion.com/mcp
        headers: {}

需要带令牌时写 headers：

        headers:
          Authorization: !!js "'Bearer ' + process.env.MY_TOKEN"

注意那个字符串拼接：Authorization 头的值必须是完整字符串，用 !!js 从环境拼出来，别把 token 明文写进 YAML。这一点和 stdio 的 config.env 写法不同，但“密钥不进 YAML”的纪律完全一致。

已核验的官方远程端点

服务 端点 说明
Notion https://mcp.notion.com/mcp 官方
Slack https://mcp.slack.com/mcp 官方
Sentry https://mcp.sentry.dev/mcp 官方
Stripe https://mcp.stripe.com/mcp 官方
Asana https://mcp.asana.com/sse 官方
Exa https://mcp.exa.ai/mcp 官方远程

这些端点无需本地安装，走 OAuth 或 API key。OAuth 类（Notion、Slack、Sentry）在首次连接时由 dsh 引导你在浏览器里授权；API key 类（Exa）则把 key 放进 headers 或对应的环境变量。

OAuth 与 API key 两种鉴权

远程端点分两类鉴权，配置姿势不同：

鉴权方式 例子 你在 YAML 里做什么
OAuth Notion、Slack、Sentry、Stripe 只写 url，首次连接走浏览器授权
API key / Bearer Exa、自建服务 把 key 拼进 headers，用 !!js 读环境

OAuth 的好处是密钥完全不碰你的配置文件——授权后由服务商返回一个短期令牌，过期自动续。API key 则需要你自己在 headers 里接好，务必用 !!js 从环境读取，不要硬编码。

与 stdio 的对比

维度 stdio streamable-http
服务器位置 本机 远程
安装 需要 不需要
启停 DSH 管 DSH 不管
凭据 config.env headers / OAuth
隔离性 进程级隔离 依赖服务商
网络依赖 无 必须有
离线可用 是 否

选型很简单：本地工具用 stdio，云端服务用 HTTP。 如果你部署了一个自建 MCP 服务在局域网或云上，它也走 HTTP——此时“上游必须已在运行”这条前提由你自己保证。

什么时候 HTTP 不合适

反过来也要知道边界：

场景 更该用 stdio
处理本机文件、本机数据库 远程服务器够不着本机资源
对延迟极度敏感、数据不出本机 走网络多一跳且数据出网
没有稳定可访问的远端服务 自己没部署就别选 HTTP

一句话：HTTP 适合“服务已经在外面”，stdio 适合“能力装在我机器上”。两者不是优劣关系，是位置决定的。

排错要点

HTTP 场景的失败模式和 stdio 不同：

现象 原因
一直连不上 上游未运行 / 网络不通 / 需要代理
401 / 403 令牌缺失或过期，检查 headers
工具列出来但调用失败 账号权限不足（如 Notion 页面没共享给集成）
时断时续 远程服务限流或网络抖动

第三项特别容易忽略：Notion 类的服务，授权之后还要把具体页面共享给集成，否则工具能列出来、一调用就报无权限。Slack 同理——频道要先把对应 App 邀请进去。

小结

  • HTTP 用于远程托管服务器，无需本地安装，但上游必须已在运行。
  • 三个字段：url + headers + transport: streamable-http。
  • OAuth 只写 url 走浏览器授权；API key 用 !!js 拼进 headers，不写明文。
  • HTTP 失败多与网络、令牌、账号权限三者相关，逐个排除。

延伸阅读