mcp-go 开发实战指南:用 Go 构建高性能 Model Context Protocol 服务器

原创2026-09-24 17:44:271,427 阅读
文章标签:人工智能大模型工具调用MCP 服务MCP Clients

mcp-go 开发实战指南:用 Go 构建高性能 Model Context Protocol 服务器

导读:本文以 mcp-go 开源仓库(README.md)为主线,系统讲解如何用 Go 语言构建符合 Model Context Protocol(MCP)规范的服务器。你将掌握从安装、创建服务器、注册资源/工具/提示,到任务增强工具、会话管理、请求钩子、中间件、自动补全与代码生成等进阶能力,并透过仓库源码(server/、mcp/、client/ 等目录)理解底层实现原理,最终能够独立交付一个可运行的 MCP 服务。

一、mcp-go 是什么

mcp-go 是 Model Context Protocol 的 Go 语言实现,它让 LLM 应用与外部数据源、工具之间实现无缝集成。与直接用 net/http 手写协议处理不同,mcp-go 把复杂的协议细节和服务器管理封装在高层接口之下——正如 README.md 所述:"MCP Go handles all the complex protocol details and server management, so you can focus on building great tools",它的设计目标是高层、易用。

核心特性(来自 README.md):

  • Fast:高层接口意味着更少的代码、更快的开发速度;
  • Simple:用极少的样板代码构建 MCP 服务器;
  • Complete:目标是提供 MCP 核心规范的完整实现(注意是"aims",即仍在完善中)。

需要说明的是,mcp-go 与 MCP 规范本身一样处于积极开发中,核心功能可用,部分高级能力仍在推进(见 README.md 中的开发状态声明)。同时,仓库在 mcp/version.go 中明确支持多个协议版本:当前最新支持 2026-07-28(stateless 协议核心,无 initialize 握手、引入 server/discover、subscriptions/listen 与多轮往返请求),同时向下兼容 2025-11-25、2025-06-18、2025-03-26、2024-11-05 等历史版本;LATEST_LEGACY_PROTOCOL_VERSION 为 2025-11-25,即仍走 initialize/initialized 握手的最高版本。

二、安装与第一个服务器

2.1 安装

go get github.com/mark3labs/mcp-go

仓库的 go.mod 定义了依赖关系,安装后即可在代码中导入:

import (
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

其中 mcp 包提供协议类型、工具/资源/提示的构造器与结果类型;server 包提供服务器主体、传输层与各类 ServerOption。

2.2 最小可运行服务器

README.md 给出了一个 hello_world 示例,完整代码如下:

package main

import (
    "context"
    "fmt"

    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Demo 🚀",
        "1.0.0",
        server.WithToolCapabilities(false),
    )

    // Add tool
    tool := mcp.NewTool("hello_world",
        mcp.WithDescription("Say hello to someone"),
        mcp.WithString("name",
            mcp.Required(),
            mcp.Description("Name of the person to greet"),
        ),
    )

    // Add tool handler
    s.AddTool(tool, helloHandler)

    // Start the stdio server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}

func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    name, err := request.RequireString("name")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }

    return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil
}

几个关键点需要展开说明:

  • server.NewMCPServer(name, version, opts...) 是服务器构造入口,实现在 server/server.go:内部初始化各类 map(resources、resourceTemplates、prompts、tools、taskTools 等)、默认 completion provider 与 tracing.NoopTracer(),然后按顺序应用所有 ServerOption。name 与 version 会出现在 initialize 响应的 serverInfo 中。
  • mcp.NewTool(name, opts...) 通过函数式选项模式构造工具定义,WithString 声明一个字符串参数,Required() 标记必填,Description 提供参数描述——这些信息会生成 JSON Schema,最终通过 tools/list 暴露给 LLM。
  • request.RequireString("name") 是类型安全的参数读取辅助方法。在 mcp/tools.go 中,它从 GetArguments() 解析出的 map<a href="https://link.gitcode.com/i/4d19ee060f1097ebb6706ae98c6b2687" target="_blank">string]any 中取值并做类型断言:参数缺失或类型不符都会返回错误。同族的辅助方法还有 RequireFloat、RequireInt、GetString、GetInt、GetFloat 等(带默认值版本),以及 BindArguments(target)——后者可以把原始 JSON 参数直接反序列化到强类型结构体(在 [mcp/tools.go 实现,这也是 examples/typed_tools/ 示例的基础)。
  • 返回类型约定:工具自身的错误应该通过 mcp.NewToolResultError 放进 CallToolResult(并置 IsError: true),而不是返回协议级 JSON-RPC 错误。原因见 mcp/tools.go 的注释:只有把错误放进结果里,LLM 才能在上下文中看到失败详情并自我纠正;而"找不到工具""服务器不支持工具调用"等异常情况才应返回 MCP 错误响应。
  • server.ServeStdio(s) 启动基于标准输入/输出的传输,这是 MCP 最常用的本地集成方式。

三、快速上手:完整计算器服务器

README.md 的 Quickstart 展示了更完整的形态——一个暴露计算器工具并具备崩溃恢复能力的服务器:

package main

import (
    "context"
    "fmt"

    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Calculator Demo",
        "1.0.0",
        server.WithToolCapabilities(false),
        server.WithRecovery(),
    )

    // Add a calculator tool
    calculatorTool := mcp.NewTool("calculate",
        mcp.WithDescription("Perform basic arithmetic operations"),
        mcp.WithString("operation",
            mcp.Required(),
            mcp.Description("The operation to perform (add, subtract, multiply, divide)"),
            mcp.Enum("add", "subtract", "multiply", "divide"),
        ),
        mcp.WithNumber("x",
            mcp.Required(),
            mcp.Description("First number"),
        ),
        mcp.WithNumber("y",
            mcp.Required(),
            mcp.Description("Second number"),
        ),
    )

    // Add the calculator handler
    s.AddTool(calculatorTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        // Using helper functions for type-safe argument access
        op, err := request.RequireString("operation")
        if err != nil {
            return mcp.NewToolResultError(err.Error()), nil
        }

        x, err := request.RequireFloat("x")
        if err != nil {
            return mcp.NewToolResultError(err.Error()), nil
        }

        y, err := request.RequireFloat("y")
        if err != nil {
            return mcp.NewToolResultError(err.Error()), nil
        }

        var result float64
        switch op {
        case "add":
            result = x + y
        case "subtract":
            result = x - y
        case "multiply":
            result = x * y
        case "divide":
            if y == 0 {
                return mcp.NewToolResultError("cannot divide by zero"), nil
            }
            result = x / y
        }

        return mcp.NewToolResultText(fmt.Sprintf("%.2f", result)), nil
    })

    // Start the server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}

