客户端集成

以 Markdown 格式查看

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

$npm install -g @alephantai/mcp

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

$npx -y @alephantai/mcp

环境变量

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

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

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

Cursor 和 Claude Desktop

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

虚拟密钥模式

1{
2  "mcpServers": {
3    "alephant": {
4      "command": "npx",
5      "args": ["-y", "@alephantai/mcp"],
6      "env": {
7        "ALEPHANT_API_BASE_URL": "https://alephant.io",
8        "ALEPHANT_VIRTUAL_KEY": "vk-..."
9      }
10    }
11  }
12}

Manager 模式

1{
2  "mcpServers": {
3    "alephant-workspace": {
4      "command": "npx",
5      "args": ["-y", "@alephantai/mcp"],
6      "env": {
7        "ALEPHANT_API_BASE_URL": "https://alephant.io",
8        "ALEPHANT_PAT": "pat_...",
9        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
10      }
11    }
12  }
13}

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

Codex

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

1[mcp_servers.alephant]
2command = "npx"
3args = ["-y", "@alephantai/mcp"]
4env = {
5  ALEPHANT_API_BASE_URL = "https://alephant.io",
6  ALEPHANT_VIRTUAL_KEY = "vk-..."
7}
8startup_timeout_sec = 20
9tool_timeout_sec = 120

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

1env = {
2  ALEPHANT_API_BASE_URL = "https://alephant.io",
3  ALEPHANT_PAT = "pat_...",
4  ALEPHANT_WORKSPACE_ID = "00000000-0000-0000-0000-000000000000"
5}

验证服务器注册：

$codex mcp list
$codex mcp get alephant

OpenCode

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

1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "alephant": {
5      "type": "local",
6      "command": ["npx", "-y", "@alephantai/mcp"],
7      "enabled": true,
8      "environment": {
9        "ALEPHANT_API_BASE_URL": "https://alephant.io",
10        "ALEPHANT_VIRTUAL_KEY": "vk-..."
11      }
12    }
13  }
14}

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

Claude Code

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

$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：

1{
2  "mcpServers": {
3    "alephant": {
4      "type": "stdio",
5      "command": "npx",
6      "args": ["-y", "@alephantai/mcp"],
7      "env": {
8        "ALEPHANT_API_BASE_URL": "https://alephant.io",
9        "ALEPHANT_VIRTUAL_KEY": "vk-..."
10      }
11    }
12  }
13}

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

本地开发故障排除

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

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

$npm start
$node ./bin/alephant-mcp.js

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

$cd ..
$npx -y @alephantai/mcp

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

$npx --yes --package=@alephantai/mcp alephant-mcp

定时审计

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

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