@draiv/mcp-server

MCP (Model Context Protocol) server for the DRAIV car rental platform. Provides AI-accessible tools for searching cars, managing bookings, and fleet administration with role-based access control.

Installation

npm install -g @draiv/mcp-server

Or use directly with npx:

npx @draiv/mcp-server

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CONVEX_URL | Yes | Convex deployment URL | | DRAIV_API_KEY | No* | API key for authenticated access |

*Without an API key, only public tools (search_available_cars) are available.

Convex URLs:

• Production: https://careful-jaguar-818.convex.cloud
• Development: https://blessed-woodpecker-895.convex.cloud

Authentication

Access Levels

| Role | Tools Available | Description | |------|-----------------|-------------| | public | 1 tool | Search cars only (no auth required) | | user | 4 tools | Own bookings and car search | | fleetOwner | 7 tools | Manage own cars and fleet stats | | admin | 11 tools | Full platform access |

API Key Format

draiv_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are created through the DRAIV Developer Portal and are tied to a specific user and role.

How It Works

1. On startup, the server validates your API key against Convex
2. Based on your role, certain tools are enabled/disabled
3. User-scoped tools (bookings, fleet) automatically use your user ID
4. Admins can explicitly query any user's data

Claude Code Setup (Authenticated)

Add to .claude/settings.local.json:

{
  "mcpServers": {
    "draiv": {
      "command": "npx",
      "args": ["@draiv/mcp-server"],
      "env": {
        "CONVEX_URL": "https://careful-jaguar-818.convex.cloud",
        "DRAIV_API_KEY": "draiv_sk_live_your_api_key_here"
      }
    }
  }
}

Claude Code Setup (Public - Search Only)

Add to .claude/settings.local.json:

{
  "mcpServers": {
    "draiv": {
      "command": "npx",
      "args": ["@draiv/mcp-server"],
      "env": {
        "CONVEX_URL": "https://careful-jaguar-818.convex.cloud"
      }
    }
  }
}

Claude Desktop Setup

Add to Claude Desktop's config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "draiv": {
      "command": "npx",
      "args": ["@draiv/mcp-server"],
      "env": {
        "CONVEX_URL": "https://careful-jaguar-818.convex.cloud",
        "DRAIV_API_KEY": "draiv_sk_live_your_api_key_here"
      }
    }
  }
}

Available Tools

Public Tools (No Auth Required)

| Tool | Description | |------|-------------| | search_available_cars | Search for cars by city, type, seats, price, dates |

User Tools (Requires user role or higher)

| Tool | Description | |------|-------------| | get_user_bookings | Get your booking history | | get_active_booking | Get your current/upcoming booking with pickup details | | get_car_by_license_plate | Look up car details by license plate |

Fleet Owner Tools (Requires fleetOwner role or higher)

| Tool | Description | |------|-------------| | get_fleet_stats | Get your fleet statistics (cars, earnings, ratings) | | list_owner_cars | List all your cars | | toggle_car_status | Change your car's availability (available/inactive) |

Admin Tools (Requires admin role)

| Tool | Description | |------|-------------| | list_pending_cars | List cars awaiting approval | | approve_car | Approve a pending car listing | | reject_car | Reject a car with reason | | get_platform_stats | Get platform-wide statistics |

Example Usage

Once configured, you can use natural language in Claude:

"Search for electric cars in Zürich under 100 CHF per day"

"Show me the fleet stats for owner user_abc123"

"List all cars pending approval"

"Approve car j57...xyz and notify the owner"

Development

Local Development

# Clone the repo
cd packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
CONVEX_URL=https://blessed-woodpecker-895.convex.cloud node dist/index.js

Testing with Claude Code

Point to local build in .claude/settings.local.json:

{
  "mcpServers": {
    "draiv": {
      "command": "node",
      "args": ["/path/to/draiv-monorepo/packages/mcp-server/dist/index.js"],
      "env": {
        "CONVEX_URL": "https://blessed-woodpecker-895.convex.cloud"
      }
    }
  }
}

Architecture

Claude Code / Claude Desktop
        │
        │ MCP Protocol (stdio)
        ▼
┌─────────────────────────┐
│   @draiv/mcp-server     │  ← Runs locally on your machine
│                         │
│  ├── Auth middleware    │  ← Validates API key on startup
│  ├── Role-based access  │  ← Filters tools by role
│  ├── Tool definitions   │
│  ├── Input validation   │
│  └── Response formatting│
└───────────┬─────────────┘
            │
            │ HTTPS
            ▼
┌─────────────────────────┐
│   Convex Cloud          │  ← DRAIV's backend
│   (hitlTools.ts)        │
│   (apiKeys.ts)          │  ← API key validation
└─────────────────────────┘

Rate Limiting

All authenticated API keys have rate limiting enforced to ensure fair usage:

| Default Limit | Window | |---------------|--------| | 60 requests | 60 seconds |

When rate limited, the server returns:

{
  "error": true,
  "code": "RATE_LIMITED",
  "retryAfter": 42,
  "resetAt": 1702500000000
}

Custom rate limits can be configured per API key through the Developer Portal.

Usage Tracking

All tool calls are tracked for analytics:

• Tool name and timestamp
• Success/failure status
• Response time (duration in ms)
• Error codes if applicable

View your usage statistics in the Developer Portal at draiv.ch/developers/keys.

Security

• API keys are never stored in plain text - only SHA256 hashes
• Keys are validated on server startup, not per-request
• User-scoped tools automatically use the authenticated user's ID
• Non-admin users cannot access other users' data
• Keys can be revoked instantly via the Developer Portal
• Rate limiting prevents abuse and ensures fair usage
• Usage tracking provides visibility into API usage patterns

Changelog

v0.3.0

• Added rate limiting enforcement (60 req/min default)
• Added usage tracking for analytics
• Rate limit headers in responses
• Better error messages for rate-limited requests

v0.2.0

• Added API key authentication
• Role-based access control (RBAC)
• Scoped tool access by role

v0.1.0

• Initial release
• 11 MCP tools for car rental platform

License

MIT