TL;DR：在 .lingcode/mcp.json 中（或通过 Mac IDE 的界面）添加一个 MCP 服务器条目，填写服务器的命令、参数和环境变量。LingCode 会将其作为子进程启动，并将其工具以 mcp__<id>__<name> 的形式暴露给代理。支持 Mac IDE、CLI 和 /try（/try 中仅支持 HTTP 传输）。
MCP 服务器是你为 AI 代理赋予全新类型化工具的方式——可用于 Linear、GitHub、数据库、内部管理 API 等任何服务。只需配置一次，工具便会出现在每次对话中，以命名空间区分并逐次获得授权。
代理内置的工具各司其职——读取文件、运行 shell、搜索代码——但它们都有一个共同的局限：只能做本地终端里能做的事。而现实中的工程工作有很大一部分并不在本地。在 Linear 中查找工单、向 Slack 发布状态更新、查询生产数据库中的用户记录、触发 CI 流程——这些远程操作，在没有额外接口的情况下，代理根本无法完成。
一个简单粗暴的做法是给代理 shell 访问权限，让它直接调 curl，寄希望于它能构造出正确的 API 请求。这种方式偶尔凑效，但大多数时候会出问题——代理必须在提示词中记住端点、认证头、响应结构和错误码。一个错误的请求头就是 401，一个错误的端点就是 404，代理只能靠 HTTP 错误码来反复调试，而不是结构化的反馈。
MCP（Model Context Protocol）是这个问题的结构化解决方案。MCP 服务器是一个小型进程，它以带有明确 JSON Schema 的形式暴露类型化工具（如 create_ticket、get_user_by_email、run_query），包括参数和返回值。代理按名称调用工具，并拿到结构化的数据返回。认证只在服务器启动时进行一次，代理根本看不到凭据。
本教程介绍如何连接一个已有的 MCP 服务器（编写自己的 MCP 服务器是另一个更深入的话题）。你将了解 LingCode 支持的两种传输方式、配置的存放位置、工具的命名空间规则，以及每次工具调用的授权流程。
一个 MCP 服务器条目只需要几个字段：
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "mcp-server-linear"],
"env": {
"LINEAR_API_KEY": "lin_api_..."
}
}
}
}这就是最精简的配置：一个唯一的名称（linear）、用于启动服务器的 command + args，以及它所需的环境变量。LingCode 会在代理开始一轮对话时启动这个进程，通过 stdin/stdout 与之通信，并在轮次结束后将其关闭，保持整洁。
MCP 支持两种传输方式：
url 代替 command，并在 headers 中传递认证信息。适合运行在团队成员机器上的服务、内部共享服务，或托管的第三方服务商。两者使用同一套协议，区别仅在于连接方式。代理本身并不知道也不在乎它使用的是哪种传输。
LingCode 从三个位置查找 MCP 服务器配置：
~/.claude/mcp.json——在任何地方均生效。适合个人账号级别的服务（你自己的 Linear、你自己的 GitHub）。.claude/mcp.json——仅在该项目中生效。适合项目专属的服务（该产品的管理 API）。mcp/ 目录中——适合可共享、有命名空间的工具（例如团队共同安装的"通过 mcp-server-linear 接入 Linear"插件）。三者在加载时会合并。命名冲突时，项目级配置优先于用户级配置。
mcp__<server>__<tool>服务器注册后，LingCode 会发现其工具，并以 mcp__linear__create_issue、mcp__linear__list_projects 等名称将其暴露给代理。这个前缀很重要：它能防止两个都暴露了 create_issue 工具的 MCP 服务器产生命名冲突，也能让你在聊天面板中一眼看出某次工具调用来自 MCP，而非内置工具集。
在一次会话中，每当代理首次调用某个 MCP 工具时，你会看到一个授权提示，显示工具名称、参数以及服务器身份。你可以选择批准、拒绝，或"本次会话内始终批准"。授权是按工具粒度的，而非按服务器——这是有意为之的设计，因为有些 MCP 服务器会将强大的工具和无害的工具混在一起暴露。
服务器无法启动。运行 lingcode doctor（或在 REPL 中输入 /doctor）。它会尝试启动每个已配置的 MCP 服务器，并报告启动失败的服务器的 stderr 输出。常见原因包括：PATH 中找不到 npx/node、必填的环境变量未设置、服务器包尚未发布（npm 包名有拼写错误）。看到实际的错误信息后，解决方案通常一目了然。
服务器启动了，但工具不显示。服务器在运行，但没有注册任何工具。这通常意味着服务器端的工具定义存在 Schema 问题——工具在代码中存在，但未能通过校验，代理因此看不到它们。查看服务器自身的日志；Schema 校验失败通常会有明显的报错信息。如果是第三方服务器且是近期才出现的问题，建议向上游提交 issue。
如果 mcp.json 文件在版本控制中，不要将 LINEAR_API_KEY 直接写成明文字符串。要么提交一个模板（$LINEAR_API_KEY），让环境变量在运行时提供实际值；要么将真实配置放在 ~/.claude/mcp.json 中（该文件属于用户个人，不会被提交）。MCP 服务器功能强大——泄露凭据的风险等同于泄露任何其他 API Key。