ApiVault Remote MCP Server

安全、加密的 API 密钥管理，适用于 AI 编码代理。
面向 ApiVault 的官方远程 Model Context Protocol (MCP) 服务器。

快速开始 • 工具参考 • 架构 • OAuth 2.1 与作用域 • 错误代码与故障排除 • 自托管与开发

概述

ApiVault Remote MCP Server 允许 AI 助手（如 Cursor、Claude Desktop、Windsurf 和 Claude Code）安全且可审计地与 ApiVault 中的加密机密信息进行交互。

无需再将原始 API 密钥粘贴到聊天提示中，或将 .env 文件提交到 git，AI 代理可以：

1. 使用掩码预览搜索和检查可用的凭据（例如 sk_live_••••1234）。

2. 仅在通过作用域权限执行代码时，才请求原始机密值。

3. 自动将新生成的 API 密钥直接存储到您的保险库中。

4. 支持零知识自定义口令，在内存中即时解密。

快速开始

1. Cursor

打开 Cursor 设置（Cmd/Ctrl + Shift + J）→ MCP → 添加新的 MCP 服务器，或添加到您的 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "apivault": {
      "url": "https://apivault-mcp.vercel.app/mcp"
    }
  }
}

2. Claude Desktop

添加到您的 Claude Desktop 配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows： %APPDATA%\Claude\claude_desktop_config.json

• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apivault": {
      "url": "https://apivault-mcp.vercel.app/mcp"
    }
  }
}

3. Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "apivault": {
      "url": "https://apivault-mcp.vercel.app/mcp"
    }
  }
}

4. Claude Code (CLI)

在终端中运行：

claude mcp add apivault https://apivault-mcp.vercel.app/mcp

5. VS Code (Cline / Roo Code / Continue)

在您的扩展的 MCP 设置 JSON 中：

{
  "mcpServers": {
    "apivault": {
      "url": "https://apivault-mcp.vercel.app/mcp",
      "transport": "http"
    }
  }
}

首次连接： 当您的代理首次初始化时，会打开一个浏览器标签页，跳转到 ApiVault 主网站（https://api-vault-opal.vercel.app）以验证您的帐户并批准所请求的作用域。

工具参考

该服务器提供 6 个符合 Model Context Protocol 的工具：

1. list_keys

列出存储的 API 密钥及其掩码值（例如 sk_live_••••1234）。防止提示污染，同时允许代理发现可用的服务。

• 所需作用域： keys:read

• 参数：

  • environment (string, optional)：按环境筛选（例如 Production、Staging、Development）。

  • service (string, optional)：按服务名称筛选（例如 Stripe、OpenAI、Resend）。

• 示例代理提示词：

  “我们在 Production 环境中存储了哪些 Stripe 凭据？”

2. get_key

按 ID 检索特定凭据的元数据和掩码预览。

• 所需作用域： keys:read

• 参数：

  • id (string, required)：密钥的唯一 ID。

• 示例代理提示词：

  “检查密钥 'cm123abc' 的元数据和最后更新日期。”

3. reveal_key

解密并返回原始、未掩码的 API 密钥值。

• 所需作用域： keys:reveal

• 参数：

  • id (string, required)：要解密的密钥的 ID。

  • vault_key (string, optional)：用户的自定义保险库口令（仅当账户启用了自定义加密模式时才需要）。

• 示例代理提示词：

  “我需要原始 OpenAI API 密钥，以便运行后端集成测试。”

4. add_key

安全地加密并将新的 API 密钥存储在保险库中。

• 所需作用域： keys:write

• 参数：

  • name (string, required)：密钥标识符（例如 STRIPE_SECRET_KEY、RESEND_API_KEY）。

  • key (string, required)：要加密的原始机密值。

  • service (string, optional)：服务名称（例如 Stripe、OpenAI、AWS）。

  • environment (string, optional)：目标环境（默认为 Production）。

  • notes (string, optional)：开发者文档或使用说明。

  • vault_key (string, optional)：需要时提供自定义保险库口令。

