> ## 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。

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`。

## 支持的传输方式

本地 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`。

## 配置示例

### 本地 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 提交到代码仓库。建议通过环境变量或系统密钥管理工具维护敏感信息。

## 作为插件分发

如果要把 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 服务传入敏感文件、私有仓库内容或生产环境凭据。
* 对会发布、发送、提交或修改外部系统状态的工具，先确认操作影响。