---
title: "通过 OAuth 或 API key 连接 Omni MCP"
summary: "OAuth 使用 callbacks.omniapp.co/callback/mcp；API key 使用实例的 /mcp/https 地址，并通过环境变量提供凭据。"
category: mcp
level: starter
surfaces: [cli, app, ide]
tags: ["MCP", "Omni", "OAuth", "HTTP"]
canonical: /tips/omni-mcp-http/
---

# 通过 OAuth 或 API key 连接 Omni MCP

OAuth 使用 callbacks.omniapp.co/callback/mcp；API key 使用实例的 /mcp/https 地址，并通过环境变量提供凭据。

Omni 文档包含 Codex 的配置说明。OAuth 是推荐路径。组织管理员先打开：Settings → General 的 Enable AI、AI Hub → Features 的 Omni Agent、AI Hub → MCP 的 MCP server，以及 Settings → API Keys → Personal tokens。OAuth 要 PAT 开关。查询工具和文档搜索跟 Omni Agent 同一条管线；关掉 Agent 后，除 pickModel 外都会 403 Feature is not enabled。

官方远程入口是 `https://callbacks.omniapp.co/callback/mcp`，带 `/callback/mcp`。官方 OAuth 命令：

```bash
codex mcp add omni --url https://callbacks.omniapp.co/callback/mcp
codex
```

```toml
[mcp_servers.omni]
url = "https://callbacks.omniapp.co/callback/mcp"
enabled = true
```

这是 MCP 入口，会在 OAuth 时把你路由到上次登录的 Omni 组织，**不是** Codex 自己的 loopback callback。加入多个组织时，先登出再登进要连的那个，随后登录。若浏览器未打开，运行 `codex mcp login omni`。Omni 会自动创建一个 MCP OAuth PAT，跟普通 PAT 不是一类：任意用户（含 Viewer）都能走完流程，但权限仍跟应用内角色走，Viewer 无法查询数据。这些 PAT 目前不在 Omni 界面里显示。

API key 是另一条 URL。官方示例主机是 `acme.omniapp.co`，路径是 `/mcp/https`，**不是** `/mcp`：

```bash
codex mcp add omni --url https://acme.omniapp.co/mcp/https --bearer-token-env-var OMNI_API_KEY
```

```toml
[mcp_servers.omni]
url = "https://acme.omniapp.co/mcp/https"
bearer_token_env_var = "OMNI_API_KEY"
enabled = true
```

把 `acme.omniapp.co` 换成你的实例。官方 Option A 写成 `codex mcp add omni https://…/mcp/https`，**漏了** `--url`。缺少该参数时，URL 会被当作 stdio 命令。为避免在配置中明文保存密钥，Codex 用 `bearer_token_env_var`，读的是启动 Codex 那个进程里的变量名。从已经 export 的终端启动。从 Dock 或开始菜单启动的桌面应用通常不会加载终端环境变量。Codex 不读 `.env`。

可选范围头可以留在 `http_headers`，它们不是密钥：`X-MCP-Model-ID`、`X-MCP-Topic-Name`、`X-MCP-User-Required`、`X-MCP-User-ID`、`X-MCP-Query-All-Views`。模型 ID 在模型页 URL 的 `/models/…/ide/model` 那段。`X-MCP-Query-All-Views` 要模型也打开 `query_all_views_and_fields`。同名表再 `mcp add` 一次会覆盖；OAuth 入口和 API key 入口应使用不同的服务名，避免两张表都叫 `omni` 的表。

单次查询 `getData` / `runQuery` 默认关，要管理员打开 Single shot query generation。复杂分析才是 `askOmni` + `checkStatus`。改已有 dashboard 会进草稿，要人审再发布；新建 dashboard 会立刻发布。`runQuery` 默认 500 行、上限 10000，带 `userEditedSQL` 的请求会被拒。

可以先询问「Hey Omni, tell me how many users signed up last month」。若工具未出现，请重新打开会话。

网页 Cloud 不读取 `~/.codex/config.toml`。修改后重新打开会话。用 `codex mcp get omni` 看传输是 streamable_http。OAuth 路径的 `/mcp` 应显示 Auth: OAuth。

## 来源

- [Omni · Using the MCP Server in Codex](https://docs.omni.co/ai/mcp/codex)
- [Omni · MCP authentication](https://docs.omni.co/ai/mcp/authentication)
- [Omni · MCP server tools](https://docs.omni.co/ai/mcp/tools)