• 示例代理提示词：

  “将新生成的 Supabase 服务角色密钥存储到我们的 Production 保险库中。”

5. update_key

更新现有密钥的元数据或重新加密其机密值。

• 所需作用域： keys:write

• 参数：

  • id (string, required)：要更新的密钥 ID。

  • name、service、environment、notes (string, optional)：元数据更新。

  • key (string, optional)：新的原始机密值（触发重新加密）。

  • vault_key (string, optional)：更新机密值时的自定义保险库口令。

• 示例代理提示词：

  “将 Resend API 密钥的备注更新为 'Rotated on August 18'。”

6. delete_key

从保险库中永久删除一个 API 密钥。

• 所需作用域： keys:write

• 参数：

  • id (string, required)：要删除的密钥 ID。

• 示例代理提示词：

  “删除已弃用的暂存数据库凭据。”

架构

MCP 服务器采用 无状态协议网关 架构，将公共传输层与数据库和加密存储分离：

+----------------------------------------------------------+
|  AI Agent (Cursor / Claude Desktop / Windsurf)           |
+----------------------------+-----------------------------+
                             | Streamable HTTP (JSON-RPC)
                             v
+----------------------------------------------------------+
|  ApiVault MCP Server (apivault-mcp.vercel.app)           |
|  - RFC 9728 Protected Resource Metadata (PRM)           |
|  - Streamable HTTP Transport (/mcp)                      |
|  - Zero Database Credentials / Zero Stored Keys          |
+----------------------------+-----------------------------+
                             | Scoped HTTPS REST Gateway (Bearer Token)
                             v
+----------------------------------------------------------+
|  ApiVault Backend (api-vault-opal.vercel.app)            |
|  - OAuth 2.1 Authorization Server (DCR + PKCE S256)      |
|  - Browser Consent UI (/mcp/authorize)                   |
|  - Cryptographic Key Decryption & MySQL Vault            |
+----------------------------------------------------------+

安全属性：

1. 零数据库密码：公共 apivault-mcp 服务不持有任何 MySQL 凭据，也不持有主加密密钥。

2. 无状态转发：客户端请求经过验证后，使用标准 OAuth Bearer 令牌转发到 ApiVault 的作用域网关（/api/mcp/v1/keys）。

3. 内存中的口令：自定义加密模式口令（vault_key）仅在单次请求派生期间于内存中使用，绝不会写入磁盘或日志。

OAuth 2.1 与作用域

MCP 服务器实现了标准 OAuth 2.1，包括 动态客户端注册 (RFC 7591) 和 PKCE S256 (RFC 7636)：

管理与撤销连接

用户可以随时在 Web 仪表板中查看已连接的 AI 代理、检查已授予的作用域并撤销访问权限： ApiVault 仪表板 → 设置 → MCP 连接

错误代码与故障排除

自托管与开发

您可以运行自己的独立 MCP 服务器，或将其部署到您的私有云基础设施：

前提条件

• Node.js >= 20.12.0

• npm 或 pnpm

1. 克隆并安装

git clone https://github.com/TLB-STATION/apivault-mcp.git
cd apivault-mcp
npm install

2. 配置环境

创建 .env.local：

# ApiVault Backend URL
API_VAULT_URL=https://api-vault-opal.vercel.app

# Public URL of this MCP server
MCP_SERVER_URL=http://localhost:3001

3. 运行开发服务器

npm run dev
# Server running at http://localhost:3001

4. 运行测试套件

npm test

5. 为生产环境构建

npm run build
npm start

社区与生态系统

• 主平台： ApiVault Web 仪表板

• CLI 工具： apivault-cli (npm)

• 文档： ApiVault 文档与指南

• 错误报告与问题： GitHub Issues

许可证

根据 MIT 许可证 分发。有关更多信息，请参阅 LICENSE。

版权所有 (c) 2026 Mohamed Eltelb • ApiVault