Papyrus.
go-mcp / mcp-server/Transport.md

Transport

最后更新 2026-06-24

Transport

1. StdioTransport（服务端：当前进程 stdin/stdout）

本地 MCP 宿主（如 IDE）拉起进程后，通过管道与 stdin/stdout 通信。

package main

import (
    "context"
    "log"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
    s := mcp.NewServer(&mcp.Implementation{Name: "demo", Version: "1.0"}, nil)
    // … AddTool / AddResource 等
    if err := s.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

2. StreamableHTTPHandler + StreamableClientTransport（推荐：Streamable HTTP）

服务端：同一 MCP 路径上处理 POST（及规范允许的 GET/DELETE）。客户端填 MCP 端点 URL。

package main

import (
    "context"
    "log"
    "net/http"
    "net/http/httptest"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
    // 服务端代码
    ctx := context.Background()
    srv := mcp.NewServer(&mcp.Implementation{Name: "http-srv", Version: "1"}, nil)

    h := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return srv }, &mcp.StreamableHTTPOptions{
        JSONResponse: true, // 示例：纯 JSON、无 SSE，便于 curl/打印；生产可改为 false
    })
    ts := httptest.NewServer(h)
    defer ts.Close()

    // 客户端代码
    c := mcp.NewClient(&mcp.Implementation{Name: "http-cli", Version: "1"}, nil)
    t := &mcp.StreamableClientTransport{
        Endpoint:             ts.URL,
        DisableStandaloneSSE: true, // 与 JSONResponse 搭配；需服务端主动下行时再设为 false
    }
    sess, err := c.Connect(ctx, t, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer sess.Close()
    // sess.CallTool …
}

stdio、HTTP 与 SSE

MCP 的传输方式归纳下来就 两种：

  1. stdio：本地进程通信
  2. Streamable HTTP：远程网络通信

日常提到的 「HTTP」和「SSE」 其实都属于 Streamable HTTP 这一套机制：用 POST/GET 来发送请求和接收响应，用 SSE（text/event-stream）来实现服务端向客户端的实时推送。它们不是独立的传输方式，而是远程场景下同一套方案的两个层面。

stdio：本地进程通信

客户端 将 MCP Server 作为子进程启动，通过操作系统的管道进行通信。

方向 说明
Client → Server 通过 stdin 发送 MCP 消息；每条消息必须是一行完整的 UTF-8 JSON-RPC；换行符作为消息边界，消息体中不能包含未转义的换行。
Server → Client 从 stdout 输出 MCP 消息；这个输出流 仅限于协议消息，混入其他内容会导致客户端解析失败。
stderr Server 可以向 stderr 输出日志（调试、错误等）；客户端通常会忽略或单独收集；stderr 出现不一定表示协议故障。
生命周期 关闭子进程的 stdin 或直接终止子进程即断开连接。

HTTP / SSE：远程网络通信

Server 作为 独立的网络服务运行，可以接受多个客户端的并发连接。通常只有一个 MCP 路由端点，既支持 POST（客户端请求）也支持 GET（客户端拉取或开启事件流）。

SSE 本质是 HTTP 的一种响应格式：Content-Type: text/event-stream，遵循 HTML5 标准中的 Server-sent events 规范，用 event / data / id / retry 这样的字段格式传输数据。

实际工作流程：

  • 下行流式传输：一个客户端请求对应一条 SSE 连接；Server 在这条连接上可以先发送 notifications 或服务端主动的 requests，最后才返回对客户端原始请求的 response。
  • 自动重连：事件可以携带 id 字段；当连接断开时，客户端用 Last-Event-ID 请求续传，实现断线重连。
  • 连接管理：Server 可以主动关闭连接，并通过 retry 告诉客户端多久后重新连接。这样做能避免长连接一直占用服务端资源。