Model Context Protocol

Setup

Add the MCP server URL to your client configuration. On first use, the client opens a browser for OAuth approval.

Cursor

Add to MCP config (mcp.json or Cursor Settings → MCP):

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

Claude Desktop

Add the same URL entry to your Claude Desktop MCP configuration. OAuth flow is identical — approve scopes in the browser when prompted.

Authentication

MCP uses OAuth 2.1 with Dynamic Client Registration (DCR) and PKCE. MCP tokens are independent from CLI tokens — revoking one does not affect the other.

If tools return an auth error or the server status is needsAuth:

1. Trigger OAuth re-authentication

   Use your MCP client's reconnect or re-authenticate action to start a fresh OAuth flow.

2. Approve the requested scopes

   Review the permissions in the browser and approve the scopes required for your task.

3. Retry the tool call

   Run the intended MCP tool again after authentication completes.

Manage and revoke active connections in Settings → MCP Connections.

OAuth scopes

Request the minimum scopes required for your task. During OAuth consent you select which permissions to grant.

• keys:read — List key names, services, environments, and masked values.
• keys:write — Create new keys, update metadata, and permanently delete keys.
• keys:reveal — Decrypt and return full secret values to the connected agent.

Tools reference

Discover full input schemas via your MCP client's tool inspection before calling. Summary of all six tools:

list_keys

Scope: keys:read. List all keys with masked values.

get_key

Scope: keys:read. Get metadata for a single key by ID (masked).

reveal_key

Scope: keys:reveal. Decrypt and return the raw secret value.

add_key

Scope: keys:write. Create a new key in the vault.

update_key

Scope: keys:write. Update metadata or secret value.

delete_key

Scope: keys:write. Permanently delete a key by ID.

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 if needed — use the value immediately in env or config, not in chat.

Add a new credential

1. Confirm write scope is granted

   Ensure your OAuth token includes keys:write.

2. Create the key with add_key

   Call add_key with name, key, service, and environment.

3. Pass vault_key in custom encryption mode

   Include vault_key when the vault uses custom encryption.

Error codes

Protocol details

Token lifetimes

• Authorization codes: 5 minutes
• Access tokens: 1 hour
• Refresh tokens: 30 days

Transport: Streamable HTTP. There is no local apivault mcp stdio command — the MCP server is remote only.

Security practices

• Request only the scopes your agent needs
• Use masked list_keys / get_key before calling reveal_key
• Do not paste revealed values into chat, commits, logs, or issue trackers
• Inject secrets via env vars or local files the user controls
• Revoke unused connections in Settings → MCP Connections