---
title: "exec 里可选 MCP 默认只等 1 秒，握手成功也可能没进工具表"
summary: "可选服务器超时后静默从第一轮目录丢掉。桌面能用是因为后面还会刷新。exec 要 required，或把宽限改成 0。"
category: mcp
level: advanced
surfaces: [cli, ci]
tags: ["MCP", "exec", "mcp_optional_startup_grace_ms"]
canonical: /tips/exec-mcp-optional-grace/
---

# exec 里可选 MCP 默认只等 1 秒，握手成功也可能没进工具表

可选服务器超时后静默从第一轮目录丢掉。桌面能用是因为后面还会刷新。exec 要 required，或把宽限改成 0。

`codex exec` 在会话一开始就拍下工具表，后面不再等。可选 MCP（没写 `required = true`）只享有顶层宽限，默认 **1000** 毫秒。网络 HTTP 服务器经常在握手完成后才返回 `tools/list`，那时第一轮目录已经定了，模型看不到工具。桌面长会话会在后续轮刷新，所以同一份 config 在 TUI 里「能用」、exec 里像没装。

exec 必须用到的服务器直接标必达：

```toml
[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
required = true
startup_timeout_sec = 20
```

或者取消共享宽限，改等各服务器自己的 `startup_timeout_sec`：

```toml
mcp_optional_startup_grace_ms = 0
```

高延迟链路也可以把宽限抬到 `3000`–`5000`。`required = true` 的服务器本来就不走这段宽限，失败会让启动失败，这是有意的。

核对：`codex mcp list` 连得上不等于 exec 第一轮带了工具。用一条只读探测：

```bash
codex exec --sandbox read-only "列出已连接 MCP 工具名，不要调用写操作。"
```

省略日志里出现 omitting pending optional MCP server 时，先改宽限或 required，不要先开 `--yolo`。

## 来源

- [OpenAI · Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)
- [openai/codex#38689](https://github.com/openai/codex/issues/38689)