# @holdify/mcp

MCP (Model Context Protocol) server for the Holdify API. Enables AI assistants like Claude and Cursor to manage API keys, check usage, and debug authentication issues.

## Installation

```bash
npm install -g @holdify/mcp
# or
npx @holdify/mcp
```

## Configuration

Set the following environment variables:

```bash
# Required: Your Holdify project API key
export HOLDIFY_API_KEY=hld_proj_live_xxx

# Optional: Custom API URL (defaults to https://api.holdify.io)
export HOLDIFY_API_URL=https://api.holdify.io

# Optional: Request timeout in ms (defaults to 30000)
export HOLDIFY_TIMEOUT=30000
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "holdify": {
      "command": "npx",
      "args": ["@holdify/mcp"],
      "env": {
        "HOLDIFY_API_KEY": "hld_proj_live_your-key-here"
      }
    }
  }
}
```

## Usage with Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "holdify": {
      "command": "npx",
      "args": ["@holdify/mcp"],
      "env": {
        "HOLDIFY_API_KEY": "hld_proj_live_your-key-here"
      }
    }
  }
}
```

## Available Features

### Resources (Read-only data)

| Resource | URI | Description |
|----------|-----|-------------|
| Project Summary | `holdify://project` | Project overview with plan, limits, and key count |
| API Keys List | `holdify://keys` | List all API keys for the project |
| Key Details | `holdify://keys/{keyId}` | Get detailed info about a specific key |
| Usage Stats | `holdify://usage` | Current usage statistics (30-day period) |
| Audit Log | `holdify://audit` | Recent audit events (last 50) |

### Tools (Actions)

| Tool | Description | Input |
|------|-------------|-------|
| `create_api_key` | Create a new API key | `name`, `environmentId`, `scopes?` |
| `verify_key` | Verify if an API key is valid | `key`, `resource?`, `units?` |
| `revoke_key` | Permanently revoke an API key | `keyId` |
| `rotate_key` | Rotate an API key (24h grace period) | `keyId` |
| `get_usage` | Get usage statistics | `period?` (24h, 7d, 30d, 90d) |

### Prompts (Templates)

| Prompt | Description | Arguments |
|--------|-------------|-----------|
| `setup_api_auth` | Help setting up API authentication | `framework`, `language?` |
| `debug_key_issue` | Debug API key problems | `errorMessage?`, `keyPrefix?` |

## Example Interactions

### Check project status
> "What's my current usage and how many keys do I have?"

The AI will read `holdify://project` to get plan info, usage stats, and key count.

### Create a new API key
> "Create a new API key called 'Production Server' for environment env_abc123"

The AI will use the `create_api_key` tool and return the new key (save it immediately!).

### Debug authentication issues
> "My API key isn't working, I'm getting a 401 error"

The AI will use the `debug_key_issue` prompt to guide you through troubleshooting.

### Check rate limits
> "Am I close to my rate limit?"

The AI will use `get_usage` to check your current usage and quota status.

## Security

- API keys are masked in responses (only prefix + last 4 chars shown)
- Full keys are only returned on creation/rotation
- All operations are scoped to your project via the project API key

## Development

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Run locally
HOLDIFY_API_KEY=your-key node dist/index.js
```

## License

MIT