相比最小示例,这里引入了两个值得注意的能力:

  1. mcp.Enum(...) 参数约束:为 operation 声明合法取值集合,LLM 在调用前就能知道可选值,降低无效调用的概率。
  2. server.WithRecovery():这是一个内置的工具处理器中间件,实现在 server/server.go。它用 defer + recover() 包裹工具处理器,一旦 handler 内部 panic,会把 panic 转换为格式化的 error(panic recovered in %s tool handler: %v)返回,而不是让整个进程崩溃。仓库还提供对应的资源处理器恢复选项 WithResourceRecovery(见 server/server.go)。

这个 Quickstart 示例完整代码可运行,建议作为新建 MCP 服务器的起步模板。

四、理解 MCP 三大核心概念

README.md 用一个类比帮助理解 MCP 的角色:它就像"专门为 LLM 交互设计的 Web API"。MCP 服务器可以:

  • 通过 Resources 暴露数据(类似 GET 端点,用于把信息加载进 LLM 上下文);
  • 通过 Tools 提供功能(类似 POST 端点,用于执行代码或产生副作用);
  • 通过 Prompts 定义交互模式(可复用的 LLM 交互模板)。

mcp-go 实现的协议版本为 2025-11-25(当前仓库还进一步支持 2026-07-28 现代协议核心,见 mcp/version.go),并向后兼容 2025-06-18、2025-03-26、2024-11-05。

4.1 Server:协议核心接口

服务器是 MCP 协议的核心接口,负责连接管理、协议合规与消息路由。创建一个基本服务器只需两行:

// Create a basic server
s := server.NewMCPServer(
    "My Server",  // Server name
    "1.0.0",     // Version
)

// Start the server using stdio
if err := server.ServeStdio(s); err != nil {
    log.Fatalf("Server error: %v", err)
}

从源码结构看(server/server.go),MCPServer 内部为不同资源类型分别维护了互斥锁(resourcesMu、promptsMu、toolsMu、toolMiddlewareMu 等),并用 sync.Map 管理会话、用 tasks map 管理任务状态,说明其并发模型是经过专门设计的,适合承载多客户端同时访问。

4.2 Resources:向 LLM 暴露数据

Resources 是暴露数据给 LLM 的方式,可以是文件、API 响应、数据库查询、系统信息等任何内容,分为两类:

  • 静态资源:固定 URI;
  • 动态资源:使用 URI 模板。

静态资源示例(暴露 README 文件):

// Static resource example - exposing a README file
resource := mcp.NewResource(
    "docs://readme",
    "Project README",
    mcp.WithResourceDescription("The project's README file"),
    mcp.WithMIMEType("text/markdown"),
)

// Add resource with its handler
s.AddResource(resource, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    content, err := os.ReadFile("README.md")
    if err != nil {
        return nil, err
    }

    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      "docs://readme",
            MIMEType: "text/markdown",
            Text:     string(content),
        },
    }, nil
})

mcp.NewResource(uri, name, opts...) 的实现在 mcp/resources.go,除 WithResourceDescription、WithMIMEType 外,还支持 WithResourceTitle(客户端展示优先用 Title)、WithResourceSize(原始内容字节数,负数会被忽略)、WithAnnotations(audience/priority/lastModified)与 WithLastModified(ISO 8601/RFC3339 时间戳)等选项(见 mcp/resources.go)。

动态资源示例(用户档案按 ID 查询):

// Dynamic resource example - user profiles by ID
template := mcp.NewResourceTemplate(
    "users://{id}/profile",
    "User Profile",
    mcp.WithTemplateDescription("Returns user profile information"),
    mcp.WithTemplateMIMEType("application/json"),
)

// Add template with its handler
s.AddResourceTemplate(template, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    // Extract ID from the URI using regex matching
    // The server automatically matches URIs to templates
    userID := extractIDFromURI(request.Params.URI)

    profile, err := getUserProfile(userID)  // Your DB/API call here
    if err != nil {
        return nil, err
    }

    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      request.Params.URI,
            MIMEType: "application/json",
            Text:     profile,
        },
    }, nil
})

