# MCP Server

> Give your AI assistant access to your entire LinkTime scheduling universe — event types, availability, bookings, contacts, message threads, and call logs.
> Source: https://linktime.io/docs/developers/mcp
> Last updated: February 2026

The LinkTime MCP Server implements the [Model Context Protocol](https://modelcontextprotocol.io) — an open standard that lets AI assistants (Claude, Cursor, Windsurf, and others) interact with external tools. Instead of asking you to copy-paste data, your AI assistant can directly check your calendar, book meetings, look up contacts, and review communication history.

**32 tools. 10 domains. 3 lines of config.**

## Quick Setup

### Prerequisites

- Node.js 18 or later
- A LinkTime account on Pro or Business plan
- An API key (Settings → API Keys → Create API Key)

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "linktime": {
      "command": "npx",
      "args": ["-y", "linktime-mcp"],
      "env": {
        "LINKTIME_API_KEY": "lt_live_..."
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "linktime": {
      "command": "npx",
      "args": ["-y", "linktime-mcp"],
      "env": {
        "LINKTIME_API_KEY": "lt_live_..."
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add linktime -- npx -y linktime-mcp
```

Then set `LINKTIME_API_KEY` in your environment.

### Windsurf / VS Code

Use the same `npx -y linktime-mcp` command in your editor's MCP settings.

## How It Works

The MCP server is a thin translation layer between your AI assistant and the LinkTime REST API:

```
AI Assistant ←→ MCP Protocol (stdio) ←→ linktime-mcp ←→ LinkTime REST API
```

1. Your AI assistant connects to the MCP server via stdio
2. The server advertises 32 tools to the AI
3. When the AI calls a tool, the server translates it to a REST API call
4. The API response is formatted and returned to the AI

The server runs locally on your machine. Your API key never leaves your environment.

## Tools Reference

### Scheduling (5 tools)

#### `list_event_types`

List your active event types — name, duration, slug, location type, and price. Use this first to find event type slugs for booking.

**Parameters:** None

**Returns:** Array of event types with id, name, slug, durationMinutes, locationType, price.

---

#### `check_availability`

Get available time slots for a specific event type. Returns exact UTC ISO datetime strings that must be used in `create_booking` or `reschedule_booking`.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `eventTypeSlug` | string | Yes | Event type slug from `list_event_types` |
| `timezone` | string | Yes | IANA timezone for display (e.g., "America/New_York") |
| `startDate` | string | No | ISO date (defaults to today) |
| `endDate` | string | No | ISO date (defaults to startDate + 7 days) |

---

#### `create_booking`

Book a meeting. The `startTime` must be a value returned by `check_availability` — the AI cannot invent or guess times. Automatically sends confirmation email, syncs calendar, fires webhooks, and creates audit log.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `eventTypeSlug` | string | Yes | Event type slug |
| `startTime` | string | Yes | UTC ISO datetime from `check_availability` |
| `inviteeName` | string | Yes | Guest's full name |
| `inviteeEmail` | string | Yes | Guest's email |
| `inviteeTimezone` | string | Yes | Guest's IANA timezone |
| `notes` | string | No | Meeting notes |

**Returns:** `{ bookingId: "..." }`

---

#### `cancel_booking`

Cancel an existing booking. Guest is notified via email. Calendar events, CRM records, and webhooks are updated automatically.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `bookingId` | string | Yes | Booking ID to cancel |
| `reason` | string | No | Cancellation reason |

---

#### `reschedule_booking`

Move a booking to a new time. The `newStartTime` must be a value from `check_availability`. Updates all connected calendars (Google, Outlook, CalDAV), CRM records, and sends a reschedule notification email.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `bookingId` | string | Yes | Booking ID to reschedule |
| `newStartTime` | string | Yes | New UTC ISO datetime from `check_availability` |
| `reason` | string | No | Reason for rescheduling |

### Meetings (2 tools)

#### `list_bookings`

List your meetings with filtering. Shows guest name, event type, time, status, meeting link, and notes.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | No | Start date filter (ISO format) |
| `to` | string | No | End date filter |
| `status` | string | No | "confirmed", "cancelled", or "all" (default: "confirmed") |
| `page` | number | No | Page number (default: 1) |
| `limit` | number | No | Results per page, max 100 (default: 20) |

---

#### `get_booking`

Get full details of a specific meeting — time, guest info, event type, meeting link, notes, and status.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `bookingId` | string | Yes | The booking ID |

### Contacts (5 tools)

#### `list_contacts`

Search and list contacts. Shows meeting count per contact.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | No | Search by name, email, or company |
| `page` | number | No | Page number (default: 1) |
| `limit` | number | No | Results per page, max 100 (default: 20) |

---

#### `get_contact`

Get a contact's full profile and complete meeting history — upcoming meetings, past meetings, and all contact details.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contactId` | string | Yes | The contact ID |

---

#### `create_contact`

Add a new contact. Returns an error if a contact with the same email already exists.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Contact's full name |
| `email` | string | Yes | Contact's email |
| `phone` | string | No | Phone in E.164 format (e.g., "+15551234567") |
| `company` | string | No | Company name |
| `notes` | string | No | Notes about the contact |

---

#### `update_contact`

Update a contact's information. Only provide the fields you want to change.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contactId` | string | Yes | Contact ID to update |
| `name` | string | No | New name |
| `email` | string | No | New email |
| `phone` | string | No | New phone |
| `company` | string | No | New company |
| `notes` | string | No | New notes |

---

#### `delete_contact`

Permanently delete a contact. This cannot be undone.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contactId` | string | Yes | Contact ID to delete |

### Communication History (2 tools)

#### `list_conversations`

View SMS and WhatsApp message threads. Shows full message content with direction (inbound/outbound) and timestamps. Up to 50 messages per conversation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `phone` | string | No | Filter by phone number (E.164 format) |
| `from` | string | No | Start date filter (ISO format) |
| `to` | string | No | End date filter |
| `limit` | number | No | Max conversations, max 50 (default: 20) |
| `page` | number | No | Page number (default: 1) |

---

#### `list_call_history`

View voice call logs — date, duration, caller phone, outcome, and which AI agent handled it. Filter by date range or call status.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | No | Start date filter (ISO format) |
| `to` | string | No | End date filter |
| `status` | string | No | "completed", "failed", "no_answer", or "all" |
| `limit` | number | No | Max results, max 50 (default: 20) |
| `page` | number | No | Page number (default: 1) |

### Context (1 tool)

#### `get_me`

Your LinkTime profile — name, email, username, plan, and effective plan.

**Parameters:** None

### Event Management (3 tools)

#### `create_event_type`

Create a new event type (booking page). Specify name, duration, location type, and scheduling options.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Event type name |
| `slug` | string | Yes | URL slug (lowercase, hyphens) |
| `durationMinutes` | number | No | Duration in minutes (default: 30) |
| `description` | string | No | Description for booking page |
| `locationType` | string | No | GOOGLE_MEET, ZOOM, TEAMS, WEBEX, PHONE, IN_PERSON, CUSTOM, NONE |
| `location` | string | No | Location details (for IN_PERSON/CUSTOM) |
| `color` | string | No | Hex color code |
| `bufferBefore` | number | No | Buffer before in minutes (0-120) |
| `bufferAfter` | number | No | Buffer after in minutes (0-120) |
| `minNoticeHours` | number | No | Minimum notice hours (default: 24) |
| `maxDaysAhead` | number | No | Booking window in days (default: 60) |

---

#### `update_event_type`

Update an existing event type. All fields are optional — only provide the ones you want to change.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `eventTypeId` | string | Yes | Event type ID |
| `name` | string | No | New name |
| `slug` | string | No | New URL slug |
| `durationMinutes` | number | No | New duration |
| `isActive` | boolean | No | Enable/disable |
| ... | ... | No | Same fields as create |

---

#### `delete_event_type`

Permanently delete an event type. Existing bookings are NOT cancelled.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `eventTypeId` | string | Yes | Event type ID to delete |

### Availability (5 tools)

#### `get_availability_rules`

Get your weekly availability schedule — which days and hours you're available.

**Parameters:** None

---

#### `update_availability_rules`

Set your weekly availability. Replaces ALL existing rules.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `rules` | array | Yes | Array of `{ dayOfWeek: 0-6, startTime: "HH:MM", endTime: "HH:MM", isAvailable: boolean }` |

---

#### `list_availability_overrides`

List date-specific blocks or custom hours.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `startDate` | string | No | Filter start (ISO format) |
| `endDate` | string | No | Filter end (ISO format) |

---

#### `create_availability_override`

Block a date or set custom hours. Use for vacations, holidays, etc.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | Yes | Date (YYYY-MM-DD) |
| `isBlocked` | boolean | Yes | True = blocked, false = custom hours |
| `startTime` | string | No | Custom start (HH:MM, required if not blocked) |
| `endTime` | string | No | Custom end (HH:MM, required if not blocked) |
| `reason` | string | No | Reason (e.g., "Vacation") |

---

#### `delete_availability_override`

Remove an override, restoring the default weekly schedule.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | Yes | Date (YYYY-MM-DD) |

### Settings (3 tools)

#### `get_settings`

Get account settings — timezone, format preferences, meeting limits.

**Parameters:** None

---

#### `update_settings`

Update account settings. Cannot change username via API.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `timezone` | string | No | IANA timezone |
| `defaultBufferBefore` | number | No | Default buffer before (0-60 min) |
| `defaultBufferAfter` | number | No | Default buffer after (0-60 min) |
| `maxMeetingsPerDay` | number/null | No | Daily cap (1-50, null to disable) |
| `minGapMinutes` | number/null | No | Min gap (5/10/15/30/60/120, null to disable) |
| `focusTimeBlocks` | array/null | No | Focus time windows (null to clear) |

---

#### `list_integrations`

Check connected integrations — calendars, video, CRM, payments.

**Parameters:** None

### Webhooks (4 tools)

#### `list_webhooks`

List webhook endpoints with delivery counts.

**Parameters:** None

---

#### `create_webhook`

Create a webhook endpoint. Returns the signing secret (shown only once).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | HTTPS URL for webhook POST requests |
| `events` | array | Yes | Events: booking.created, booking.cancelled, booking.rescheduled, etc. |
| `name` | string | No | Friendly name |

---

#### `update_webhook`

Update a webhook — URL, events, name, or active status.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `webhookId` | string | Yes | Webhook ID |
| `url` | string | No | New URL |
| `events` | array | No | New event subscriptions |
| `isActive` | boolean | No | Enable/disable |

---

#### `delete_webhook`

Delete a webhook endpoint permanently.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `webhookId` | string | Yes | Webhook ID |

### Workflows (2 tools)

#### `list_workflows`

List automation workflows with trigger, actions, and execution counts.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `eventTypeId` | string | No | Filter by event type |

---

#### `create_workflow`

Create an automation — email, SMS, webhook, Slack, or AI call triggered by booking events.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Workflow name |
| `trigger` | string | Yes | BOOKING_CREATED, BOOKING_CANCELLED, TIME_BEFORE_MEETING, etc. |
| `actions` | array | Yes | Array of `{ type, config }` action objects |
| `eventTypeId` | string | No | Limit to specific event type |
| `triggerTimeValue` | number | No | Time value for TIME_BEFORE/AFTER |
| `triggerTimeUnit` | string | No | MINUTES, HOURS, or DAYS |

## Example Conversations

### "Book a meeting with Sarah"

```
User: Book a 30-minute call with Sarah Chen tomorrow afternoon

AI uses: list_event_types → finds "30-Minute Call" (slug: 30-min-call)
AI uses: check_availability → gets slots for tomorrow, timezone America/New_York
AI uses: create_booking → books 2:00 PM slot with sarah.chen@acme.com

AI: Done! I've booked a 30-minute call with Sarah Chen tomorrow at 2:00 PM ET.
    She'll receive a confirmation email with the Zoom link.
```

### "What's my schedule this week?"

```
User: What meetings do I have this week?

AI uses: list_bookings → fetches confirmed bookings from Mon–Fri

AI: You have 4 meetings this week:
    - Mon 10am: Product Demo with Alex Rivera
    - Tue 2pm: Quick Call with Sarah Chen
    - Wed 11am: Strategy Session with Jordan Lee
    - Fri 3pm: Intro Call with new lead (maria@startup.io)
```

### "Tell me about this person before my call"

```
User: What do I know about Sarah Chen? I have a call with her in an hour

AI uses: list_contacts → searches "Sarah Chen"
AI uses: get_contact → gets full profile + meeting history

AI: Sarah Chen — VP Engineering at Acme Corp
    Email: sarah.chen@acme.com | Phone: +1-555-0123

    You've met 4 times:
    - Oct 15: Intro Call (30 min)
    - Nov 3: Follow-up (30 min)
    - Nov 18: Product Demo (45 min)
    - Dec 2: Quick Call — she cancelled

    Notes: "Interested in enterprise plan. Budget review in Q1."
```

### "Reschedule tomorrow's meeting"

```
User: Push my meeting with Alex to Thursday instead

AI uses: list_bookings → finds Alex's booking tomorrow
AI uses: check_availability → gets Thursday slots for same event type
AI: Thursday slots available: 9am, 10:30am, 2pm, 3:30pm. Which works?
User: 10:30
AI uses: reschedule_booking → moves to Thursday 10:30am

AI: Done! Alex's Product Demo is now Thursday at 10:30 AM.
    He'll get an email with the updated time.
```

### "Check my recent calls"

```
User: How did my voice agent calls go this week?

AI uses: list_call_history → filters from Monday, status "all"

AI: 8 calls this week:
    - 5 completed (avg 2m 15s) — 3 resulted in bookings
    - 2 no answer
    - 1 failed (caller hung up after 5s)

    Your "Sales Agent" handled all of them.
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `LINKTIME_API_KEY` | Yes | Your LinkTime API key (`lt_live_...`) |
| `LINKTIME_BASE_URL` | No | Override API base URL (defaults to `https://linktime.io`) |

## Troubleshooting

**"LINKTIME_API_KEY environment variable is required"**
Make sure your API key is set in the `env` section of your MCP config, not as a system environment variable.

**"unauthorized" error**
Your API key may be invalid or expired. Generate a new one at Settings → API Keys.

**"rate_limited" error**
The API allows 60 requests per minute. Your AI assistant will automatically back off and retry.

**Tools not appearing in your AI assistant**
Restart your AI client after updating the MCP config. Verify the server starts by running `npx -y linktime-mcp` in your terminal — it should print "LinkTime MCP server running" to stderr.

**"not_found" errors when creating bookings**
The `eventTypeSlug` must match an active event type. Use `list_event_types` first to find valid slugs.

## Architecture

The MCP server is a standalone npm package (`linktime-mcp`) that:

- Uses **stdio transport** — no network ports, no HTTP server
- Makes authenticated REST API calls to `https://linktime.io/api/v1/*`
- Runs locally on your machine — your API key never leaves your environment
- Has zero state — every tool call is a fresh API request
- Requires Node.js 18+ (uses native fetch)

## Related Documentation

- [API Reference](https://linktime.io/docs/developers/api) — Full REST API documentation
- [Webhooks API](https://linktime.io/docs/developers/webhooks) — Real-time event notifications
- [Voice Agents](https://linktime.io/docs/ai/voice) — AI phone agents
- [Messaging Agents](https://linktime.io/docs/ai/messaging) — SMS and WhatsApp AI agents