> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服务

> 将外部工具和数据源连接到 MiniMax Code。

<div className="code-docs">
  MCP（Model Context Protocol）是一种连接外部工具与数据源的协议。通过 MCP 服务，MiniMax Code 可以在任务中调用你配置的本地命令、远程服务或第三方数据能力，例如浏览器自动化、企业内部系统、知识库、数据库和专用检索工具。

  ## 适合场景

  * 将团队内部工具接入 MiniMax Code
  * 调用本地命令行工具或脚本
  * 连接远程 MCP 服务
  * 为 Agent 补充专用数据源、检索能力或操作能力
  * 复用其他 MCP 客户端中已有的 `mcpServers` 配置

  ## 两种使用方式

  MCP 在 MiniMax Code 中有两种常见使用方式：

  | 方式     | 适用对象        | 说明                                             |
  | ------ | ----------- | ---------------------------------------------- |
  | 本地配置   | 个人或团队内部使用   | 在当前设备添加 MCP 服务，配置保存在本地。                        |
  | 通过插件分发 | 希望上架给其他用户安装 | 将 MCP 配置放入插件包的 `*.mcp.json`，并在插件 manifest 中引用。 |

  本地配置不依赖插件；插件分发用于 Marketplace 上架。需要用户账号连接、OAuth 授权、凭据刷新或断开连接的能力，不应直接写成普通 MCP 配置，应先按应用 / Connector 接入。

  ## 配置入口

  在 MiniMax Code 中打开插件管理入口，并切换到 **MCP 服务**。你可以在页面中添加、编辑、删除、启用或停用 MCP 服务，也可以测试连接状态。

  添加服务器时支持两种方式：

  * **表单模式**：按传输方式填写命令、URL、参数、环境变量、请求头等字段。
  * **JSON 模式**：粘贴单个服务器配置，或粘贴包含 `mcpServers` 的完整 JSON 对象。

  <Note>
    MCP 配置保存在当前设备本地。手动维护配置时，常见位置是 MiniMax Code 本地数据目录下的 `mcp.json`，例如 `~/.minimax/mcp.json`。
  </Note>

  ## 支持的传输方式

  本地 MCP 配置支持：

  | 类型                | 适用场景                                    | 主要字段                   |
  | ----------------- | --------------------------------------- | ---------------------- |
  | `stdio`           | 本地命令、Node/Python 脚本、通过 `npx` 启动的 MCP 服务 | `command`、`args`、`env` |
  | `http`            | 普通 HTTP MCP 服务                          | `url`、`headers`        |
  | `streamable-http` | 支持 Streamable HTTP 的远程 MCP 服务           | `url`、`headers`        |
  | `sse`             | 使用 SSE 连接的远程 MCP 服务                     | `url`、`headers`        |

  公共字段包括：

  * `type`：传输方式。
  * `enabled`：是否启用该服务。
  * `description`：在列表中展示的说明。
  * `timeout`：连接或调用超时时间，单位为毫秒。

  <Note>
    插件包中的 `*.mcp.json` 支持 `stdio`、`streamable-http` 和 `sse`；不支持 `http` alias。如果要把 MCP 能力上架为插件，建议直接使用 `streamable-http`。
  </Note>

  ## 配置示例

  ### 本地 stdio 服务

  ```json theme={null}
  {
    "mcpServers": {
      "playwright": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@playwright/mcp", "--browser", "chromium"],
        "enabled": true,
        "description": "Playwright browser automation"
      }
    }
  }
  ```

  ### 远程 HTTP 服务

  ```json theme={null}
  {
    "mcpServers": {
      "company-search": {
        "type": "streamable-http",
        "url": "https://example.com/mcp",
        "headers": {
          "Authorization": "Bearer ${COMPANY_MCP_TOKEN}"
        },
        "enabled": true,
        "description": "Internal company search"
      }
    }
  }
  ```

  <Warning>
    不要把真实 Token、API Key 或内部 URL 提交到代码仓库。建议通过环境变量或系统密钥管理工具维护敏感信息。
  </Warning>

  ## 作为插件分发

  如果要把 MCP 能力分发给其他用户安装，可以在插件包中添加 `*.mcp.json`，并在 `.minimax-plugin/plugin.json` 的 `mcpServers` 中引用。

  ```json theme={null}
  {
    "schemaVersion": 1,
    "mcpServers": {
      "acme-search": {
        "type": "streamable-http",
        "url": "https://mcp.acme.example/mcp",
        "description": "检索 Acme 公开知识库",
        "timeout": 30000
      }
    }
  }
  ```

  本地 stdio MCP 可以引用插件包内脚本：

  ```json theme={null}
  {
    "schemaVersion": 1,
    "mcpServers": {
      "local-analyzer": {
        "type": "stdio",
        "command": "python3",
        "args": ["./server.py"],
        "description": "分析本地输入文件",
        "timeout": 30000
      }
    }
  }
  ```

  插件包中的 MCP 需要注意：

  * `timeout` 表示单次工具调用超时，单位为毫秒。
  * `stdio.command` 只写 PATH 中的解释器或可执行名；包内脚本通过相对 `args` 引用。
  * 远程 MCP 必须使用真实 HTTP(S) 地址，并建议在提交前完成 `initialize`、`tools/list`、`tools/call` 验证。
  * 不要在 `headers`、`env` 或其他文件中写入任何密钥与用户凭据。

  ## 在任务中使用

  配置并启用 MCP 服务后，你可以直接在对话中描述需要的能力。MiniMax Code 会根据任务上下文选择可用工具，并在需要账号、权限或外部操作确认时向你说明。

  如果配置了较多 MCP 工具，MiniMax Code 会按需检索相关工具，避免把所有工具定义一次性放入上下文，从而减少上下文占用并提升工具选择的准确性。

  ## 命令行检查

  MiniMax Code 运行时保持开启后，可以用 CLI 查看 MCP 状态：

  ```bash theme={null}
  mcode mcp list --human
  mcode mcp tools <server-name>
  mcode mcp auth status
  ```

  常用用途：

  * 查看当前已注册的 MCP 服务
  * 确认服务是否启用
  * 查看某个服务暴露了哪些工具
  * 检查需要授权的服务是否已经登录或过期

  ## 排障建议

  | 问题        | 建议                                                                   |
  | --------- | -------------------------------------------------------------------- |
  | 找不到命令     | 确认 `command` 在当前系统 PATH 中可执行；使用 `npx`、`node`、`python` 时确认本机已安装对应运行时。 |
  | JSON 无法保存 | 检查是否是合法 JSON，`args` 应为字符串数组，`env` 和 `headers` 应为字符串键值对象。             |
  | 连接测试失败    | 检查 URL、网络代理、请求头和服务端 MCP 协议兼容性。                                       |
  | 工具没有出现    | 确认服务已启用并重新测试连接；必要时重启 MiniMax Code。                                   |
  | 授权失效      | 重新登录或更新对应的 Token、Cookie、API Key。                                     |
  | 插件提交被拒    | 检查 transport 是否受插件包支持，路径是否为相对路径，包内是否包含密钥、安装脚本或平台专属依赖。                |

  ## 安全建议

  * 只添加可信来源的 MCP 服务。
  * 在保存前检查 `command`、`args`、`url` 和 `headers`。
  * 避免给不可信 MCP 服务传入敏感文件、私有仓库内容或生产环境凭据。
  * 对会发布、发送、提交或修改外部系统状态的工具，先确认操作影响。
</div>