NewResourceTemplate 内部使用 uritemplate 库编译模板(mcp/resources.go),服务器会自动把客户端请求的 URI 与模板做匹配,再回调对应的 handler。README 同时提示:资源可以远比示例复杂,例如一次返回多个 content、集成数据库或外部 API 等。

4.3 Tools:让 LLM 采取行动

Tools 让 LLM 通过服务器采取行动。与资源不同,工具预期执行计算并产生副作用,类比 REST API 的 POST 端点。除了 4.2 中的参数辅助方法外,README 还展示了两种工具处理器写法。

方式一:直接读取参数 map(README.md 中的计算器变体):

s.AddTool(calculatorTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args := request.GetArguments()
    op := args["operation"].(string)
    x := args["x"].(float64)
    y := args["y"].(float64)

    var result float64
    switch op {
    case "add":
        result = x + y
    case "subtract":
        result = x - y
    case "multiply":
        result = x * y
    case "divide":
        if y == 0 {
            return mcp.NewToolResultError("cannot divide by zero"), nil
        }
        result = x / y
    }

    return mcp.FormatNumberResult(result), nil
})

这里出现了 mcp.FormatNumberResult(result),它把数值自动包装为合适的文本结果。GetArguments() 在 mcp/tools.go 中实现——若 Arguments 是 map[string]any 则返回它,否则返回 nil,因此直接类型断言前应确保参数存在。

方式二:发起 HTTP 请求的工具(README.md):

httpTool := mcp.NewTool("http_request",
    mcp.WithDescription("Make HTTP requests to external APIs"),
    mcp.WithString("method",
        mcp.Required(),
        mcp.Description("HTTP method to use"),
        mcp.Enum("GET", "POST", "PUT", "DELETE"),
    ),
    mcp.WithString("url",
        mcp.Required(),
        mcp.Description("URL to send the request to"),
        mcp.Pattern("^https?://.*"),
    ),
    mcp.WithString("body",
        mcp.Description("Request body (for POST/PUT)"),
    ),
)

s.AddTool(httpTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args := request.GetArguments()
    method := args["method"].(string)
    url := args["url"].(string)
    body := ""
    if b, ok := args["body"].(string); ok {
        body = b
    }

    // Create and send request
    var req *http.Request
    var err error
    if body != "" {
        req, err = http.NewRequest(method, url, strings.NewReader(body))
    } else {
        req, err = http.NewRequest(method, url, nil)
    }
    if err != nil {
        return mcp.NewToolResultErrorFromErr("unable to create request", err), nil
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return mcp.NewToolResultErrorFromErr("unable to execute request", err), nil
    }
    defer resp.Body.Close()

    // Return response
    respBody, err := io.ReadAll(resp.Body)
    if err != nil {
        return mcp.NewToolResultErrorFromErr("unable to read request response", err), nil
    }

    return mcp.NewToolResultText(fmt.Sprintf("Status: %d\nBody: %s", resp.StatusCode, string(respBody))), nil
})

这里新引入了 mcp.Pattern("^https?://.*")(正则约束 url 格式)与 mcp.NewToolResultErrorFromErr(prefix, err)(把 error 包装进结果)。工具可用于数据库查询、文件操作、外部 API 调用、计算、系统操作等任意场景。README 给出的设计准则(见 README.md)值得每一位开发者遵守:每个工具都应有清晰描述、校验输入、优雅处理错误、返回结构化响应、使用合适的结果类型。

4.4 Prompts:可复用交互模板

Prompts 是"编码进服务器的最佳实践",帮助 LLM 更有效地与服务器交互。三个典型示例来自 README.md:

示例一:问候提示——带默认值处理:

s.AddPrompt(mcp.NewPrompt("greeting",
    mcp.WithPromptDescription("A friendly greeting prompt"),
    mcp.WithArgument("name",
        mcp.ArgumentDescription("Name of the person to greet"),
    ),
), func(ctx context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    name := request.Params.Arguments["name"]
    if name == "" {
        name = "friend"
    }

    return mcp.NewGetPromptResult(
        "A friendly greeting",
        []mcp.PromptMessage{
            mcp.NewPromptMessage(
                mcp.RoleAssistant,
                mcp.NewTextContent(fmt.Sprintf("Hello, %s! How can I help you today?", name)),
            ),
        },
    ), nil
})

示例二:代码评审提示——带必填参数与内嵌资源:

s.AddPrompt(mcp.NewPrompt("code_review",
    mcp.WithPromptDescription("Code review assistance"),
    mcp.WithArgument("pr_number",
        mcp.ArgumentDescription("Pull request number to review"),
        mcp.RequiredArgument(),
    ),
), func(ctx context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    prNumber := request.Params.Arguments["pr_number"]
    if prNumber == "" {
        return nil, fmt.Errorf("pr_number is required")
    }

    return mcp.NewGetPromptResult(
        "Code review assistance",
        []mcp.PromptMessage{
            mcp.NewPromptMessage(
                mcp.RoleUser,
                mcp.NewTextContent("Review the changes and provide constructive feedback."),
            ),
            mcp.NewPromptMessage(
                mcp.RoleAssistant,
                mcp.NewEmbeddedResource(mcp.ResourceContents{
                    URI: fmt.Sprintf("git://pulls/%s/diff", prNumber),
                    MIMEType: "text/x-diff",
                }),
            ),
        },
    ), nil
})

