---
title: "CircleCI 在 Codex 里先装插件，托管 MCP 才是 mcp.circleci.com/v1/mcp"
summary: "Codex 主路径是 /plugins 装 CircleCI，并先 circleci auth login。跨工具才用 codex mcp add circleci --url https://mcp.circleci.com/v1/mcp 再 mcp login。不要装已弃用的 npx @circleci/mcp-server-circleci，也不要和 Circle 支付 MCP 搞混。"
category: mcp
level: intermediate
surfaces: [cli, app, ide]
tags: ["MCP", "CircleCI", "plugins", "OAuth"]
canonical: /tips/mcp-circleci-remote/
---

# CircleCI 在 Codex 里先装插件，托管 MCP 才是 mcp.circleci.com/v1/mcp

Codex 主路径是 /plugins 装 CircleCI，并先 circleci auth login。跨工具才用 codex mcp add circleci --url https://mcp.circleci.com/v1/mcp 再 mcp login。不要装已弃用的 npx @circleci/mcp-server-circleci，也不要和 Circle 支付 MCP 搞混。

CircleCI 官方给 Codex 的**主路径是插件**，不是本地 npx 包。先装 CLI 并登录（浏览器授权，凭证进系统钥匙串，不必手拷 PAT）：

```bash
brew install circleci
circleci auth login
circleci auth me
```

然后在 Codex 会话里打开 `/plugins`，目录里找 CircleCI，安装后**新开会话**。技能要新会话才加载。用自然语言即可，不必每句都 `@circleci`：

- 检查最近一次 pipeline
- 审查本仓库的 CircleCI 配置（底层是 `circleci config validate`）
- 诊断最近一次失败构建

多数命令从当前 git remote / 分支推断项目。组织 slug 是 `circleci/` 而不是 `gh/` 时，在仓库里再跑 `circleci project link`。网页「Copy Fix Prompt」会复制一段带 run UUID 和 `--failure-report` 的提示，直接贴进 Codex；不要把那段 UUID 写进 `config.toml`。

跨编辑器、或只要远程 MCP 时，托管地址是 Streamable HTTP：

```bash
codex mcp add circleci --url https://mcp.circleci.com/v1/mcp
codex mcp login circleci
```

```toml
[mcp_servers.circleci]
url = "https://mcp.circleci.com/v1/mcp"
enabled = true
```

服务器名用 `circleci`，不要抄 Claude 文档里的 `circleci-mcp-server`。CI 不能开浏览器时，用个人 API token 走 `bearer_token_env_var`（CLI 环境变量名是 `CIRCLE_TOKEN`），不要把 `Authorization: Bearer` 写进 `http_headers`：

```toml
[mcp_servers.circleci]
url = "https://mcp.circleci.com/v1/mcp"
bearer_token_env_var = "CIRCLE_TOKEN"
enabled = true
```

不要和已经 `mcp login` 的 OAuth 写在同一张表。变量必须在启动 Codex 的那个进程里。

本机 CLI MCP（`circleci mcp start`）官方 enable 列表只有 Claude / Cursor / VS Code，**没有** `circleci mcp codex enable`。硬要 stdio 时自己 `codex mcp add circleci -- circleci mcp start`，仍先 `circleci auth login`。

不要做这些：

- 不要装 `npx -y @circleci/mcp-server-circleci`。官方已弃用；旧文里的 `CIRCLECI_TOKEN` + `env` 表不要抄。
- 不要抄 Claude 的 `--transport http` 或 `mcpServers` JSON。
- 不要和 Circle（circle.com 支付 / 链上）那台 `api.circle.com` MCP 搞混。那是另一家。
- 不要给它 `required = true` 挂全局。
- 不要一上来 `--yolo`。触发 pipeline、重跑工作流都是写操作。

网页 Cloud 不读 `~/.codex/config.toml`。改完新开会话。用 `codex mcp get circleci` 看传输是 streamable_http。插件不生效时先确认 `circleci version` 和 `circleci auth me`。

## 来源

- [CircleCI · Getting started with Codex](https://circleci.com/blog/getting-started-with-codex-and-circleci/)
- [CircleCI · Codex plugin](https://circleci.com/blog/circleci-codex-plugin/)
- [CircleCI · Hosted MCP](https://circleci.com/docs/guides/toolkit/connecting-to-the-circleci-mcp-server/)
- [OpenAI · Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)