提示Win11下给Codex配置 Jira MCP 的完整教程codex读取wiki页面需求文档并产出设计文档codex读取观测云日志claudeccswitch读取数据库、claudeccswitch读取wiki、jira、claude帮我读取日志扫描代码、cursorclaudecodexminimaxright code使用分享心得用 Docker 给 Codex 配置 Jira / Wiki MCP、MCP常见问题排查文章目录前言一、效果图二、概念介绍1、MCP是什么2、MCP原理3、各角色职责3.1、AI Client3.2、MCP Server3.3、业务系统4、MCP 通信方式4.1、stdio4.2、Streamable HTTP三、前置操作1、安装docker2、安装Node.js和npm3、安装或更新Codex4、准备Jira/Confluence凭证5、拉取、验证wiki的Mcp镜像6、ccswitch四、修改配置1、找到codex配置文件2、写入Jira MCP 配置(不要怕麻烦文章末尾有我的配置直接粘贴改一下即可)3、解释Jira MCP各配置含义3.1、command 和 args3.2、-e 和 [mcp_servers.jira.env]3.3、TOOLSETS3.4、ENABLED_TOOLS3.5、READ_ONLY_MODE4、同时配置 Confluence / Wiki5、重启codex并验证五、常见问题排查1. /mcp 显示 Tools: (none)2. Docker 提示镜像拉取失败3. Codex 能看到 MCP Server但调用工具时报 401 / 4034. 调用工具一直超时5. 不要把日志写到 stdout六、MCP 能做什么不能做什么1、MCP 能做什么2、MCP 不能做什么七、从 0 到 1 配置 MCP 的完整流程总结八、我个人的完整配置文件总结前言现在 AI 工具已经从“聊天助手”逐渐变成“研发助手”。普通聊天模型只能根据你输入的文本回答问题但研发工作里的真实上下文往往分散在 Jira、Confluence / Wiki、数据库、日志平台、代码仓库、内部 API 里。如果每次都靠人工复制粘贴效率很低也容易漏信息。MCP 的价值就在这里它把外部系统包装成 AI 客户端可以调用的工具让 Codex、Claude、Cursor 等客户端能够在授权范围内读取业务系统的数据。举几个常见场景让 Codex 读取 Jira 需求单然后生成设计文档。让 Codex 读取 Confluence / Wiki 页面理解业务背景。让 Codex 查询日志系统定位线上报错。让 Claude / Cursor 查询数据库辅助分析问题。让 AI 调用内部 API完成研发流程中的固定动作。本文不只贴配置还会解释为什么要这么配。读完之后你应该能知道MCP 是什么。MCP Client、MCP Server、业务系统分别是什么角色。stdio传输方式是什么意思。Win11 下如何给 Codex 配置一个 Jira / Wiki MCP。如何验证 MCP 是否配置成功。常见错误如何排查。目前已经使用过claude、codex、cursor、minimax、kimi、right code。。。我个人认为目前最好用的无疑是claude但是claude封的过快导致几乎不可用。(刚用完没两天就不能用了)其次便是codex。本次便是分享的codex。截止到目前为止我仅保留了2种AIright Code、miniMax。right Code无疑是“真香”甩国产几条街没有对比就没有伤害。(感兴趣的话可以点击这个按钮这个按钮对应的文章就是right code自动生成的)。nimiMax是国产的保留它是因为它的优势很明显量大管饱且便宜。一年12个月才399399对应的miniMax是每5小时1500条无疑是非常适合高频问简单问题的针对于程序员日常开发这个流量绰绰有余甚至一个团队的日常开发也能满足。如果大家有需要的话可以访问。rightcode的地址地址(按流量计费)minimax的地址地址(399一年)话不多说咱们上干货。一、效果图俗话说有图有真相没图没朋友。放两张图大家看一下二、概念介绍1、MCP是什么MCP全称 Model Context Protocol可以理解为“让 AI 助手连接外部系统的一套标准协议”。一句话解释MCP 是一套标准协议用来让 AI 客户端安全、统一地连接外部系统和工具。这里的“AI 客户端”可以是CodexClaude Desktop / Claude CodeCursorCline其他支持 MCP 的 IDE 或 Agent 工具这里的“外部系统”可以是JiraConfluence / WikiGitLab / GitHub数据库日志平台文件系统内部业务 API浏览器自动化工具任何可以被程序访问的系统没有 MCP 时不同 AI 工具要接 Jira、接数据库、接日志平台都要各写一套私有插件。MCP 做的事情就是把这类连接方式标准化。简单总结你可以把 MCP 想象成 AI 世界里的“USB-C 接口”2、MCP原理MCP 的整体链路可以这样理解AI Client 例如 Codex / Claude / Cursor||MCP 协议vMCP Server 例如 Jira MCP / GitHub MCP / 数据库 MCP / 日志 MCP||HTTP / JDBC / SDK / RPC / 文件系统 / 数据库协议v业务系统 例如 Jira / Wiki / MySQL / 日志平台 / 内部服务各角色的职责如下。3、各角色职责3.1、AI ClientAI Client 是你正在使用的 AI 工具比如 Codex。它负责读取 MCP 配置。启动或连接 MCP Server。获取 MCP Server 暴露了哪些工具。在模型需要时调用这些工具。把工具返回的结果交给模型继续推理。你在 Codex 里看到的/mcp本质上就是查看当前客户端已经连接了哪些 MCP Server以及这些 Server 暴露了哪些工具。3.2、MCP ServerMCP Server 是一个普通程序可以用 Node.js、Python、Go、Java、Rust 等语言实现。它负责对外遵守 MCP 协议。对内调用真实业务系统。把业务系统能力包装成一个个工具。例如 Jira MCP Server 可能暴露这些工具jira_get_issuejira_searchjira_get_project_issuesjira_get_agile_boardsjira_get_board_issuesjira_get_sprints_from_boardjira_get_sprint_issues这些工具背后真正调用的是 Jira 的 REST API。3.3、业务系统业务系统就是 MCP Server 最终要访问的数据源或服务。例如Jira MCP Server 访问 Jira API。Confluence MCP Server 访问 Confluence API。MySQL MCP Server 访问 MySQL。日志 MCP Server 访问日志平台 API。所以 MCP 不是替代业务系统也不是让模型直接连数据库。更准确地说MCP Server 是一个“受控代理层”它决定 AI 能访问什么、怎么访问、是否只读、是否需要鉴权。4、MCP 通信方式MCP 协议使用 JSON-RPC 来编码请求和响应。官方协议中常见的传输方式主要有两类stdioStreamable HTTP4.1、stdiostdio是 standard input / standard output 的缩写也就是标准输入和标准输出。在stdio模式下AI Client 会启动一个本地 MCP Server 子进程然后Client 往 Server 的stdin写入 MCP 请求。Server 从stdin读取请求。Server 把 MCP 响应写到stdout。Client 从stdout读取响应。Server 的日志一般写到stderr。在 stdio 模式下Codex||启动本地子进程vdockerrun-i--rmghcr.io/sooperset/mcp-atlassian:latest--transportstdio||stdin / stdoutvMCP Server||Jira REST API / Confluence REST APIvJira / Confluencestdio的特点适合本地工具。不需要单独开放端口。生命周期通常由客户端管理。Client 关闭后Server 子进程也会退出。Server 的stdout必须只输出合法 MCP 消息普通日志不要写到stdout。这就是为什么 Docker 命令里经常能看到-i因为 MCP Server 需要通过标准输入持续读取客户端发来的协议消息。4.2、Streamable HTTPStreamable HTTP 更适合远程服务。这种方式下MCP Server 是一个独立运行的 HTTP 服务客户端通过 HTTP endpoint 访问它。适合这些场景团队共用一个 MCP Server。Server 部署在内网服务器或 Kubernetes 中。需要统一网关、鉴权、审计、限流。不希望每个客户端都本地启动一个进程。本文使用 Docker stdio因为它最适合个人本地配置步骤也最简单。三、前置操作1、安装dockerWin11 推荐安装 Docker Desktop。安装完成后打开 PowerShell 或 CMD执行docker--version docker run hello-world能正常输出版本号并且hello-world能运行说明 Docker 基本可用。2、安装Node.js和npmCodex CLI 通常通过 npm 安装因此需要先安装 Node.js。验证命令node-v npm-v如果能输出版本号说明 Node.js 和 npm 已安装成功。node -v npm -v docker --version3、安装或更新Codex执行npm install-g openai/codex安装完成后验证codex--version codex如果能进入 Codex 命令行界面说明安装成功。如果你是第一次安装codex直接执行上面的命令就行如果你不是第一次安装就需要删除旧的codex的缓存不然一些配置可能是旧的会影响你后续的mcp配置。删除很简单 将 C:\Users\Administrator 下的 (用户的文件夹不一定是Administrator ).codex 文件夹整个删除。效果是winr输入cmd按回车弹出来的命令行中输入codex看到的效果是 openAI Codex如下图4、准备Jira/Confluence凭证至少需要准备JIRA_URL JIRA_USERNAME JIRA_API_TOKEN 或 JIRA_PERSONAL_TOKEN示例JIRA_URLhttps://jira.example.com JIRA_USERNAMEyour-nameexample.com JIRA_API_TOKENxxxxxxxx如果你还要读取 Confluence / Wiki通常还需要CONFLUENCE_URL CONFLUENCE_USERNAME CONFLUENCE_API_TOKEN 或 CONFLUENCE_PERSONAL_TOKEN具体字段以所使用的 MCP Server 文档为准。文章末尾我会贴上我的配置文件防止大家写错。5、拉取、验证wiki的Mcp镜像先拉取镜像docker pull ghcr.io/sooperset/mcp-atlassian:latest再检查镜像是否存在docker image inspect ghcr.io/sooperset/mcp-atlassian:latest这一步的意义是先排除网络、Docker、镜像拉取问题。不要一上来就改 Codex 配置否则排错范围会很大。6、ccswitchccswitch是方便你切换AI工具的可安装可不安装。简单的说ccswitch其实是方便你管理你的配置文件的。不安装也不影响后续的操作我为了方便管理就安装了。如果安装的话可以这么配置配置后的效果四、修改配置运行方式依赖 Docker所以需要先确认Win11 已安装 Docker DesktopDocker Desktop 正常运行当前机器能访问 Jira 地址已准备好 Jira 访问凭据1、找到codex配置文件修改前建议先备份如果改错了可以用备份文件恢复。在 Win11 上Codex 的全局配置文件一般在当前用户目录下C:\Users\你的用户名\.codex\config.toml本次机器上的实际路径是C:\Users\Administrator\.codex\config.toml这是全局配置不是当前聊天窗口的临时配置。也就是说只要改的是这个文件关闭当前 Codex 窗口后新开 Codex 仍然会读取这份配置。2、写入Jira MCP 配置(不要怕麻烦文章末尾有我的配置直接粘贴改一下即可)推荐配置如下[mcp_servers.jira]commanddockerargs[run,-i,--rm,-e,JIRA_URL,-e,JIRA_USERNAME,-e,JIRA_API_TOKEN,-e,JIRA_PERSONAL_TOKEN,-e,TOOLSETS,-e,ENABLED_TOOLS,-e,READ_ONLY_MODE,ghcr.io/sooperset/mcp-atlassian:latest,--transport,stdio][mcp_servers.jira.env]JIRA_URLhttps://jira.example.comJIRA_USERNAMEyour-nameexample.comJIRA_API_TOKENyour-api-tokenJIRA_PERSONAL_TOKENyour-personal-tokenTOOLSETSjira_issues,jira_agile,jira_projects,jira_fieldsENABLED_TOOLSjira_get_issue,jira_search,jira_get_project_issues,jira_get_agile_boards,jira_get_board_issues,jira_get_sprints_from_board,jira_get_sprint_issues,jira_get_project_versions,jira_get_all_projects,jira_search_fields,jira_get_field_options,jira_batch_get_changelogsREAD_ONLY_MODEtrue3、解释Jira MCP各配置含义3.1、command和argscommand docker args [run, -i, --rm, ...]意思是Codex 启动 MCP Server 时实际执行的是docker run-i--rm...其中docker是启动命令。args是传给docker的参数。-i表示保持标准输入打开stdio 模式必须要有。--rm表示容器退出后自动删除避免残留大量临时容器。3.2、-e和[mcp_servers.jira.env]Docker 命令里的-e, JIRA_URL表示把环境变量JIRA_URL传给容器。下面这段[mcp_servers.jira.env] JIRA_URL https://jira.example.com表示 Codex 启动进程时先设置环境变量再让 Docker 把这些变量传进容器。所以完整链路是Codex config.toml - Codex 启动 docker run - Docker 把环境变量传入容器 - 容器里的 MCP Server 读取环境变量 - MCP Server 调用 Jira API3.3、TOOLSETSTOOLSETS用来指定启用哪些工具集合。示例TOOLSETS jira_issues,jira_agile,jira_projects,jira_fields不要简单写成TOOLSETS jira很多 MCP Server 对 toolset 名称有严格要求写错后可能出现/mcp能看到 server但 tools 为空。3.4、ENABLED_TOOLSENABLED_TOOLS用来显式指定暴露哪些工具。好处是减少无关工具。降低误操作风险。让模型可用工具更清晰。出问题时更容易排查。3.5、READ_ONLY_MODE建议先设置READ_ONLY_MODE true这表示只读模式。也就是 AI 可以读取 Jira但不能创建、修改、删除 Jira 内容。第一次配置 MCP 时不建议直接开放写能力。等你确认工具行为稳定、权限范围明确、团队安全规范允许后再考虑开放写操作。4、同时配置 Confluence / Wiki如果你要让 Codex 读取 Wiki可以在同一个mcp-atlassian中开启 Confluence 相关配置。示例[mcp_servers.atlassian] command docker args [ run, -i, --rm, -e, JIRA_URL, -e, JIRA_USERNAME, -e, JIRA_API_TOKEN, -e, CONFLUENCE_URL, -e, CONFLUENCE_USERNAME, -e, CONFLUENCE_API_TOKEN, -e, TOOLSETS, -e, ENABLED_TOOLS, -e, READ_ONLY_MODE, ghcr.io/sooperset/mcp-atlassian:latest, --transport, stdio ] [mcp_servers.atlassian.env] JIRA_URL https://jira.example.com JIRA_USERNAME your-nameexample.com JIRA_API_TOKEN your-jira-token CONFLUENCE_URL https://wiki.example.com CONFLUENCE_USERNAME your-nameexample.com CONFLUENCE_API_TOKEN your-confluence-token TOOLSETS jira_issues,jira_agile,jira_projects,jira_fields,confluence_search,confluence_pages ENABLED_TOOLS jira_get_issue,jira_search,jira_get_project_issues,jira_get_agile_boards,jira_get_board_issues,jira_get_sprints_from_board,jira_get_sprint_issues,confluence_search,confluence_get_page READ_ONLY_MODE true注意不同版本的mcp-atlassian支持的 toolset 和 tool 名称可能不同。如果/mcp中没有看到 Confluence 工具需要回到该 MCP Server 的 README 或启动日志里确认具体名称。5、重启codex并验证修改config.toml后关闭当前 Codex 会话重新打开 Codex。进入新会话后执行/mcp成功时应该能看到jira Tools: jira_get_issue, jira_search, ...然后可以做一次真实验证请读取 Jira 单 SCRD-19749并总结它的标题、状态、负责人、需求背景和验收标准。如果要验证搜索能力请在 Jira 中搜索 project SCRD AND status ! Done 的最近 10 个需求单。如果要验证 Wiki请搜索标题包含“订单调度”的 Wiki 页面并总结最相关的一篇。五、常见问题排查1./mcp显示Tools: (none)这是最常见问题。优先检查TOOLSETS是否写错。ENABLED_TOOLS里的工具名是否真实存在。Docker 镜像版本是否支持这些工具。容器启动后是否因为鉴权失败退出。stdout是否被普通日志污染。排查思路先确认 Docker 能运行 再确认 MCP Server 能启动 再确认环境变量正确 最后确认 toolset / tool 名称正确2. Docker 提示镜像拉取失败可能原因网络无法访问ghcr.io。公司网络代理限制。Docker Desktop 没有启动。DNS 解析失败。可以先执行docker pull ghcr.io/sooperset/mcp-atlassian:latest如果这一步失败说明问题还没到 Codex 层。3. Codex 能看到 MCP Server但调用工具时报 401 / 403这是鉴权问题。检查JIRA_URL是否正确。用户名是否正确。Token 是否过期。Token 是否有权限访问目标项目。公司 Jira 是否需要 VPN 或内网环境。Jira Cloud 和 Jira Server / Data Center 的认证方式是否混用了。4. 调用工具一直超时可能原因本机访问不了 Jira / Wiki。VPN 未连接。Jira 地址需要代理。Docker 容器内网络访问不到公司内网。MCP Server 启动慢或被防火墙拦截。可以先在宿主机验证curl https://jira.example.com如果宿主机能访问但容器访问不了需要重点检查 Docker Desktop 网络、代理和 VPN。5. 不要把日志写到 stdoutstdio 模式下stdout是 MCP 协议通道必须输出合法 JSON-RPC 消息。如果 MCP Server 把普通日志写到stdout客户端可能解析失败。日志应该写到stderr。如果你自己写 MCP Server这一点非常重要。六、MCP 能做什么不能做什么1、MCP 能做什么MCP 能让 AI读取外部系统数据。调用被授权的工具。基于真实上下文回答问题。把多个系统的信息串起来分析。自动化部分研发流程。例如读取 Jira 需求 - 读取 Wiki 背景 - 扫描代码 - 生成技术方案再比如读取线上报错日志 - 根据 traceId 定位链路 - 扫描相关代码 - 给出修复建议2、MCP 不能做什么MCP 不是万能的。它不能绕过权限用户没有权限访问 Jira 项目MCP 也不应该访问到。它不能保证模型一定理解正确MCP 只负责把数据取回来最终怎么推理仍然取决于模型能力和提示词质量。它也不能替代安全治理该审计的要审计该脱敏的要脱敏该只读的要只读。七、从 0 到 1 配置 MCP 的完整流程总结完整流程可以按下面顺序走1. 明确你要接入什么系统 例如 Jira / Wiki / 数据库 / 日志平台 2. 找到或开发对应的 MCP Server 例如 mcp-atlassian 3. 确认运行方式 本地个人使用优先 stdio 团队共享服务优先 Streamable HTTP 4. 准备运行环境 Node.js / npm / Docker / VPN / 网络代理 5. 准备访问凭证 URL / username / token / personal access token 6. 单独验证 MCP Server 能启动 先排除 Docker、镜像、网络问题 7. 修改 AI Client 配置 例如 Codex 的 config.toml 8. 重启 AI Client 让配置生效 9. 使用 /mcp 验证工具是否注册成功 10. 用真实问题验证工具调用 例如读取一个 Jira 单 11. 做安全收敛 只读模式、最小权限、最小工具集八、我个人的完整配置文件C:\Users\Administrator.codex 下的 config.toml 文件model_providerrightcodemodelgpt-5.4model_reasoning_effortmediumdisable_response_storagetrue[model_providers.rightcode]namerightcodebase_urlhttps://right.codes/codex/v1wire_apiresponsesrequires_openai_authtrue[mcp_servers.wiki]typestdiocommanddockerargs[run,-i,--rm,-e,CONFLUENCE_URL,-e,CONFLUENCE_USERNAME,-e,CONFLUENCE_API_TOKEN,-e,CONFLUENCE_PERSONAL_TOKEN,-e,TOOLSETS,ghcr.io/sooperset/mcp-atlassian:latest,--transport,stdio][mcp_servers.wiki.env]CONFLUENCE_API_TOKENNjkyODgyO——后面我给去掉了是你个人对应的tokenCONFLUENCE_PERSONAL_TOKENNjkyOD——后面我给去掉了是你个人对应的tokenCONFLUENCE_URLhttps://wiki.hoxxcloud.comCONFLUENCE_USERNAMEzhengxxxxxxxcloud.comTOOLSETSconfluence_pages[mcp_servers.jira]typestdiocommanddockerargs[run,-i,--rm,-e,JIRA_URL,-e,JIRA_USERNAME,-e,JIRA_API_TOKEN,-e,JIRA_PERSONAL_TOKEN,-e,TOOLSETS,-e,ENABLED_TOOLS,-e,READ_ONLY_MODE,ghcr.io/sooperset/mcp-atlassian:latest,--transport,stdio][mcp_servers.jira.env]ENABLED_TOOLSjira_get_issue,jira_search,jira_get_project_issues,jira_get_agile_boards,jira_get_board_issues,jira_get_sprints_from_board,jira_get_sprint_issues,jira_get_project_versions,jira_get_all_projects,jira_search_fields,jira_get_field_options,jira_batch_get_changelogsJIRA_API_TOKENMjI3ODA——后面我给去掉了是你个人对应的tokenJIRA_PERSONAL_TOKENMjI3ODA——后面我给去掉了是你个人对应的tokenJIRA_URLhttps://jira.xxxcloud.comJIRA_USERNAMEzhengtxxghxxcloud.comREAD_ONLY_MODEtrueTOOLSETSjira_issues,jira_agile,jira_projects,jira_fields[projects.c:\users\administrator]trust_leveltrusted[projects.c:\windows\system32]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-flight-6]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-train-3-master]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-flight-9-master]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-flight-3-dev]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-sms-3-kaifa]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-train-2-merge]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-hotel]trust_leveltrusted[projects.d:\ruanjian\java\idea\file\mall-hotel-order-merge]trust_leveltrusted[tui.model_availability_nux]gpt-5.54[windows]sandboxelevated总结MCP 的核心不是“某个配置文件怎么写”而是把外部系统能力标准化地暴露给 AI 客户端。对个人开发者来说最容易落地的方式是Codex Docker stdio MCP Server 只读 Token先用 Jira / Wiki 这种低风险读操作跑通再逐步扩展到日志、数据库、内部 API。只要理解了AI Client - MCP Server - 业务系统这条链路后面接入任何 MCP 都是同一套思路。