示例三:SQL 查询构建提示——多个 user 角色消息并内嵌数据库 schema 资源:

s.AddPrompt(mcp.NewPrompt("query_builder",
    mcp.WithPromptDescription("SQL query builder assistance"),
    mcp.WithArgument("table",
        mcp.ArgumentDescription("Name of the table to query"),
        mcp.RequiredArgument(),
    ),
), func(ctx context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    tableName := request.Params.Arguments["table"]
    if tableName == "" {
        return nil, fmt.Errorf("table name is required")
    }

    return mcp.NewGetPromptResult(
        "SQL query builder assistance",
        []mcp.PromptMessage{
            mcp.NewPromptMessage(
                mcp.RoleUser,
                mcp.NewTextContent("Help construct efficient and safe queries for the provided schema."),
            ),
            mcp.NewPromptMessage(
                mcp.RoleUser,
                mcp.NewEmbeddedResource(mcp.ResourceContents{
                    URI: fmt.Sprintf("db://schema/%s", tableName),
                    MIMEType: "application/json",
                }),
            ),
        },
    ), nil
})

Prompts 可以包含:系统指令、必填参数、内嵌资源、多条消息、不同内容类型(文本、图片等)、自定义 URI scheme(见 README.md)。

五、进阶:任务增强工具(Task-Augmented Tools)

任务增强工具是 mcp-go 的一大亮点:它们异步执行、通过轮询返回结果,适用于会阻塞或超时的长时间运行操作(见 README.md)。

5.1 三种任务支持模式

模式 说明
TaskSupportForbidden(默认) 工具不能被作为任务调用
TaskSupportOptional 工具既可以作为任务调用,也可以同步调用
TaskSupportRequired 工具必须作为任务调用

任务工具示例(process_batch,必须作为任务执行):

// Example: A tool that requires task execution
processBatchTool := mcp.NewTool("process_batch",
    mcp.WithDescription("Process a batch of items asynchronously"),
    mcp.WithTaskSupport(mcp.TaskSupportRequired),
    mcp.WithArray("items",
        mcp.Description("Array of items to process"),
        mcp.WithStringItems(),
        mcp.Required(),
    ),
)

// Task tool handler returns CreateTaskResult instead of CallToolResult
s.AddTaskTool(processBatchTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    items := request.GetStringSlice("items", []string{})

    // Long-running work here
    for i, item := range items {
        select {
        case <-ctx.Done():
            // Task was cancelled
            return nil, ctx.Err()
        default:
            // Process item...
            processItem(item)
        }
    }

    // Return result - task ID and metadata are managed by the server
    return &mcp.CreateTaskResult{
        Task: mcp.Task{
            // Task fields (ID, status, etc.) are populated by the server
        },
    }, nil
})

// Enable task capabilities when creating the server
s := server.NewMCPServer(
    "Task Server",
    "1.0.0",
    server.WithTaskCapabilities(
        true, // listTasks: allows clients to list all tasks
        true, // cancel: allows clients to cancel running tasks
        true, // toolCallTasks: enables task augmentation for tools
    ),
    server.WithMaxConcurrentTasks(10), // Optional: limit concurrent running tasks
)

注意三点:

  1. 注册方式不同:任务工具使用 s.AddTaskTool 而非 AddTool,handler 签名返回 *mcp.CreateTaskResult 而不是 *mcp.CallToolResult(见 server/server.go 中的 TaskToolHandlerFunc 定义)。
  2. 服务器自动管理任务元数据:Task 的 ID、状态等字段由服务器填充,handler 只需返回空的 mcp.Task{}。
  3. 能力声明:server.WithTaskCapabilities(list, cancel, toolCallTasks) 三个布尔参数分别控制客户端能否列出任务、取消任务、以及是否启用工具的任务增强(实现在 server/server.go)。

任务执行流程(README 明确列出):

  1. 客户端携带 task 参数调用工具;
  2. 服务器立即返回 task ID;
  3. 工具在后台异步执行;
  4. 客户端轮询 tasks/result 获取结果;
  5. 任务完成时服务器发送状态通知。

5.2 可选任务工具(混合模式)

对于 TaskSupportOptional 工具,同一个工具既可以同步调用(不带 task 参数),也可以异步调用(带 task 参数),服务器会自动处理两种调用方式:

// Tool with optional task support
analyzeTool := mcp.NewTool("analyze_data",
    mcp.WithDescription("Analyze data - can run sync or async"),
    mcp.WithTaskSupport(mcp.TaskSupportOptional),
    mcp.WithString("data", mcp.Required()),
)

// Use AddTaskTool for hybrid tools that support both modes
s.AddTaskTool(analyzeTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    // This handler runs when called as a task
    data := request.GetString("data", "")
    result := analyzeData(data)

    return &mcp.CreateTaskResult{
        Task: mcp.Task{},
    }, nil
})

// The server automatically handles both sync and async invocations
// When called without task param: executes handler and returns immediately
// When called with task param: executes handler asynchronously

5.3 限制并发任务数

为防止资源耗尽,可以用 WithMaxConcurrentTasks 限制并发运行的任务数量:

