功能介绍

MCP（Model Context Protocol）用于把外部工具和数据源接入PlugClaw。配置完成后，智能体可以在对话中调用MCP Server提供的能力，例如读取代码仓库、访问指定文件、查询数据库，或连接内部业务系统。

MCP Server是实际提供工具的一端。PlugClaw负责连接MCP Server，并把其中可用的工具交给智能体。不同MCP Server能够访问的数据、需要的权限和认证方式都可能不同，因此不能只根据服务名称套用同一份配置；接入前需要先查看对应MCP Server的官方说明，确认启动方式、连接地址、认证信息和所需运行环境。

MCP适合接入已有服务或专业工具，不会因为完成配置就自动改变智能体的所有行为。配置生效后，还需要在对话中提出与该工具有关的任务，才能确认智能体是否真正调用了对应能力。

MCP可能接触文件、代码、数据库或内部系统中的信息。只接入来源可信的MCP Server，并为它提供完成任务所需的最小权限。Token、API Key、密码和内部地址不要出现在公开文档、对话内容或反馈截图中。

配置前准备

先根据MCP Server的官方说明准备以下信息：

MCP Server名称      用于在PlugClaw配置和命令中识别该服务
接入类型            远程MCP或本地MCP
连接或启动信息      远程服务的URL，或本地服务的command和args
认证信息            OAuth、Token、API Key、请求头或其他凭证
运行条件            网络访问、Node.js、npx、可执行文件或其他依赖

远程MCP连接一个已经运行的MCP Server，核心配置是url。这个地址必须能从PlugClaw运行环境访问；如果服务位于其他设备，不能使用只对服务所在设备有效的localhost地址。

本地MCP由PlugClaw启动一个MCP Server程序，核心配置是command。该命令和它依赖的程序必须存在于PlugClaw运行环境中，而不是只安装在另一台电脑上。

配置保存在openclaw.json中。修改前先备份原文件，下面的JSON都只是需要合并到现有配置中的示例结构，不要用示例覆盖整个文件。合并时还要保留已有配置，并检查括号、逗号和引号是否完整。

添加MCP Server

每个MCP Server都配置在mcp.servers下，基础结构如下：

{
  "mcp": {
    "servers": {
      "<server-name>": {
        "enabled": true
      }
    }
  }
}

<server-name>是这项服务在PlugClaw中的名称，后续状态查询和OAuth登录也会使用同一个名称。建议使用容易识别且不重复的英文名称，例如github、filesystem或database。

配置远程MCP

远程MCP需要填写PlugClaw可以访问的MCP Server地址。下面以支持Streamable HTTP的服务为例：

{
  "mcp": {
    "servers": {
      "<server-name>": {
        "url": "<mcp-server-url>",
        "transport": "streamable-http",
        "enabled": true
      }
    }
  }
}

transport表示连接方式。示例中的streamable-http只适用于明确支持这种方式的MCP Server；如果官方说明提供了其他传输方式，应按对应服务的要求填写，不能只因为它是远程服务就固定使用该值。

需要OAuth授权时，可以在对应服务中加入auth：

{
  "mcp": {
    "servers": {
      "github": {
        "url": "https://example.com/mcp",
        "transport": "streamable-http",
        "auth": "oauth",
        "enabled": true
      }
    }
  }
}

需要通过请求头传递Token或API Key时，可以加入headers：

{
  "mcp": {
    "servers": {
      "example": {
        "url": "https://example.com/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${API_TOKEN}"
        },
        "enabled": true
      }
    }
  }
}

${API_TOKEN}表示从环境变量中读取名为API_TOKEN的值，不是需要原样使用的真实Token。这个环境变量必须能够被运行网关的PlugClaw进程读取；只在另一个终端或另一台电脑中设置同名变量不会自动生效。具体变量名称和认证格式以MCP Server的官方说明为准。

配置本地MCP

本地MCP由PlugClaw运行环境执行启动命令：

{
  "mcp": {
    "servers": {
      "<server-name>": {
        "command": "<start-command>",
        "args": [
          "<arg-1>",
          "<arg-2>"
        ],
        "enabled": true
      }
    }
  }
}

command是启动程序，args是依次传给该程序的参数。启动命令不需要参数时可以省略args。例如官方说明要求使用npx -y <mcp-server-package>时，command应填写npx，其余内容写入args，不要把整行命令全部放进command。

需要向本地MCP Server传递环境变量时，可以加入env：

{
  "mcp": {
    "servers": {
      "example-local": {
        "command": "npx",
        "args": [
          "-y",
          "<mcp-server-package>"
        ],
        "env": {
          "TOKEN": "${TOKEN}"
        },
        "enabled": true
      }
    }
  }
}

示例中的<mcp-server-package>和${TOKEN}都需要按实际服务说明准备，不能直接照抄。敏感信息应通过环境变量传入，不建议直接写进openclaw.json。

让配置生效并完成认证

保存openclaw.json后重启网关，让PlugClaw重新加载MCP配置。网关无法正常启动时，先恢复修改前的配置文件备份，再检查JSON格式和新增内容，不要在错误配置上继续叠加修改。

使用OAuth的MCP Server还需要在终端中完成登录：

openclaw mcp login <server-name>

例如配置中的服务名称为github：

openclaw mcp login github

命令中的名称必须与mcp.servers下的名称完全一致。使用Token、API Key或自定义请求头时，则要确认相应环境变量已经配置，并且运行网关的PlugClaw进程能够读取。

验证MCP是否可用

先在终端中查看已保存的MCP配置状态：

openclaw mcp status --verbose

status用于检查配置、连接方式和认证状态，本身不会连接目标MCP Server。需要确认服务确实能够连接并提供工具时，继续运行：

openclaw mcp doctor <server-name> --probe

将<server-name>替换为配置中的实际名称。检查通过后，再回到智能体对话中提出一个只能通过该MCP完成的简单任务。例如，仓库类MCP可以先读取一个已知仓库的基本信息，文件类MCP可以先读取授权目录中的测试文件。

只有实时探测正常，并且对话中的实际结果来自目标MCP，才能说明配置完整生效。智能体给出普通文字回复，并不能单独证明它已经调用MCP工具。

MCP Server未正常工作时，可按下面的顺序检查：

• 远程MCP：URL是否正确，PlugClaw是否能访问该地址，transport是否符合服务要求。
• 本地MCP：command是否存在，args顺序是否正确，依赖是否安装在PlugClaw运行环境中。
• 认证信息：OAuth是否完成登录，Token或API Key是否有效，环境变量是否能被网关读取。
• 配置文件：JSON格式是否正确，服务名称是否一致，enabled是否为true。
• 权限范围：MCP Server是否有权访问当前任务所需的仓库、目录、数据库或其他资源。

需要暂时停用某个MCP Server时，可以把对应配置中的enabled改为false并重启网关。确认不再使用后再删除对应配置；删除前保留一份可恢复的配置备份。