ApiVault Remote MCP Server

Secure, encrypted API key management for AI coding agents.
Official remote Model Context Protocol (MCP) server for ApiVault.

Quick Start • Tools Reference • Architecture • OAuth 2.1 & Scopes • Error Codes & Troubleshooting • Self-Hosting & Development

---

Overview

The ApiVault Remote MCP Server allows AI assistants (such as Cursor, Claude Desktop, Windsurf, and Claude Code) to interact with your encrypted secrets in ApiVault safely and auditably.

Instead of pasting raw API keys into chat prompts or committing .env files to git, AI agents can:

1. Search and inspect available credentials using masked previews (e.g. sk_live_••••1234).
2. Request raw secret values only when executing code via scoped permissions.
3. Automatically store newly generated API keys directly into your vault.
4. Support Zero-Knowledge custom vault keys decrypted in-memory on-the-fly.

---

🤖 Official AI Agent Skill

If you use AI coding assistants (Cursor, Claude Code, Windsurf, or Google Antigravity), install the official ApiVault Agent Skill into your workspace:

git clone https://github.com/TLB-STATION/apivault-skill.git .agents/skills/apivault

This equips your AI agents with native runbooks, copy-paste prompt templates, and security guidelines for interacting with ApiVault MCP.

---

Quick Start

1. Cursor

Open Cursor Settings (Cmd/Ctrl + Shift + J) → MCP → Add New MCP Server, or add to your ~/.cursor/mcp.json:

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

---

2. Claude Desktop & Claude.ai

• Method 1 (UI Connector): In Claude Desktop / Claude.ai, navigate to Settings → Connectors → Add Custom Connector, enter Name: ApiVault and Remote URL: https://apivault-mcp.vercel.app/mcp.
• Method 2 (Config File): Add to your Claude Desktop configuration file:
  • 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": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://apivault-mcp.vercel.app/mcp"]
    }
  }
}

---

3. Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

---

4. Claude Code (CLI)

Run in your terminal:

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

---

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

In your extension's MCP Settings JSON:

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

First Connection: When your agent first initializes, a browser tab opens to the main ApiVault website (https://api-vault-opal.vercel.app) to authenticate your account and approve the requested scopes.

---

Tools Reference

The server exposes 6 tools adhering to the Model Context Protocol:

1. list_keys

List stored API keys with masked values (e.g. sk_live_••••1234). Prevents prompt pollution while allowing the agent to discover available services.

• Required Scope: keys:read
• Parameters:
  • environment (string, optional): Filter by environment (e.g. Production, Staging, Development).
  • service (string, optional): Filter by service name (e.g. Stripe, OpenAI, Resend).
• Example Agent Prompt:

  "What Stripe credentials do we have stored in Production?"

---

2. get_key

Retrieve metadata and masked preview for a specific credential by ID.

• Required Scope: keys:read
• Parameters:
  • id (string, required): The unique ID of the key.
• Example Agent Prompt:

  "Check the metadata and last updated date for key 'cm123abc'."

---

3. reveal_key

Decrypt and return the raw, unmasked API key value.

• Required Scope: keys:reveal
• Parameters:
  • id (string, required): The ID of the key to decrypt.
  • vault_key (string, optional): User's custom vault key (required only if the account has Custom Encryption Mode enabled).
• Example Agent Prompt:

  "I need the raw OpenAI API key so I can run the backend integration tests."

---

4. add_key

Securely encrypt and store a new API key in the vault.

• Required Scope: keys:write
• Parameters:
  • name (string, required): Key identifier (e.g. STRIPE_SECRET_KEY, RESEND_API_KEY).
  • key (string, required): Raw secret value to encrypt.
  • service (string, optional): Service name (e.g. Stripe, OpenAI, AWS).
  • environment (string, optional): Target environment (defaults to Production).
  • notes (string, optional): Developer documentation or usage notes.
  • vault_key (string, optional): Custom vault key when required.
• Example Agent Prompt:

  "Store this newly generated Supabase service role key in our Production vault."

---

5. update_key

Update an existing key's metadata or re-encrypt its secret value.

• Required Scope: keys:write
• Parameters:
  • id (string, required): Key ID to update.
  • name, service, environment, notes (string, optional): Metadata updates.
  • key (string, optional): New raw secret value (triggers re-encryption).
  • vault_key (string, optional): Custom vault key when updating secret value.
• Example Agent Prompt:

  "Update the notes on the Resend API key to 'Rotated on August 18'."

---

6. delete_key

Permanently remove an API key from the vault.

• Required Scope: keys:write
• Parameters:
  • id (string, required): Key ID to delete.
• Example Agent Prompt:

  "Delete the deprecated staging database credential."

---

Architecture

The MCP server uses a Stateless Protocol Gateway architecture, separating the public transport layer from the database and cryptographic storage:

+----------------------------------------------------------+
|  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            |
+----------------------------------------------------------+

Security Properties:

1. Zero Database Passwords: The public apivault-mcp service holds no MySQL credentials and no master encryption keys.
2. Stateless Forwarding: Client requests are verified and forwarded to ApiVault's scoped gateway (/api/mcp/v1/keys) using standard OAuth Bearer tokens.
3. In-Memory Vault Keys: Custom encryption mode vault keys (vault_key) are used only in-memory during single-request derivation and are never written to disk or logs.

---

OAuth 2.1 & Scopes

The MCP server implements standard OAuth 2.1 with Dynamic Client Registration (RFC 7591) and PKCE S256 (RFC 7636):

Scope	Name	Grants Access To
keys:read	Read Metadata	list_keys, get_key (masked previews only)
keys:write	Manage Keys	add_key, update_key, delete_key
keys:reveal	Decrypt Secrets	reveal_key (access raw unmasked secret values)

Managing & Revoking Connections

Users can review connected AI agents, inspect granted scopes, and revoke access at any time in the web dashboard: ApiVault Dashboard → Settings → MCP Connections

---

Error Codes & Troubleshooting

Error Code	Reason	Resolution
UNAUTHORIZED	Expired or missing OAuth Bearer token.	Re-authenticate in Cursor or Claude Desktop via the Reconnect action.
INSUFFICIENT_SCOPE	Token lacks the required scope (e.g. tried reveal_key with only keys:read).	Re-authenticate and grant the keys:reveal or keys:write scope during browser consent.
VAULT_KEY_REQUIRED	The account uses Custom Encryption Mode and no vault_key was passed.	Provide your custom vault key in the tool arguments.
INVALID_VAULT_KEY	The supplied custom vault key failed decryption check.	Check that your master vault key is correct and retry.
DUPLICATE_KEY	A key with the same name and environment already exists.	Use update_key or pick a unique key name.
NOT_FOUND	The specified key ID does not exist in your vault.	Use list_keys to verify the active key IDs.
NETWORK_ERROR	Unable to reach the ApiVault backend gateway.	Check internet connectivity and verify API_VAULT_URL.

---

Self-Hosting & Development

You can run your own standalone MCP server or deploy it to your private cloud infrastructure:

Prerequisites

• Node.js >= 20.12.0
• npm or pnpm

1. Clone and Install

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

2. Configure Environment

Create .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. Run Development Server

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

4. Run Test Suite

npm test

5. Build for Production

npm run build
npm start

---

Community & Ecosystem

• Main Platform: ApiVault Web Dashboard
• AI Agent Skill: apivault-skill (GitHub)
• CLI Tool: apivault-cli (npm)
• Documentation: ApiVault Docs & Guides
• Bug Reports & Issues: GitHub Issues

---

License

Distributed under the MIT License. See LICENSE for more information.

Copyright (c) 2026 TLB-STATION • ApiVault