s := server.NewMCPServer(
    "Task Server",
    "1.0.0",
    server.WithTaskCapabilities(true, true, true),
    server.WithMaxConcurrentTasks(10), // Allow up to 10 concurrent running tasks
)

限制说明(来自 README.md 与 server/server.go):

  • 达到上限后,新的任务创建请求会失败并返回错误;
  • 已完成、失败或已取消的任务不计入限制,只有处于 "working" 状态的任务才算;
  • 若未指定或设为 0,则并发任务数不受限制。

六、传输层(Transports)与 HTTP 增强能力

6.1 支持的传输方式

mcp-go 支持三种传输层:stdio、SSE 和 streamable HTTP(见 README.md)。其中:

  • stdio:通过标准输入/输出通信,server.ServeStdio(s) 直接启动;
  • SSE:服务器推送事件流;README 提示可以使用 SetConnectionLostHandler() 检测并处理断连,以实现重连逻辑;
  • Streamable HTTP:基于 HTTP 的现代传输。

客户端侧对应的传输实现在 client/transport/ 目录下(stdio.go、sse.go、streamable_http.go 等),服务器侧在 server/ 目录下(stdio.go、sse.go、streamable_http.go)。

6.2 嵌入非 net/http 框架(fasthttp/fiber 等)

StreamableHTTPServer 本身就是一个 http.Handler,可以挂载到任何走 net/http 的路由器上。对于不走 net/http 的框架(如 fasthttp、fiber),若想避免通过适配器缓冲响应,可以使用传输无关的 Handle 入口(见 README.md):

func (s *StreamableHTTPServer) Handle(w HTTPResponseWriter, r *HTTPRequest)
  • HTTPRequest 是一个普通结构体,包含 Method、URL、Header、Body、Context 字段(实现在 server/streamable_http_handle.go),Body 会被完整缓冲,适配器无需在整个流式响应期间保持 io.Reader 存活;
  • HTTPResponseWriter 是一个小型接口(Header、WriteHeader、Write、Flush、CanStream)。底层传输无法流式输出的实现必须让 CanStream 返回 false,此时服务器会对 GET(SSE 监听)请求返回 405 Method Not Allowed,并把 POST 响应保持为缓冲的 application/json 而不是升级为 text/event-stream;
  • 通过 ServeHTTP 进入的请求仍保留原有的 net/http 语义,ServeHTTP 未改变。

6.3 OAuth 受保护资源元数据(RFC 9728)

需要 OAuth 的服务器可以通过 /.well-known/oauth-protected-resource 端点通告授权要求。使用 server.WithProtectedResourceMetadata(或 SSE 版本的 server.WithSSEProtectedResourceMetadata)自动挂载该端点,或用 server.NewProtectedResourceMetadataHandler 把它接入自定义路由器(见 README.md):

httpServer := server.NewStreamableHTTPServer(mcpServer,
    server.WithProtectedResourceMetadata(server.ProtectedResourceMetadataConfig{
        Resource:             "https://my-mcp-server.com",
        AuthorizationServers: []string{"https://auth.example.com"},
        ScopesSupported:      []string{"mcp:read", "mcp:write"},
    }),
)

6.4 CORS:面向浏览器客户端

暴露给浏览器 MCP 客户端的服务器可以开启跨域资源共享处理。CORS 默认关闭,需显式配置(见 README.md):

httpServer := server.NewStreamableHTTPServer(mcpServer,
    server.WithEndpointPath("/mcp"),
    server.WithStreamableHTTPCORS(
        server.WithCORSAllowedOrigins("https://my-ai-app.com", "http://localhost:3000"),
        server.WithCORSAllowCredentials(),
        server.WithCORSMaxAge(300),
    ),
)

行为细节:

  • 传输层直接应答预检(OPTIONS)请求,并给简单响应加上 Access-Control-Allow-Origin、Access-Control-Allow-Credentials、Access-Control-Expose-Headers 和 Vary 头;
  • 省略相应选项时使用合理默认值:方法为 GET, POST, DELETE, OPTIONS;请求头为 Content-Type, Mcp-Session-Id, Last-Event-ID, Authorization;暴露头为 Mcp-Session-Id(均见 README.md);
  • 把 WithCORSAllowedOrigins("*") 与 WithCORSAllowCredentials() 组合使用时,会回显请求的 Origin 以保持规范兼容。

6.5 DNS 重绑定防护(localhost 服务器)

两种 HTTP 传输都会自动保护本地服务器免受 DNS 重绑定攻击(见 README.md):

  • 经回环连接(127.0.0.1、[::1])到达、但 Host 头不是 localhost 值的请求会被拒绝,返回 403 Forbidden;
  • 该检查基于连接本地地址在运行时推导,因此无论服务器监听 localhost 还是 0.0.0.0 都适用,且绝不影响经非回环地址到达的请求;
  • 若同机反向代理经由 localhost 转发请求但保留了原始 Host 头,可配置代理把 Host 重写为 localhost,或显式退出防护:
httpServer := server.NewStreamableHTTPServer(mcpServer,
    // Or server.WithSSEDisableLocalhostProtection(true) on NewSSEServer.
    server.WithDisableLocalhostProtection(true),
)

七、会话管理(Session Management)

