> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 客户端集成

> 在 Cursor、Claude Desktop、Codex、OpenCode 和 Claude Code 中配置 Alephant MCP

Alephant MCP 通过 npm 以 `@alephantai/mcp` 形式发布。大多数客户端可直接使用 `npx` 运行它。

```bash
npm install -g @alephantai/mcp
```

全局安装为可选项。推荐的客户端命令为：

```bash
npx -y @alephantai/mcp
```

## 环境变量

为每个 MCP 服务器条目选择一种凭据模式。

| 变量                        | 必需         | 说明                                       |
| ------------------------- | ---------- | ---------------------------------------- |
| `ALEPHANT_API_BASE_URL`   | 是          | SaaS API 基础 URL，例如 `https://alephant.io` |
| `ALEPHANT_VIRTUAL_KEY`    | VK 模式      | 用于只读 Cockpit 范围工具的虚拟密钥                   |
| `ALEPHANT_PAT`            | Manager 模式 | 个人访问令牌                                   |
| `ALEPHANT_WORKSPACE_ID`   | Manager 模式 | PAT 对应的工作区 UUID                          |
| `ALEPHANT_RATE_LIMIT_RPM` | 否          | 每分钟本地 HTTP 工具调用限制。默认为 `60`；设置为 `0` 可禁用。  |

如果同时存在 `ALEPHANT_PAT` 和 `ALEPHANT_VIRTUAL_KEY`，服务器将使用 Manager 模式。

## Cursor 和 Claude Desktop

对于读取 JSON MCP 配置的客户端，请使用相同的 `mcpServers` 结构。

### 虚拟密钥模式

```json
{
  "mcpServers": {
    "alephant": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}
```

### Manager 模式

```json
{
  "mcpServers": {
    "alephant-workspace": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_PAT": "pat_...",
        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}
```

对于多个工作区，使用诸如 `alephant-prod` 和 `alephant-staging` 的唯一名称复制服务器条目。

## Codex

在 `~/.codex/config.toml` 中添加 stdio MCP 服务器。

```toml
[mcp_servers.alephant]
command = "npx"
args = ["-y", "@alephantai/mcp"]
env = {
  ALEPHANT_API_BASE_URL = "https://alephant.io",
  ALEPHANT_VIRTUAL_KEY = "vk-..."
}
startup_timeout_sec = 20
tool_timeout_sec = 120
```

对于 Manager 模式，将 VK 环境替换为：

```toml
env = {
  ALEPHANT_API_BASE_URL = "https://alephant.io",
  ALEPHANT_PAT = "pat_...",
  ALEPHANT_WORKSPACE_ID = "00000000-0000-0000-0000-000000000000"
}
```

验证服务器注册：

```bash
codex mcp list
codex mcp get alephant
```

## OpenCode

在 OpenCode 配置（例如 `opencode.json`）中的 `mcp` 下添加本地 MCP 服务器。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alephant": {
      "type": "local",
      "command": ["npx", "-y", "@alephantai/mcp"],
      "enabled": true,
      "environment": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}
```

对于 Manager 模式，在 `environment` 中使用 `ALEPHANT_PAT` 和 `ALEPHANT_WORKSPACE_ID` 替换 `ALEPHANT_VIRTUAL_KEY`。

## Claude Code

将 Alephant 添加为本地 stdio 服务器：

```bash
claude mcp add-json alephant '{"type":"stdio","command":"npx","args":["-y","@alephantai/mcp"],"env":{"ALEPHANT_API_BASE_URL":"https://alephant.io","ALEPHANT_VIRTUAL_KEY":"vk-..."}}' --scope user
claude mcp list
claude mcp get alephant
```

对于项目共享配置，请在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "alephant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}
```

对于 Manager 模式，将 VK 环境替换为 `ALEPHANT_PAT` 和 `ALEPHANT_WORKSPACE_ID`。

## 本地开发故障排除

在 `alephant-mcp` 仓库克隆目录中开发时，不要从仓库根目录使用 `npx -y @alephantai/mcp` 对已发布的软件包进行冒烟测试。npm 可能解析为当前本地项目而非注册表软件包。

请在克隆目录中使用以下任一命令：

```bash
npm start
node ./bin/alephant-mcp.js
```

要使用 `npx` 测试已发布的软件包，请在其他目录（例如父目录）中运行：

```bash
cd ..
npx -y @alephantai/mcp
```

如果 bin 解析失败，请使用显式软件包形式：

```bash
npx --yes --package=@alephantai/mcp alephant-mcp
```

## 定时审计

对于本地每周审计，添加一条 cron 条目：

```cron
0 9 * * 1 npx --yes --package=@alephantai/mcp alephant-mcp --audit >> ./AUDIT.md
```