Model Context Protocol（MCP）

通过 MCP 将本地或远程工具接入 Step Code。服务器连接后，模型可以按任务需要调用已注册的工具。

接入方式

传输	配置	适用场景
stdio	`command`、`args`、可选 `env`	启动本地工具进程
Streamable HTTP	`url`	连接远程 MCP 服务

不支持使用旧的 SSE 传输配置替代 Streamable HTTP。插件也可以声明 MCP 服务器，安装和启用方式见插件。

配置

在全局 ~/.stepcode/config.toml 的 [mcp_servers.<名称>] 中声明服务器。项目级 MCP 来自已安装插件 manifest 的 mcpServers 叠加：

[mcp_servers.local-tools]
command = "node"
args = ["/absolute/path/to/mcp-server.js"]
env = { LOG_LEVEL = "info" }

[mcp_servers.remote]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_TOKEN"

[mcp_servers.remote.oauth]
callback_port = 8976

示例中的本地路径和远程地址需替换为实际服务；Bearer 与 OAuth 按服务要求选择，不必同时配置。

字段	说明
`command`	stdio 启动命令，与 `url` 二选一
`args`、`env`、`cwd`	命令参数、子进程环境变量和工作目录，按需填写
`url`	Streamable HTTP 端点
`bearer_token_env_var`	保存 Bearer token 的环境变量名
`http_headers`	字面请求头，避免直接写入真实密钥
`env_http_headers`	请求头对应的环境变量名，缺少变量时报告错误
`startup_timeout_sec`	启动超时，默认 30 秒
`tool_timeout_sec`	单次调用超时，默认 300 秒
`enabled`	是否启用，默认 `true`
`enabled_tools`、`disabled_tools`	启用或禁用的工具集合

鉴权

Bearer token 应从运行 Step Code 的进程环境读取：

export EXAMPLE_TOKEN="YOUR_MCP_TOKEN"
step

OAuth 服务使用：

step mcp login <服务器名称>
step mcp logout <服务器名称>

OAuth 使用动态客户端注册、PKCE 和本地回调。令牌保存在 ~/.stepcode/.credentials.json，权限为 0600，按服务器名称加竖线的键（<名称>|）存放。模型平台登录与 MCP 服务授权是两套凭据。

命令行管理

step mcp list
step mcp list --json
step mcp get <服务器名称>
step mcp add remote --url https://mcp.example.com/mcp
step mcp add local-tools -- node /absolute/path/to/mcp-server.js
step mcp remove <服务器名称>

--url 与本地命令互斥。--bearer-token-env-var 只用于 HTTP，--env 设置的是 stdio 子进程环境，并不是 HTTP 请求头。

交互内查看

运行 /mcp 查看服务器状态和已加载工具数。常见状态包括 connecting、connected 和 failed。enabled = false 的服务器不进入列表。连接失败时，先检查命令是否存在、环境变量是否传入、远程地址是否可达，以及授权是否有效。

工具命名与过滤

工具以 <服务器名>__<工具名> 命名，非法字符转换为下划线。通过 enabled_tools 和 disabled_tools 在注册阶段过滤：设置 enabled_tools 后，其他工具对模型不可达。这与在 prompt 中要求“不要使用某工具”不同：未注册的工具不会出现在模型可调用列表中。

安全性

只连接可信服务器。stdio 服务会执行本地进程，远程 MCP 会收到调用参数；返回内容也可能进入模型上下文。 Bypass 不逐项审批普通 MCP 工具调用。涉及外发、写入或管理操作时，建议使用 Ask，并关闭不需要的工具。内置命令规则不能推断任意外部 MCP 服务的全部副作用。

指南

配置

自定义

参考手册

接入方式

配置

鉴权

命令行管理

交互内查看

工具命名与过滤

安全性

下一步

​接入方式

​配置

​鉴权

​命令行管理

​交互内查看

​工具命名与过滤

​安全性

​下一步

接入方式

配置

鉴权

命令行管理

交互内查看

工具命名与过滤

安全性

下一步