MCP 扩展工具

MCP（Model Context Protocol）是一个开放协议，让 Agent 能接入外部程序提供的工具——比如某个专业软件的接口、一个数据源、一套文档检索服务。你在 3Studio 里配置好一个「MCP 服务器」之后，它提供的工具就会出现在 Agent 的能力清单里，Agent 会在需要时自动调用，不用你手动干预。

MCP 服务器由各自的开发者提供，3Studio 只负责连接。常见来源：开源社区发布的现成服务器（很多用 npx 一条命令就能跑起来）、你们团队自己开发的内部服务。

在哪里配置

打开设置 → 工具标签页，最上方就是 MCP 服务器 分区：

刷新按钮：重新读取已配置服务器的当前连接状态。
编辑配置按钮：展开一个 JSON 配置编辑器。编辑前需要先选择范围——全局（对所有工作区生效）或项目（只对当前工作区生效），改完点保存；保存成功会显示"已保存"，JSON 写错了会显示具体错误。
下方是服务器列表，每条显示服务器 ID、连接状态标签、所属范围（global/project）、命令或地址，以及提供的工具数量（"N 个工具"）；连接出错时会额外显示错误信息。

配置文件格式

配置是一个 JSON 对象，所有服务器都写在 mcpServers 下，每个服务器一个自取的 ID。两种连接方式：

本地命令（stdio）——3Studio 替你启动一个本地程序作为服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:\\data"],
      "env": { "SOME_TOKEN": "xxx" }
    }
  }
}

远程地址（streamable_http）——连接一个已经在运行的 HTTP 服务：

{
  "mcpServers": {
    "internal-docs": {
      "url": "http://192.168.1.100:8080/mcp"
    }
  }
}

各字段含义：

字段	说明
`command`	本地方式：要执行的程序（如 `npx`、`python`、某个 exe 的完整路径）
`args`	本地方式：命令行参数，字符串数组
`env`	本地方式：传给该程序的环境变量（比如 API 密钥），键值都是字符串
`url`	远程方式：服务器的 HTTP 地址
`transport`	连接方式，`"stdio"` 或 `"streamable_http"`；通常不用写——填了 `url` 自动按远程处理，否则按本地处理
`enabled`	设为 `false` 可暂时停用这个服务器而不删配置；不写默认启用

一个服务器写 command（本地）或 url（远程）二选一；两者都没写的条目会被忽略。

两个作用域

范围	配置文件位置	生效范围
全局	`C:\Users\<你>\.3studio\mcp.json`（macOS 为 `~/.3studio/mcp.json`）	所有工作区
项目	`<工作区文件夹>\.3studio\mcp.json`	只在该工作区

两份配置会合并生效；如果全局和项目里配了同一个 ID，以项目里的为准。在设置页编辑时通过范围选择切换编辑哪一份；直接用文本编辑器改这两个文件也可以，效果相同。

项目作用域的配置文件在工作区文件夹里，如果你的项目用 git 之类的工具共享，团队成员可以拿到同一份 MCP 配置——注意不要把 API 密钥这类敏感信息写进要共享的项目配置里，放全局配置或 env 由各自本机维护更安全。

保存后何时生效

改动 MCP 配置后需要重启 3Studio 才会生效。 保存只是把配置写入文件；Agent 实际连接哪些服务器是在应用启动时确定的，所以新增、修改或删除的服务器要等重启后才会出现在服务器列表里、才能被 Agent 使用。列表里的"刷新"按钮只是重新读取当前已连接服务器的状态，不会加载新配置。

连接状态

服务器列表里每条的状态标签含义：

状态	含义
已连接	正常，旁边会显示这个服务器提供了几个工具
连接中	正在建立连接
已断开	连接断开
错误	连接失败，下方会显示具体错误信息
已禁用	配置里 `enabled` 设了 `false`
不支持	当前运行环境不支持这类服务器

除了设置页，还有两个地方能看 MCP 状态：

侧边栏底部的"运行时"面板：有一行 MCP 汇总（如"MCP 2/3 已连接"），点开能看到每个服务器的状态。
对话里输入 /mcp：输出一份已连接服务器、工具和提示词的状态清单（斜杠命令的用法见《与 Agent 对话》）。

另外，MCP 服务器提供的提示词（预置的一段任务指令）会以斜杠命令的形式出现在输入框的命令列表里，带 "MCP" 标记，同样见《与 Agent 对话》。

常见问题

加了服务器但列表里没出现：先确认已保存且 JSON 无报错，然后重启 3Studio（见上文"保存后何时生效"）。
保存时报错：JSON 格式有问题——常见的是少逗号、多逗号、引号不配对；报错信息里会给出线索。Windows 路径里的反斜杠要写成两个（D:\\data）。
状态显示"错误"：看下方的错误信息。本地方式先确认 command 里的程序在你机器上装了、能在命令行里跑起来；远程方式确认 url 地址可访问。
想暂时停用一个服务器：给它加 "enabled": false，不用删配置；重启后状态会显示"已禁用"。