---
title: "连接 Kapso WhatsApp MCP"
summary: "连接 https://api.kapso.ai/mcp 并通过 OAuth 选择项目。无头环境可使用 KAPSO_API_KEY，文档查询服务单独配置。"
category: mcp
level: intermediate
surfaces: [cli, app, ide]
tags: ["MCP", "Kapso", "WhatsApp", "KAPSO_API_KEY", "env_http_headers"]
canonical: /tips/kapso-codex-mcp/
---

# 连接 Kapso WhatsApp MCP

连接 https://api.kapso.ai/mcp 并通过 OAuth 选择项目。无头环境可使用 KAPSO_API_KEY，文档查询服务单独配置。

连接 https://api.kapso.ai/mcp 并通过 OAuth 选择项目。无头环境可使用 KAPSO_API_KEY，文档查询服务单独配置。

这是 [Kapso Project MCP](https://docs.kapso.ai/docs/whatsapp/mcp) 给 Codex 的远程 HTTP 表，不是 Claude 的 `claude mcp add --transport http`，也不是 `npm install -g @kapso/cli` / `curl … kapso.ai/install.sh`。Project MCP 让代理在没有 shell 的情况下操作 WhatsApp 号码：查会话、发消息、管模板、配 webhook、开 setup link。端点是 `https://api.kapso.ai/mcp`，**带** `/mcp` 后缀。人要先在 Kapso 控制台建好项目，代理才能连。

浏览器登录（本机有交互时走这条）：

```bash
codex mcp add kapso --url https://api.kapso.ai/mcp
codex mcp login kapso
```

浏览器打开后登录 Kapso，选要交给这台客户端的那个项目。不要把项目 id 拼进 URL。

无头 / CI 才用项目 API key。变量必须在**启动 Codex 的那个进程**里，Codex 不读 `.env`：

```bash
export KAPSO_API_KEY=YOUR_KAPSO_API_KEY
codex mcp add kapso --url https://api.kapso.ai/mcp --bearer-token-env-var KAPSO_API_KEY
```

```toml
[mcp_servers.kapso]
url = "https://api.kapso.ai/mcp"
bearer_token_env_var = "KAPSO_API_KEY"
enabled = true
```

Bearer 这条**不要**再 `mcp login kapso`。`KAPSO_API_KEY` 填的是变量**名**，不要把密钥字面量写进 `http_headers`。

Codex 没有 `--header`。要用 `X-API-Key` 时写 `~/.codex/config.toml`：

```toml
[mcp_servers.kapso]
url = "https://api.kapso.ai/mcp"
env_http_headers = { "X-API-Key" = "KAPSO_API_KEY" }
enabled = true
```

右边仍是变量名。缺变量或空值时该请求头会静默丢掉。不要把密钥写进 `http_headers`。

工具是分组的，多数接受 `action` + `params`。先 `status` 看鉴权、客户数、号码数和下一步；分组工具先 `action: "help"`。常见组：`search_docs`、`customers`、`setup_links`、`whatsapp_numbers`、`whatsapp_conversations`、`whatsapp_messages`、`whatsapp_templates`、`whatsapp_webhooks`、`findings`。发消息、改 webhook、删号码保持批准。保持工具调用审批。

Docs MCP 是**另一张**表，只查文档：

```bash
codex mcp add kapso-docs --url https://docs.kapso.ai/mcp
```

不要和 Project MCP 的 `kapso` 叠成一台。不要把 `https://docs.kapso.ai/mcp` 当成发 WhatsApp 的入口。

技能是另一条，官方未明确指定 `--agent codex`：

```bash
npx skills add gokapso/agent-skills
```

不要把 `npx skills add` 当 Codex MCP 安装器。仓库 README 可能 404，以文档页为准。

网页 Cloud 不读 `~/.codex/config.toml`。改完新开会话。用 `codex mcp get kapso` 看传输是 streamable_http，url 是 `https://api.kapso.ai/mcp`。

## 来源

- [Kapso · Project MCP](https://docs.kapso.ai/docs/whatsapp/mcp)
- [Kapso · Build with AI](https://docs.kapso.ai/docs/build-with-ai)
- [Kapso · CLI](https://docs.kapso.ai/docs/whatsapp/cli)