深入理解 MCP 服务器中环境变量的声明和配置实践

配置环境变量的必要性

对于Model Context Protocol（MCP）服务器的开发，在实际操作中我最深刻的一个小但很重要的知识点就是在工具开发流程中怎样规范地声明和管理环境变量输入。从开发者的角度来看，这其实只是增加几个参数、配置一些信息，但是如果没有理解其中的设计约定以及配置的要求，很容易在本地开发、集成到客户端、发布NuGet包的时候出现错误。

运行时行为调整与环境变量设计

在构建MCP服务器的时候，常见的需求之一就是让工具方法的执行可以读取环境变量，比如模拟外部配置输入，或者在运行时调整行为。比如在开发天气描述工具的时候，就需要用到一个叫做WEATHER_CHOICES的环境变量，该环境变量可以使得工具根据外部配置返回不同的描述。MCP协议以及现代AI应用中“插件模式”设计的思想其实就蕴含在里面了。也就是说，你的MCP服务端除了提供基本的功能之外，还要把输入和控制权交给“宿主”应用，即VS Code或者其他IDE的插件管理系统，最终用户或者客户端可以通过参数来控制你的服务。配置带来的好处就是大大提高了MCP服务器的适用范围以及可定制性。

{"servers":{"SampleMcpServer":{"type":"stdio","command":"dotnet","args":["run","--project","<relative-path-to-project-file>"],"env":{"WEATHER_CHOICES":"sunny,humid,freezing"}}}}

// .vscode/mcp.json 示例，配置WEATHER_CHOICES环境变量以调整MCP服务行为

server.json的重要性

在实际开发中，环境变量的声明并不是传统的.NET应用那样只需要在代码中读取就可以的，更多的是体现在配置层面。以目前MCP的实现为例，开发者在工具方法内部通过标准的环境变量读取机制来获取配置项。这种方式简单有效，也符合云原生应用和容器时代下开发的理念。但是我们还要让VS Code、NuGet.org等客户端知道这个MCP工具都有哪些环境变量，这些变量是否必须，是不是需要用户手动输入，甚至能不能用统一的配置文件批量注入。这就需要我们让server.json中显式注册这些变量。我认为每一个MCP工具的开发者都应该花时间来认真维护server.json文件中environmentVariables的部分。WEATHER_CHOICES这样的变量应该声明出它的名称、用途、说明，如果是必填项的话还需要加上isRequired标记。这样用户在VS Code安装你的MCP插件的时候，就会被友好地提示填写、校验参数，从而避免运行时因为变量缺失而出现诡异的错误。

{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json","description":"<your description here>","name":"io.github.<your GitHub username here>/<your repo name>","version":"<your package version here>","packages":[{"registryType":"nuget","registryBaseUrl":"https://api.nuget.org","identifier":"<your package ID here>","version":"<your package version here>","transport":{"type":"stdio"},"packageArguments":[],"environmentVariables":[{"name":"WEATHER_CHOICES","value":"{weather_choices}","variables":{"weather_choices":{"description":"Comma separated list of weather descriptions to randomly select.","isRequired":true,"isSecret":false}}}]}],"repository":{"url":"https://github.com/<your GitHub username here>/<your repo name>","source":"github"}}

// server.json中显式声明WEATHER_CHOICES环境变量及其描述、必填属性

补全元数据桥梁

在以前的工程实践中，我也曾经忽视过配置这一层，结果上架 NuGet 后发现 IDE 端总是捕捉不到我的 runtime 参数，导致功能受限。后来仔细研究了官方的 MCP Registry 配置模式，才明白NuGet或者VS Code其实都是依赖于server.json格式化的数据来生成MCP服务器的交互界面。也就是说，“元数据”才真正起到桥梁的作用，把配置的写死和用户层的定制需求打通了。这也给开发者提了一个醒，不管是环境变量还是CLI参数，都应该放到server.json的environmentVariables、packageArguments中，根据实际需要来规划清楚，并且加上必要的说明文本。不但可以方便后期维护，而且对集成体验有很大帮助。

IDE与NuGet集成维护建议

另一个常见问题就是，开发者在本地开发的时候会使用 .vscode/mcp.json 来覆盖环境变量，但是始终没有把配置同步到 NuGet 的 server.json 版本，结果在别人直接拉取 NuGet 包之后，服务端参数缺失，导致功能异常。为了避免出现类似的问题，我建议每次进行功能升级或者参数扩展的时候，都要把新增的输入项写到项目根目录下的 server.json 文件中，并且用 VS Code 进行实际的调试来确认IDE已经正确地识别了所有的可用参数并且可以顺利地调用工具方法。只有这样，MCP 工具包才不会进入 NuGet 流程的时候出现“可以运行但是不能控制”的问题。另外，随着 MCP Registry 的逐步完善，元数据声明会和 IDE 配置、应用市场结合起来，谁的 server.json 写得更规范，谁的插件集成体验就越好。

参数声明的集成意义

最后一点就是我个人的经验，MCP 服务器工具方法的输入参数和环境变量，实际上就是二进制分发和云端环境之间的桥梁。很多时候我们希望AI工具或者Copilot能够做出独立的决定，但是又想控制一些重要的配置。参数声明不清楚的话，集成MCP模块的用户要么一头雾水，要么经常收到隐晦的错误提示，这都会对扩展生态的活力产生很大的影响。规范声明配置、善用server.json这样的约定文件，既是对自己负责，也是对服务生态负责的表现。

规范流程的重要意义

因此，如果你使用.NET 10 SDK或者相关MCP Server模板开发MCP服务器，希望被IDE端或者AI Agent端调用的时候，强烈建议一定要保证环境变量和参数声明、配置、校验的流程是做好、做完整的。这是MCP生态实现自动化、可组合、高扩展的基础，也是每一个AI插件开发者必须具备的基本素养。项目开始的时候就养成好的习惯，后期不管是用户体验还是服务集成，都会表现得更有效、更健壮。