将 Oracle Integration Cloud MCP 服务器连接到 macOS 系统上的 Codex。
配置 OAuth 客户端凭证,获取访问令牌,在 Codex 中注册 OIC 项目的 MCP 服务器,并确认其工具能显示在 CLI 和桌面应用中。
那些已经使用 Oracle Integration Cloud (OIC) 来连接应用程序的团队,可以通过模型上下文协议将合适的集成功能暴露给 Codex。Codex 会将这些集成识别为工具,在需要时调用它们。例如,一个用于查询订单信息的集成,只要配置和发布正确,就可以成为 Codex 用来回答与该订单相关问题的工具。
在这里,我们将一个 OIC 项目中的 MCP 服务器连接到 macOS 上的 Codex。你需要收集一些配置值,申请 OAuth 访问令牌,注册服务器,并确认 Codex 能够看到这些工具。内容还涵盖了桌面应用所需的额外环境设置,以及令牌用尽时该怎么做。它假设你已经拥有 OIC 环境,并且已经有人为此在 OCI IAM 中准备了 OAuth 应用程序。
涉及的组件
共有四个组成部分:
- Oracle Integration Cloud 负责托管与你的应用程序和服务进行交互的集成功能。
- OIC 项目中的 MCP 服务器会发布那些被注册为 Agentic AI 工具的集成功能。
- Codex 则是 MCP 客户端,它能够找到这些工具并在适当的时候使用它们。
请求的传输路径为:Codex,然后是 OIC MCP 服务器,接着是已注册的集成组件,最后是连接的应用程序。
Codex 在能够访问服务器之前,需要使用 OAuth 应用程序的客户端凭据向 OCI IAM 请求一个短期有效的访问令牌。该令牌随后会通过环境变量传递给 Codex。
需先完成的准备工作
在操作终端之前,请先完成 OIC 及身份配置。您需要:
- 一个已启用 MCP 服务器选项的 OIC 项目。
- 至少一个作为 Agentic AI 工具注册的活跃集成组件。
urn:opc:resource:consumer::all在内的资源范围。https://<identity_domain>.identity.oraclecloud.com。您只需使用 <identity_domain> 这部分内容,无需包含协议或后缀。对于 https://example123.identity.oraclecloud.com,对应的就是 example123。如果列表中有任何项目缺失,请立即解决,否则无法建立连接。
步骤 1:准备终端
在您的 Mac 上打开 Terminal。以下所有操作均以 zsh 为前提。
检查 Codex 和 jq 是否已安装
运行以下命令:
codex --version
command -v jq
第一行应输出 Codex 版本号。第二行应输出用于从认证响应中提取令牌的 jq 的路径。
如果缺少 jq 但已安装 Homebrew:
brew install jq
设置您的数值
将每个<尖括号>占位符替换为您自己的数值,然后运行:
export OIC_CLIENT_ID='<CLIENT_ID>'
export OIC_RESOURCE_SCOPE='<RESOURCE_SCOPE>'
export OIC_IDENTITY_DOMAIN='<IDENTITY_DOMAIN>'
export OIC_MCP_URL='https://<oic-instance-host>.integration.<region>.ocp.oraclecloud.com/mcp-server/v1/projects/<project-identifier>/mcp'
各变量的含义:
OIC_CLIENT_ID是您 OAuth 机密应用程序的客户端 ID。OIC_RESOURCE_SCOPE包含为 OIC 配置的完整范围字符串,其中包含urn:opc:resource:consumer::all元素。OIC_IDENTITY_DOMAIN是.identity.oraclecloud.com之前的部分,例如example123。OIC_MCP_URL是从“MCP 服务器运行地址”字段复制的完整项目专用 URL。
请勿将客户端密钥放入此区域,下一步会通过隐藏输入字段来请求该密钥。
检测缺失值及残留的占位符
此部分会确认四个变量均包含有效内容,且没有变量仍含有尖括号:
(
setup_ready=true
for name in \
OIC_CLIENT_ID \
OIC_RESOURCE_SCOPE \
OIC_IDENTITY_DOMAIN \
OIC_MCP_URL
do
value="${(P)name}"
if [[ -z "$value" || "$value" == *'<'* || "$value" == *'>'* ]]; then
printf 'Check %s: missing value or unreplaced placeholder.\n' "$name"
setup_ready=false
fi
done
if [[ "$setup_ready" == true ]]; then
printf 'Required values are populated and contain no placeholders.\n'
fi
)
它仅检查值是否存在,而不验证凭证、作用域或URL是否正确。请保持此终端会话打开,因为下一步会重新使用这些变量。
步骤2:获取OAuth访问令牌
在同一个会话中,运行下面的代码块。它会要求输入客户端密钥,向OCI IAM请求令牌,并将该令牌提供给Codex CLI以及之后启动的桌面应用。输入或粘贴密钥后按回车键。输入时屏幕上不会显示任何内容。
read -rs 'OIC_CLIENT_SECRET?OIC client secret: '
printf '\n'
if token="$(
curl --silent --show-error --fail \
--user "${OIC_CLIENT_ID}:${OIC_CLIENT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "scope=${OIC_RESOURCE_SCOPE}" \
"https://${OIC_IDENTITY_DOMAIN}.identity.oraclecloud.com:443/oauth2/v1/token" \
| jq -er '.access_token'
)"; then
unset OIC_CLIENT_SECRET
export OIC_ACCESS_TOKEN="$token"
unset token
if launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"; then
echo 'Access token received and set for CLI and newly launched desktop apps.'
else
echo 'Access token set for CLI, but desktop environment setup failed.' >&2
fi
else
unset OIC_CLIENT_SECRET token
echo 'ERROR: Token request failed. Check your values and OAuth configuration.' >&2
fi
成功时它会输出:
Access token received and set for CLI and newly launched desktop apps.
由于提示信息是静默的,该密钥永远不会出现在你的 shell 历史记录中,而且脚本在令牌请求完成后会立即清除该密钥变量。
确认令牌存在
此检查会报告令牌的存在情况,而不会打印出令牌内容:
[[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
&& echo 'OIC access token is present' \
|| echo 'ERROR: OIC access token is missing'
这证明了该变量确实具有值。只有当 Codex 实际与服务器通信时,OIC 才会确定是否接受该令牌。
对于桌面应用,需完全关闭 Codex,待 launchctl setenv 操作成功后重新打开,这样它才能看到更新后的环境变量。
请将此令牌视为机密信息,切勿将其输出到终端,也不要粘贴到聊天记录、邮件、工单或文档中。
步骤 3:在 Codex 中注册服务器
拿到令牌后,在同一会话中运行以下命令:
codex mcp add oic \
--url "$OIC_MCP_URL" \
--bearer-token-env-var OIC_ACCESS_TOKEN
这样就会使用第一步中的 URL,将服务器以 oic 为名称添加到 Codex 中。通过 --bearer-token-env-var 参数,Codex 在连接时会从 OIC_ACCESS_TOKEN 变量中查找令牌。请提供不带美元符号的变量名,这样存储的配置才会引用该变量,而不会获取当前时刻的令牌值。
第 4 步:检查配置
列出已配置的服务器并查看新添加的服务器:
codex mcp list
codex mcp get oic
请确保:
- 服务器名为
oic且处于启用状态; - URL与您的OIC项目的MCP端点一致;
- 传输方式为
streamable_http; - bearer-token变量值为
OIC_ACCESS_TOKEN。
如果服务器不存在、处于禁用状态或URL设置错误,请先修复这些问题再继续操作。
第5步:通过CLI查找工具
在导出过 OIC_ACCESS_TOKEN 的终端中启动Codex,这样它就能继承该令牌:
codex
打开后,输入以下提示语:
List the tools available from every MCP server with oic in its name.
您应该会看到您的 OIC 项目所提供的工具列表。如果列表为空,请返回 OIC 并确认项目中是否有已激活的集成被注册为 Agentic AI 工具。如果 Codex 报出认证错误,请重新检查 OAuth 设置,执行第 2 步以获取新的令牌,然后从该终端重新启动 Codex。
第 6 步:在桌面应用中使用它
在打开应用之前,请确保已完成第 2 步,包括执行以下命令:
launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"
如果在第2步已经成功,就无需重复操作。请完全退出桌面应用程序后再重新启动,这样它才能读取令牌。虽然两个客户端使用相同的MCP配置,但在单个终端会话中导出的变量无法自动传递到桌面应用程序中。
启动一个新的Codex任务,然后输入:
/mcp
确认oic已出现,然后发送相同的发现提示:
List the tools available from every MCP server with oic in its name.
Codex 应列出您 OIC 项目中的工具。
令牌过期时
访问令牌的有效期较短,其时长遵循您的 OCI IAM 设置。要重新建立连接:
- 返回设置终端,或重新输入第一步中的参数。
- 重复第二步以获取新令牌并更新桌面环境。
- 退出并重新打开桌面应用程序。对于命令行使用,需在包含新令牌的终端中启动新的 Codex 会话。
除非服务器的配置被删除或更改,否则无需再次注册。
故障排除说明
这种设置下会反复出现几种故障模式:
- 如果令牌请求立即失败,通常是由于客户端 ID、密钥或作用域有误,或者身份域值仍包含
https://前缀或后缀所致。