mcp-go 开发实战指南:用 Go 构建高性能 Model Context Protocol 服务器
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)
}
}
相比最小示例,这里引入了两个值得注意的能力:
mcp.Enum(...)参数约束:为operation声明合法取值集合,LLM 在调用前就能知道可选值,降低无效调用的概率。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
)
注意三点:
- 注册方式不同:任务工具使用
s.AddTaskTool而非AddTool,handler 签名返回*mcp.CreateTaskResult而不是*mcp.CallToolResult(见 server/server.go 中的TaskToolHandlerFunc定义)。 - 服务器自动管理任务元数据:Task 的 ID、状态等字段由服务器填充,handler 只需返回空的
mcp.Task{}。 - 能力声明:
server.WithTaskCapabilities(list, cancel, toolCallTasks)三个布尔参数分别控制客户端能否列出任务、取消任务、以及是否启用工具的任务增强(实现在 server/server.go)。
任务执行流程(README 明确列出):
- 客户端携带 task 参数调用工具;
- 服务器立即返回 task ID;
- 工具在后台异步执行;
- 客户端轮询
tasks/result获取结果; - 任务完成时服务器发送状态通知。
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 ./... 了解生成代码的组织方式。