ApiVault MCP Server

Quick Setup

Use the add-mcp CLI to automatically configure ApiVault MCP across all detected AI tools:

npx -y add-mcp https://mcp.apivault.tech/mcp -g

The add-mcp utility detects installed editors (Cursor, Claude Desktop, Windsurf, VS Code) and automatically registers the remote endpoint.

Official AI Agent Skill

For AI assistants like Cursor, Claude Code, Windsurf, or Google Antigravity, you can install the official ApiVault Agent Skill. It gives your AI agents native runbooks and workflows to browse, inject, and manage encrypted credentials safely without risking secret leakage in chat logs.

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

Alternatively, paste this prompt into any AI agent to let it install and configure the skill automatically:

Please install the ApiVault skill for this workspace by cloning https://github.com/TLB-STATION/apivault-skill.git into .agents/skills/apivault. Read .agents/skills/apivault/SKILL.md to learn how to manage ApiVault keys and connect to the MCP server.

What is ApiVault MCP?

ApiVault MCP is the official remote Model Context Protocol server for ApiVault. It provides AI agents with fine-grained, auditable access to your encrypted credentials without ever placing raw secrets in prompt histories or checking .env files into version control.

It implements the official Streamable HTTP transport and OAuth 2.1 authorization specifications with Dynamic Client Registration (RFC 7591) and PKCE S256 (RFC 7636).

Project-Scoped Connections & RBAC

In ApiVault's multi-project environment, MCP connections are strictly isolated. When you authorize an AI agent in your browser, you will be prompted to select a Target Project.

The resulting authorization token is permanently bound to that specific project. This means any tool execution (like fetching or revealing keys) by that agent will automatically route to the chosen workspace, requiring zero manual configuration or project IDs in your client setup!

Role-Based Access Control (RBAC): The operations your AI agent can perform are limited by your role in the selected project:

• Owner/Admin: Agents can perform any operation granted by the requested scopes.
• Editor: Agents can manage and reveal keys (if keys:write or keys:reveal scopes are granted).
• Viewer: Agents can only read metadata (e.g., list_keys). Attempts to use write tools will be rejected regardless of granted scopes.

Available tools

The server exposes six dedicated tools for browsing masked metadata, managing vault credentials, and decrypting secrets on-demand:

Supported clients

ApiVault MCP supports any client implementing the Model Context Protocol Streamable HTTP or SSE specification, including:

• Cursor
• Claude.ai and Claude for Desktop
• Claude Code (CLI)
• Windsurf
• VS Code (with Copilot / Cline / Roo Code)
• ChatGPT (Developer Mode Connector)
• Codex CLI
• Devin
• Raycast
• Goose
• Gemini Code Assist
• Gemini CLI

Setup by client

Connect your preferred AI tool and authorize access via browser approval:

Cursor

Add the server entry to your project .cursor/mcp.json or global Cursor Settings (Cmd/Ctrl + Shift + J → MCP):

{
  "mcpServers": {
    "apivault": {
      "url": "https://mcp.apivault.tech/mcp"
    }
  }
}

When Cursor connects, it will prompt you with a Needs login status. Click the button to open your browser on ApiVault and approve permissions.

Claude.ai and Claude for Desktop

You can connect Claude using either the built-in Connectors UI or via your configuration file:

Method 1: Connectors UI (Recommended)

1. Open Connectors settings

   In Claude Desktop or Claude.ai, open Settings → Connectors (or click the + in chat → Connectors).

2. Add custom connector

   Click Add Custom Connector.

3. Enter server details

   Enter Name: ApiVault and Remote URL: https://mcp.apivault.tech/mcp.

4. Connect and authorize

   Click Connect to authenticate via your browser.

Method 2: Config 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://mcp.apivault.tech/mcp"]
    }
  }
}

Claude Code

Add ApiVault MCP directly from your terminal:

# Add the ApiVault remote MCP server
claude mcp add --transport http apivault https://mcp.apivault.tech/mcp

# Launch Claude Code
claude

# Trigger authentication
/mcp

Windsurf

