Docs MCP Server Setup

MCP Server Setup

Manage API keys directly from your AI coding assistant.

The Holdify MCP (Model Context Protocol) server brings API key management directly into your AI coding workflow. Create, verify, rotate, and revoke keys without leaving your editor.

Claude Code

Full support via MCP config file.

Cursor

Add to your Cursor MCP settings.

Windsurf

Works with Windsurf MCP support.

Prerequisites

A Holdify account with at least one project
A root API key from your Holdify dashboard (Settings → API Keys)
Node.js 18+ installed (for npx)
An MCP-compatible AI assistant (Claude Code, Cursor, or Windsurf)

Setup for Claude Code

Get your root API key

Go to Settings → API Keys in your Holdify dashboard and create a root API key. This key allows the MCP server to manage keys on your behalf.

Add MCP configuration

Add the following to your Claude Code MCP configuration file (~/.claude/mcp.json or project-level config):

mcp.json

json

{
  "mcpServers": {
    "holdify": {
      "command": "npx",
      "args": ["@holdify/mcp-server"],
      "env": {
        "HOLDIFY_API_KEY": "your-root-key"
      }
    }
  }
}

Restart Claude Code

Restart Claude Code to load the new MCP server. You can verify it's connected by asking Claude to list your Holdify projects.

Setup for Cursor

Open Cursor settings

Go to Cursor → Settings → MCP or open your ~/.cursor/mcp.json file.

Add Holdify configuration

Add the Holdify MCP server to your configuration:

mcp.json

json

{
  "mcpServers": {
    "holdify": {
      "command": "npx",
      "args": ["@holdify/mcp-server"],
      "env": {
        "HOLDIFY_API_KEY": "your-root-key"
      }
    }
  }
}

Reload Cursor

Reload Cursor to apply the changes. The Holdify tools will now be available in your AI assistant.

Available Tools

Once connected, your AI assistant can use the following Holdify tools:

MCP Tools

yaml

# Tools available via Holdify MCP Server

holdify_create_key      - Create a new API key
holdify_verify_key      - Verify an API key and check usage
holdify_list_keys       - List all API keys in a project
holdify_revoke_key      - Revoke an API key
holdify_rotate_key      - Rotate an API key (revoke + create new)
holdify_get_usage       - Get usage statistics for a key
holdify_list_projects   - List all projects
holdify_get_project     - Get project details

Example Usage

Here are some examples of what you can ask your AI assistant:

Creating a key

Create API Key

javascript

// Example: Create a new API key
// Ask your AI assistant:
// "Create an API key for the payments service with read-only access"

// The MCP server will call:
holdify_create_key({
  name: "payments-service",
  projectId: "proj_abc123",
  permissions: ["read"],
  metadata: {
    service: "payments",
    environment: "production"
  }
})

// Returns:
{
  "id": "key_xyz789",
  "key": "hld_live_abc123...",
  "name": "payments-service",
  "createdAt": "2026-01-09T12:00:00Z"
}

Verifying a key

Verify API Key

javascript

// Example: Verify a key and check usage
// Ask your AI assistant:
// "How many requests has the mobile-app key made this month?"

// The MCP server will call:
holdify_verify_key({
  key: "hld_live_abc123..."
})

// Returns:
{
  "valid": true,
  "keyId": "key_xyz789",
  "name": "mobile-app",
  "usage": {
    "requests": 45230,
    "limit": 500000,
    "resetAt": "2026-02-01T00:00:00Z"
  },
  "entitlements": ["api", "chat", "embeddings"]
}

Example Prompts

Try these prompts with your AI assistant:

"Create an API key for the payments service with read-only access"

"How many requests has the mobile-app key made this month?"

"Rotate all keys that haven't been used in 30 days"

"Show me which keys are close to their rate limit"

"Revoke the compromised key and create a replacement"

"List all API keys in my production project"

"What entitlements does key xyz have?"

Security Best Practices

Use environment variables - Never hardcode your root API key. Use HOLDIFY_API_KEY environment variable.
Limit root key scope - Create a dedicated root key for MCP with only the permissions you need.
Review audit logs - All actions via MCP are logged in your Holdify dashboard audit trail.
Rotate regularly - Rotate your root API key periodically, especially if it may have been exposed.

Troubleshooting

MCP server not connecting

Ensure Node.js 18+ is installed and npx is available in your PATH. Try running npx @holdify/mcp-server manually to check for errors.

Authentication errors

Verify your HOLDIFY_API_KEY is correct and hasn't been revoked. Check the key in your Holdify dashboard.

Tools not appearing

Restart your AI coding assistant after adding the MCP configuration. Some tools may take a moment to register.