mcp-go 提供健壮的会话管理系统(见 README.md),支持:

  • 为每个连接的客户端维护独立状态;
  • 注册与跟踪客户端会话;
  • 向特定客户端发送通知;
  • 提供按会话定制的工具。

7.1 基本会话处理

// Create a server with session capabilities
s := server.NewMCPServer(
    "Session Demo",
    "1.0.0",
    server.WithToolCapabilities(true),
)

// Implement your own ClientSession
type MySession struct {
    id           string
    notifChannel chan mcp.JSONRPCNotification
    isInitialized bool
    // Add custom fields for your application
}

// Implement the ClientSession interface
func (s *MySession) SessionID() string {
    return s.id
}

func (s *MySession) NotificationChannel() chan<- mcp.JSONRPCNotification {
    return s.notifChannel
}

func (s *MySession) Initialize() {
    s.isInitialized = true
}

func (s *MySession) Initialized() bool {
    return s.isInitialized
}

// Register a session
session := &MySession{
    id:           "user-123",
    notifChannel: make(chan mcp.JSONRPCNotification, 10),
}
if err := s.RegisterSession(context.Background(), session); err != nil {
    log.Printf("Failed to register session: %v", err)
}

// Send notification to a specific client
err := s.SendNotificationToSpecificClient(
    session.SessionID(),
    "notification/update",
    map[string]any{"message": "New data available!"},
)
if err != nil {
    log.Printf("Failed to send notification: %v", err)
}

// Unregister session when done
s.UnregisterSession(context.Background(), session.SessionID())

源码层面的关键信息(server/session.go):

  • ClientSession 接口要求实现四个方法:Initialize()、Initialized()、NotificationChannel() chan<- mcp.JSONRPCNotification、SessionID()(server/session.go);
  • RegisterSession 用 LoadOrStore 防止重复注册,若 session ID 已存在会返回 ErrSessionExists(server/session.go);
  • 通知发送使用非阻塞 select 写入 channel:若 channel 阻塞,会通过 OnError 钩子上报 ErrNotificationChannelBlocked,而不会卡死服务器(见 server/session.go 的 sendNotificationToSpecificClient)。

7.2 按会话定制工具(Per-Session Tools)

实现 SessionWithTools 接口即可支持按会话定制工具:

// Implement SessionWithTools interface for per-session tools
type MyAdvancedSession struct {
    MySession  // Embed the basic session
    sessionTools map[string]server.ServerTool
}

// Implement additional methods for SessionWithTools
func (s *MyAdvancedSession) GetSessionTools() map[string]server.ServerTool {
    return s.sessionTools
}

func (s *MyAdvancedSession) SetSessionTools(tools map[string]server.ServerTool) {
    s.sessionTools = tools
}

// Create and register a session with tools support
advSession := &MyAdvancedSession{
    MySession: MySession{
        id:           "user-456",
        notifChannel: make(chan mcp.JSONRPCNotification, 10),
    },
    sessionTools: make(map[string]server.ServerTool),
}
if err := s.RegisterSession(context.Background(), advSession); err != nil {
    log.Printf("Failed to register session: %v", err)
}

// Add session-specific tools
userSpecificTool := mcp.NewTool(
    "user_data",
    mcp.WithDescription("Access user-specific data"),
)
// You can use AddSessionTool (similar to AddTool)
err := s.AddSessionTool(
    advSession.SessionID(),
    userSpecificTool,
    func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        // This handler is only available to this specific session
        return mcp.NewToolResultText("User-specific data for " + advSession.SessionID()), nil
    },
)
if err != nil {
    log.Printf("Failed to add session tool: %v", err)
}

// Delete session-specific tools when no longer needed
err = s.DeleteSessionTools(advSession.SessionID(), "user_data")
if err != nil {
    log.Printf("Failed to delete session tool: %v", err)
}

源码佐证(server/session.go):

  • AddSessionTools 会先加载会话,确认其实现 SessionWithTools(否则返回 ErrSessionDoesNotSupportTools),然后复制现有工具 map、追加新工具、再写回(避免并发修改问题);
  • 若会话已初始化且启用了 tools.listChanged,添加/删除工具后还会向该会话单独发送 notifications/tools/list_changed 通知;
  • GetSessionTools/SetSessionTools 在接口注释中明确要求线程安全(server/session.go)。

7.3 工具过滤(Tool Filtering)

可以对特定会话应用过滤器,控制哪些工具可用。WithToolFilter 在 server/server.go 实现,其注释明确了安全边界:过滤器在 tools/list 和 tools/call 两个阶段都生效,被过滤掉的工具既不能被发现、也不能被调用——过滤器是访问控制边界,而非仅可见性提示。

// Add a tool filter that only shows tools with certain prefixes
s := server.NewMCPServer(
    "Tool Filtering Demo",
    "1.0.0",
    server.WithToolCapabilities(true),
    server.WithToolFilter(func(ctx context.Context, tools []mcp.Tool) []mcp.Tool {
        // Get session from context
        session := server.ClientSessionFromContext(ctx)
        if session == nil {
            return tools // Return all tools if no session
        }

        // Example: filter tools based on session ID prefix
        if strings.HasPrefix(session.SessionID(), "admin-") {
            // Admin users get all tools
            return tools
        } else {
            // Regular users only get tools with "public-" prefix
            var filteredTools []mcp.Tool
            for _, tool := range tools {
                if strings.HasPrefix(tool.Name, "public-") {
                    filteredTools = append(filteredTools, tool)
                }
            }
            return filteredTools
        }
    }),
)