Add the server snippet to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "apivault": {
      "serverUrl": "https://mcp.apivault.tech/mcp"
    }
  }
}

VS Code with Copilot / Cline

In VS Code with Copilot or extensions like Cline / Roo Code:

1. Open Command Palette

   Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).

2. Run MCP: Add Server

   Select HTTP, set Name to apivault, and enter URL: https://mcp.apivault.tech/mcp.

3. Authorize in Browser

   Start the server and complete the authorization prompt in your browser.

ChatGPT (Developer Mode)

Custom connectors using MCP are available on ChatGPT for Pro and Plus accounts:

1. Enable Developer mode

   Go to Settings → Connectors → Advanced settings → Developer mode.

2. Create connector

   Click Create under Connectors.

3. Configure server endpoint

   Set Name: ApiVault, URL: https://mcp.apivault.tech/mcp, and Authentication: OAuth.

4. Complete authorization

   Click Create to finish setup and complete authorization in your browser.

Codex CLI

# Install Codex
npm i -g @openai/codex

# Add ApiVault MCP
codex mcp add apivault --url https://mcp.apivault.tech/mcp

# Start Codex
codex

Devin

1. Open MCP Marketplace

   Navigate to Settings → MCP Marketplace.

2. Find ApiVault

   Search for ApiVault or select Custom Server.

3. Install server

   Set URL to https://mcp.apivault.tech/mcp and click Install.

Raycast

1. Run Install Server

   Run the Install Server command in Raycast.

2. Configure connection

   Set Name: ApiVault, Transport: HTTP, and URL: https://mcp.apivault.tech/mcp.

3. Approve access

   Click Install and approve permissions in your browser.

Goose

Add the extension configuration in Goose:

goose extension add --name apivault --url https://mcp.apivault.tech/mcp --type streamable_http

Gemini Code Assist

Add the configuration to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "apivault": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.apivault.tech/mcp"]
    }
  }
}

Gemini CLI

Shares the same configuration as Gemini Code Assist. After updating ~/.gemini/settings.json, run gemini /mcp list and approve when prompted.

OAuth scopes

During OAuth consent you select which permissions to grant:

The client icon is picked from the first source that loads: the logo_uri sent at registration, the favicon of its client_uri or of its HTTPS redirect URIs, a LobeHub icon matching the client name, a built-in icon for well-known clients, and finally a generic MCP icon. Only HTTPS logo_uri and client_uri values are stored.

Manage or revoke connected agents anytime in Settings → MCP Connections.

Workflow patterns

Find a key for an integration task

1. List keys for the target environment

   Call list_keys with an environment filter (e.g. "Production").

2. Confirm the correct key ID

   Call get_key to verify metadata before using the secret.

3. Reveal only when the raw secret is required

   Call reveal_key only when running local builds or tests — avoid printing plaintext values into conversation windows.

Error codes

Vault key attempt limits

A custom vault key is verified against a stored hash, so incorrect keys passed to reveal_key, add_key or update_key are rate limited: 10 failures per 15 minutes, counted per user and per source address. Exceeding the limit returns VAULT_KEY_RATE_LIMITED (HTTP 429 with a Retry-After header), and the tool error states how long to wait.

A correct vault key clears the counter, so an agent that reveals several keys in a row is never throttled. Agents should not retry a rejected vault_keyautomatically — ask the user for the correct one instead.

Rejected attempts are visible, not silent: a failed tool call is written to the project's audit log with its HTTP status, the error code above, the acting user and the client name the agent reports, filed under the action that was attempted — so a denied reveal_key appears as a KEY_REVEALED entry with a 4xx status. Calls rejected before a project can be resolved are not logged, because entries are stored per project.

Security best practices

• Least Privilege: Request only the scopes your agent needs for the current task.
• Masked Previews: Always rely on masked previews (list_keys) before requesting raw secrets.
• No Plaintext in Chat: Never instruct an AI agent to print revealed secrets in conversation transcripts or unencrypted commit files.
• Confused Deputy Protection: ApiVault MCP requires explicit browser authorization for every unique client ID.
• Revocation: Disconnect inactive agents anytime in Settings → MCP Connections.