npm package: @frozotrailbase/mcp-server
Description: MCP server for AI-assisted Trailbase API integration
Latest version: 0.1.0

# @frozotrailbase/mcp-server

MCP (Model Context Protocol) server for AI-assisted Trailbase API integration. This server allows AI assistants like Claude to interact with your Trailbase audit logging platform directly.

## Features

- **19 tools** covering all Trailbase API capabilities
- **API key only** — just set `TRAILBASE_API_KEY`, tenant is auto-discovered
- **Zero configuration** — works out of the box with a single env var
- **Stdio transport** — compatible with Claude Desktop, VS Code, Cursor, and any MCP client

## Available Tools

| Tool | Description |
|------|-------------|
| `trailbase_health_check` | Check API health |
| `trailbase_send_event` | Send a single audit event |
| `trailbase_send_batch_events` | Send up to 100 events at once |
| `trailbase_search_events` | Search events with filters |
| `trailbase_rbac_decide` | Check RBAC permissions |
| `trailbase_list_grants` | List RBAC grants |
| `trailbase_create_grant` | Create an RBAC grant |
| `trailbase_list_alert_rules` | List alert rules |
| `trailbase_create_alert_rule` | Create an alert rule |
| `trailbase_list_alerts` | List fired alerts |
| `trailbase_update_alert` | Acknowledge/resolve alerts |
| `trailbase_list_webhooks` | List webhooks |
| `trailbase_create_webhook` | Create a webhook |
| `trailbase_run_compliance_check` | Run compliance check (SOC2, HIPAA, etc.) |
| `trailbase_get_compliance_results` | Get compliance results |
| `trailbase_list_exports` | List export runs |
| `trailbase_get_stats` | Get analytics stats |
| `trailbase_get_operations` | Get operational health |
| `trailbase_get_event_schema` | Get event schema reference |

## Setup

### 1. Install

```bash
npm install -g @frozotrailbase/mcp-server
```

Or use directly with npx:

```bash
npx @frozotrailbase/mcp-server
```

### 2. Get Your API Key

1. Log into your Trailbase dashboard
2. Go to **Settings > API Keys**
3. Click **Create API Key**
4. Copy the key (it's only shown once)

### 3. Configure Your MCP Client

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%AppData%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "trailbase": {
      "command": "npx",
      "args": ["@frozotrailbase/mcp-server"],
      "env": {
        "TRAILBASE_API_KEY": "tb_your_api_key_here",
        "TRAILBASE_BASE_URL": "https://your-trailbase-instance.com"
      }
    }
  }
}
```

#### Claude Code (VS Code)

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "trailbase": {
      "command": "npx",
      "args": ["@frozotrailbase/mcp-server"],
      "env": {
        "TRAILBASE_API_KEY": "tb_your_api_key_here",
        "TRAILBASE_BASE_URL": "https://your-trailbase-instance.com"
      }
    }
  }
}
```

#### Cursor

Add to Cursor's MCP settings with the same configuration format as Claude Desktop.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TRAILBASE_API_KEY` | Yes | Your Trailbase API key (starts with `tb_`) |
| `TRAILBASE_BASE_URL` | No | API base URL (default: `https://api.trailbase.frozo.ai`) |

The **tenant ID is auto-discovered** from your API key on first use — no need to configure it manually.

## Example Usage

Once configured, you can ask your AI assistant things like:

- "Send an audit event for user john@example.com logging into the dashboard"
- "Search for all failed login events in the last 24 hours"
- "Check if user_123 has read permission on document doc_456"
- "Create an alert rule for more than 10 failed logins in 5 minutes"
- "Run a SOC2 compliance check"
- "Show me the operational health dashboard"
- "What's the event schema for Trailbase?"

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev

# Run locally
TRAILBASE_API_KEY=tb_xxx TRAILBASE_BASE_URL=http://localhost:3000 node build/index.js
```

## License

MIT