性能细节:tools/list 时过滤器收到完整候选列表;tools/call 时只传入被请求的那一个工具,避免调用时访问检查落在全量列表的热路径上(见 server/server.go 的 ToolFilterFunc 注释)。

7.4 在 Context 中工作

会话上下文会自动传递给工具和资源处理器:

s.AddTool(mcp.NewTool("session_aware"), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Get the current session from context
    session := server.ClientSessionFromContext(ctx)
    if session == nil {
        return mcp.NewToolResultError("No active session"), nil
    }

    return mcp.NewToolResultText("Hello, session " + session.SessionID()), nil
})

// When using handlers in HTTP/SSE servers, you need to pass the context with the session
httpHandler := func(w http.ResponseWriter, r *http.Request) {
    // Get session from somewhere (like a cookie or header)
    session := getSessionFromRequest(r)

    // Add session to context
    ctx := s.WithContext(r.Context(), session)

    // Use this context when handling requests
    // ...
}

ClientSessionFromContext 与 WithContext 的实现见 server/session.go:WithContext 把会话以 context.WithValue 存入 context,之后在任意处理器里用 ClientSessionFromContext 取回。

八、请求钩子与中间件

8.1 请求钩子(Request Hooks)

通过创建 Hooks 对象并选择需要的回调,可以切入请求生命周期,为所有功能提供遥测与可观测性——例如统计格式错误的请求数、在初始化阶段记录 agent 身份(见 README.md)。使用 server.WithHooks 选项在创建服务器时挂载。

server/hooks.go 是 go generate 生成的(源模板在 server/internal/gen/hooks.go.tmpl),提供丰富的钩子类型,包括:

  • OnBeforeAnyHookFunc / OnSuccessHookFunc / OnErrorHookFunc:请求解析后、成功返回后、出错时三个通用时机;
  • 各方法的专用钩子,如 OnBeforeInitializeFunc / OnAfterInitializeFunc、OnBeforeListToolsFunc / OnAfterListToolsFunc、OnBeforeCallToolFunc / OnAfterCallToolFunc、OnBeforeReadResourceFunc / OnAfterReadResourceFunc、OnBeforeGetPromptFunc / OnAfterGetPromptFunc 等;
  • 会话生命周期钩子 OnRegisterSessionHookFunc / OnUnregisterSessionHookFunc。

OnErrorHookFunc 的文档注释(server/hooks.go)演示了用 errors.Is / errors.As 精确处理错误类型(如 ErrResourceNotFound、ErrPromptNotFound、ErrToolNotFound、UnparsableMessageError)的用法,是排查问题的利器。

8.2 工具处理器中间件(Tool Handler Middleware)

用 server.WithToolHandlerMiddleware 为工具调用处理器添加中间件,在服务器创建时注册,每次工具调用都会经过(见 README.md)。WithRecovery 就是这类中间件的一个内置实例(server/server.go)。中间件类型定义与注册见 server/server.go 与 server/server.go,MCPServer.Use(mw...) 方法可以在服务器创建后继续追加中间件(按添加顺序外层优先,与 net/http 约定一致)。

8.3 提示处理器中间件与提示过滤

  • Prompt Handler Middleware:server.WithPromptHandlerMiddleware 在每次 prompts/get 调用时生效(README.md);
  • Prompt Filtering:server.WithPromptFilter 与工具过滤机制相同,但作用于 prompts/list 结果(README.md)。其源码注释(server/server.go)同样强调:过滤器在 prompts/list 与 prompts/get 两个阶段都生效,被过滤的提示既不能被发现也不能被访问。

九、自动补全(Auto-completions)

当用户为特定提示(按名称标识)或资源模板(按 URI 标识)填写参数值时,服务器可以提供上下文相关的建议(见 README.md)。启用方式:创建服务器时使用 server.WithCompletions()。

9.1 补全提供者(Completion Providers)

为提示参数与资源模板参数实现相应接口即可:

type MyPromptCompletionProvider struct{}

func (p *MyPromptCompletionProvider) CompletePromptArgument(
    ctx context.Context,
    promptName string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // Example: provide style suggestions for a "code_review" prompt
    if promptName == "code_review" && argument.Name == "style" {
        styles := []string{"formal", "casual", "technical", "creative"}
        var suggestions []string

        // Filter based on current input
        for _, style := range styles {
            if strings.HasPrefix(style, argument.Value) {
                suggestions = append(suggestions, style)
            }
        }

        return &mcp.Completion{
            Values: suggestions,
        }, nil
    }

    // Return empty suggestions for unhandled cases
    return &mcp.Completion{Values: []string{}}, nil
}

type MyResourceCompletionProvider struct{}

func (p *MyResourceCompletionProvider) CompleteResourceArgument(
    ctx context.Context,
    uri string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // Example: provide file path completions
    if uri == "file:///{path}" && argument.Name == "path" {
        // You can access previously completed arguments from context.Arguments
        // context.Arguments is a map[string]string of already-resolved arguments

        paths := getMatchingPaths(argument.Value) // Your custom logic

        return &mcp.Completion{
            Values:  paths[:min(len(paths), 100)], // Max 100 items
            Total:   len(paths),                    // Total available matches
            HasMore: len(paths) > 100,              // More results available
        }, nil
    }

    return &mcp.Completion{Values: []string{}}, nil
}

// Register the provider
mcpServer := server.NewMCPServer(
    "my-server",
    "1.0.0",
    server.WithCompletions(),
    server.WithPromptCompletionProvider(&MyPromptCompletionProvider{}),
    server.WithResourceCompletionProvider(&MyResourceCompletionProvider{}),
)

注意:即使不显式提供,服务器也有默认提供者(NewMCPServer 中初始化了 DefaultPromptCompletionProvider 与 DefaultResourceCompletionProvider,见 server/server.go);WithPromptCompletionProvider / WithResourceCompletionProvider 用于替换为自定义实现(server/server.go)。

9.2 补全上下文(Completion Context)

对多参数的提示或资源模板,CompleteContext 参数提供已完成参数的访问,从而可以基于先前的选择给出上下文相关的建议:

func (p *MyProvider) CompleteResourceArgument(
    ctx context.Context,
    uri string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // Access previously completed arguments
    if previousValue, ok := context.Arguments["previous_arg"]; ok {
        // Provide suggestions based on previous_arg value
        return getSuggestionsFor(argument.Value, previousValue), nil
    }

    return &mcp.Completion{Values: []string{}}, nil
}

9.3 响应约束

返回补全结果时需遵守(README.md):

  • 每次响应最多 100 项;
  • 用 Total 表示可用匹配的总数;
  • 用 HasMore 表示是否存在超出已返回值之外的结果。

十、示例代码与代码生成

10.1 官方示例目录

README.md 指向 examples/ 目录,其中关键示例包括:

示例 演示内容
examples/task_tool/ 任务增强工具,覆盖 TaskSupportRequired 与 TaskSupportOptional 两种模式
examples/structured_input_and_output/ 基于 struct 的输入/输出 schema 与类型安全的工具处理器
examples/typed_tools/ 带强类型参数的类型安全工具处理器
examples/custom_context/ 工具处理器中的自定义上下文
examples/roots_client/、examples/roots_server/ roots 能力(客户端/服务器)
examples/sampling_client/、examples/sampling_server/ sampling 能力
examples/everything/ 综合演示
examples/in_process/、examples/inprocess_sampling/ 进程内(in-process)集成
examples/simple_client/ 简单客户端
examples/oauth_client/ OAuth 客户端

10.2 重新生成服务器代码

服务器的钩子(hooks)与请求处理器(request handlers)是生成代码,重新生成只需运行(见 README.md):

go generate ./...

前提条件:

  • 已安装 go;
  • 可用的 goimports 工具(生成器会自动运行 goimports 来格式化并修复导入)。

生成的源头是 server/internal/gen/ 目录中的模板(hooks.go.tmpl、request_handler.go.tmpl)与生成器 main.go,生成产物(如 server/hooks.go)文件头都有 Code generated by go generate. DO NOT EDIT. 标记。

十一、更多 ServerOption 一览

除了文中已展开的选项,仓库 server/server.go 还提供了大量 ServerOption,按需选用即可让服务器能力声明更精准:

选项 作用
WithToolCapabilities(listChanged bool) 声明工具能力及 listChanged 通知
WithResourceCapabilities(subscribe, listChanged bool) 声明资源能力(订阅、变更通知)
WithPromptCapabilities(listChanged bool) 声明提示能力
WithLogging() 启用日志能力
WithRoots() 启用 roots 能力
WithInstructions(instructions string) 设置 initialize 响应中的服务器指令
WithCompletions() 启用自动补全能力
WithPaginationLimit(limit int) 设置分页上限
WithInputSchemaValidation() 服务端校验工具调用参数是否符合声明的 inputSchema,失败时按 SEP-1303 返回工具执行错误
WithOutputSchemaValidation() 服务端校验结构化结果是否符合声明的 outputSchema
WithStrictInputSchemaDefault() 为未显式配置的 schema 设置 additionalProperties:false
WithHooks(hooks *Hooks) 挂载请求生命周期钩子
WithTaskHooks(taskHooks *TaskHooks) 挂载任务生命周期钩子
WithExperimental(map[string]any) 声明实验性非标准能力
WithIcons(...mcp.Icon) 设置服务器图标元数据
WithTitle(title) / WithDescription(desc) / WithWebsiteURL(url) 设置服务器实现元数据

需要提醒的是:如 README.md 所述,mcp-go 仍在积极开发中,使用前请以当前仓库代码与文档为准确认各选项的行为。

结语

本文从安装出发,走完了"最小服务器 → 计算器实战 → 资源/工具/提示三大概念 → 任务增强工具 → 传输层与 HTTP 增强 → 会话管理 → 钩子与中间件 → 自动补全"的完整路径,并对每个环节给出了仓库源码级佐证。掌握这些内容后,你既可以快速搭建一个通过 stdio 与本地 LLM 客户端通信的轻量 MCP 服务器,也可以进一步探索 client/(客户端实现)、mcptest/(测试辅助)、tracing/(可观测性)与 e2e/(端到端测试)等目录,把 mcp-go 用透。动手实践时,建议直接对照 examples/ 中的示例运行,并利用 go generate ./... 了解生成代码的组织方式。

登录后查看全文
mcp-go