# Vagaro MCP tools

> Every Vagaro MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/vagaro

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

15 tools for Vagaro on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Vagaro business login, the one you use for the calendar, customers and reports
- Integration page: https://cotlet.dev/integrations/vagaro-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `vagaro_list_locations` | read | Your business locations with address, time zone and phone. |
| `vagaro_list_services` | read | Service menu of a location with duration, price and who performs each service. |
| `vagaro_list_appointments` | read | Appointments in a date range with client, service, provider and status. |
| `vagaro_search_availability` | read | Open slots for a service, optionally with one provider, in a date range. |
| `vagaro_find_client` | read | Search clients by name, email or phone; returns contact details, tags and last visit. |
| `vagaro_list_waitlist` | read | Clients on the waitlist with the service, provider and day they want. |
| `vagaro_list_conversations` | read | Client chats in Connect by Vagaro with the last message and unread status. |
| `vagaro_list_reviews` | read | Client reviews from your listing page with rating, text and whether you replied. |
| `vagaro_book_appointment` | write | Book a client into an open slot. |
| `vagaro_reschedule_appointment` | write | Move an appointment to a new time or provider. |
| `vagaro_cancel_appointment` | write | Cancel a client's appointment from the calendar, optionally notifying the client. |
| `vagaro_add_to_waitlist` | write | Put a client on the waitlist for a service, provider and day. |
| `vagaro_notify_waitlist` | write | Alert chosen waitlisted clients about an opening. |
| `vagaro_reply_to_client` | write | Send a message to a client in Connect by Vagaro, optionally with your booking link. |
| `vagaro_reply_to_review` | write | Post a public business reply under a customer review. |

## List locations

MCP tool: `vagaro_list_locations`

Access: read.

Returns every location of your Vagaro business. Use location_id from each item in the other calls. Multi-location businesses read one location per call.

### Parameters

No parameters.

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_list_locations",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "locations": [
      {
        "location_id": "loc_21",
        "name": "Main Street",
        "address": "120 Main St, Portland, OR",
        "time_zone": "America/Los_Angeles",
        "phone": "+1 555 0100"
      },
      {
        "location_id": "loc_22",
        "name": "Riverside",
        "address": "8 River Rd, Portland, OR",
        "time_zone": "America/Los_Angeles",
        "phone": "+1 555 0101"
      }
    ]
  },
  "isError": false
}
```

## List services

MCP tool: `vagaro_list_services`

Access: read.

Returns the services of one location with duration, price and the providers who perform them. Use service_id in search_availability and book_appointment. Prices are the menu prices shown in Vagaro.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_list_services",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "services": [
      {
        "service_id": "svc_1172",
        "name": "Balayage",
        "duration_min": 150,
        "price": {
          "amount": 185,
          "currency": "USD"
        },
        "provider_ids": [
          "emp_309"
        ]
      },
      {
        "service_id": "svc_1180",
        "name": "Women's cut",
        "duration_min": 45,
        "price": {
          "amount": 65,
          "currency": "USD"
        },
        "provider_ids": [
          "emp_309",
          "emp_311"
        ]
      }
    ]
  },
  "isError": false
}
```

## List appointments

MCP tool: `vagaro_list_appointments`

Access: read.

Returns appointments of one location between two days, ordered by start time. Filter by provider to read one person's day. Each item has the client, service, provider, status and price shown on the calendar. This reads the calendar by date, which the official API cannot do.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `from` | date | yes | First day, inclusive. |
| `to` | date | no | Last day, inclusive. Default: same as from. |
| `provider_id` | string | no | Only this service provider. |
| `status` | string | no | Only appointments with this status, as Vagaro shows it. Default: all. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_list_appointments",
    "arguments": {
      "from": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointments": [
      {
        "appointment_id": "apt_7730301",
        "client": "Maya Brooks",
        "service": "Women's cut",
        "provider": "Alex",
        "start": "2026-10-14T09:00:00-07:00",
        "end": "2026-10-14T09:45:00-07:00",
        "status": "Booked"
      },
      {
        "appointment_id": "apt_7730415",
        "client": "Jamie Cole",
        "service": "Balayage",
        "provider": "Alex",
        "start": "2026-10-14T11:30:00-07:00",
        "end": "2026-10-14T14:00:00-07:00",
        "status": "Booked"
      }
    ]
  },
  "isError": false
}
```

## Search availability

MCP tool: `vagaro_search_availability`

Access: read.

Returns open start times for one service in a date range, per provider. Use a start from the result in book_appointment or reschedule_appointment so the booking lands on a free slot.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `service_id` | string | yes | Service ID from list_services. |
| `from` | date | yes | First day to search. |
| `to` | date | no | Last day to search. Default: from + 7 days. |
| `provider_id` | string | no | Only slots with this provider. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_search_availability",
    "arguments": {
      "service_id": "service_8c41d2",
      "from": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "slots": [
      {
        "provider_id": "emp_309",
        "provider": "Alex",
        "start": "2026-10-15T10:00:00-07:00"
      },
      {
        "provider_id": "emp_309",
        "provider": "Alex",
        "start": "2026-10-15T14:30:00-07:00"
      }
    ]
  },
  "isError": false
}
```

## Find client

MCP tool: `vagaro_find_client`

Access: read.

Searches your customers by name, email or phone and returns contact details and tags. Use client_id in book_appointment and add_to_waitlist. The official API needs a customer ID up front; this finds the ID from what you know.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Name, email or phone number. |
| `limit` | integer | no | 1 to 50. Default: 10. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_find_client",
    "arguments": {
      "query": "query"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "clients": [
      {
        "client_id": "cl_48213",
        "name": "Jamie Cole",
        "email": "jamie@example.com",
        "phone": "+1 555 0142",
        "tags": [
          "color"
        ]
      }
    ]
  },
  "isError": false
}
```

## List waitlist

MCP tool: `vagaro_list_waitlist`

Access: read.

Returns the waitlist of one location. Each entry has the client, the service and provider they asked for and the day. Use entry IDs in notify_waitlist. Which alerts Vagaro sends on its own depends on your waitlist mode under Online Appointment Rules.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `date` | date | no | Only entries for this day. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_list_waitlist",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "entries": [
      {
        "waitlist_entry_id": "wl_2041",
        "client": "Maya Brooks",
        "service": "Women's cut",
        "provider": "Alex",
        "date": "2026-10-14"
      },
      {
        "waitlist_entry_id": "wl_2044",
        "client": "Sam Ortiz",
        "service": "Beard trim",
        "provider": "any",
        "date": "2026-10-14"
      }
    ]
  },
  "isError": false
}
```

## List conversations

MCP tool: `vagaro_list_conversations`

Access: read.

Returns your Connect chats with clients, most recent first, with the last message and whether it is unread. Set unread_only to see what needs an answer. Replies to appointment notifications do not appear here.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `unread_only` | boolean | no | Only conversations with unread client messages. |
| `limit` | integer | no | 1 to 50. Default: 20. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_list_conversations",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversations": [
      {
        "conversation_id": "cv_2290",
        "client": "Maya Brooks",
        "unread": true,
        "last_message": "How much is a cut with Alex?",
        "updated_at": "2026-10-13T16:02:00-07:00"
      }
    ]
  },
  "isError": false
}
```

## List reviews

MCP tool: `vagaro_list_reviews`

Access: read.

Returns the reviews posted on your Vagaro listing page, newest first, with rating, text and whether you replied. Use unanswered_only to skip reviews you already answered. You cannot remove a customer review in Vagaro, so this tool only reads them.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `since` | date | no | Only reviews posted on or after this date. |
| `unanswered_only` | boolean | no | Skip reviews you already replied to. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_list_reviews",
    "arguments": {
      "location_id": "loc_21",
      "since": "2026-10-06",
      "unanswered_only": true
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "reviews": [
      {
        "review_id": "rv_5521",
        "client": "Maya B.",
        "rating": 5,
        "text": "Best balayage I have had.",
        "posted_at": "2026-10-12",
        "replied": false
      }
    ]
  },
  "isError": false
}
```

## Book appointment

MCP tool: `vagaro_book_appointment`

Access: write. Confirm: waits for the user's OK before it runs.

Books one client for one service with one provider at a start time from search_availability. Returns the appointment, its end time and price. The booking appears on the Vagaro calendar like one made by staff. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from find_client. |
| `service_id` | string | yes | Service ID from list_services. |
| `provider_id` | string | yes | Service provider ID. |
| `start` | datetime | yes | Slot start from search_availability, ISO 8601 with time zone. |
| `notes` | string | no | Appointment note visible to staff. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_book_appointment",
    "arguments": {
      "client_id": "cl_48213",
      "service_id": "svc_1172",
      "provider_id": "emp_309",
      "start": "2026-10-16T14:00:00-07:00",
      "notes": "Booked by agent from a Connect request"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointment_id": "apt_7730415",
    "status": "Booked",
    "client_id": "cl_48213",
    "service": "Balayage",
    "provider": "Alex",
    "start": "2026-10-16T14:00:00-07:00",
    "end": "2026-10-16T16:30:00-07:00",
    "price": {
      "amount": 185,
      "currency": "USD"
    }
  },
  "isError": false
}
```

## Reschedule appointment

MCP tool: `vagaro_reschedule_appointment`

Access: write. Confirm: waits for the user's OK before it runs.

Moves one appointment to a new start time and optionally a new provider, the same change as dragging it on the calendar. Returns the old and new times. Pick the new start from search_availability. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from list_appointments. |
| `start` | datetime | yes | New start, ISO 8601 with time zone. |
| `provider_id` | string | no | New provider. Default: unchanged. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_reschedule_appointment",
    "arguments": {
      "appointment_id": "apt_7730301",
      "start": "2026-10-14T09:00:00-07:00",
      "provider_id": "emp_311"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointment_id": "apt_7730415",
    "status": "Booked",
    "previous_start": "2026-10-14T11:30:00-07:00",
    "start": "2026-10-15T10:00:00-07:00",
    "end": "2026-10-15T12:30:00-07:00",
    "provider": "Alex"
  },
  "isError": false
}
```

## Cancel appointment

MCP tool: `vagaro_cancel_appointment`

Access: write. Confirm: waits for the user's OK before it runs.

Cancels one appointment, as Change Status then Cancel does on the Vagaro calendar. Set notify_client to tell the client. Refunds of prepayments and cancellation fees are not part of this tool; handle those in Vagaro. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from list_appointments. |
| `notify_client` | boolean | no | Tell the client about the cancellation. Default: true. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_cancel_appointment",
    "arguments": {
      "appointment_id": "appointment_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointment_id": "apt_7730415",
    "status": "Cancelled",
    "client_notified": true
  },
  "isError": false
}
```

## Add to waitlist

MCP tool: `vagaro_add_to_waitlist`

Access: write. Confirm: waits for the user's OK before it runs.

Adds a client to the waitlist of a location for one service and day, as Vagaro lets staff do by hand. The date tells Vagaro when to notify the client. Returns the entry ID for list_waitlist. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `client_id` | string | yes | Client ID from find_client. |
| `service_id` | string | yes | Service ID from list_services. |
| `date` | date | yes | Day the client wants. |
| `provider_id` | string | no | Preferred provider. Default: any. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_add_to_waitlist",
    "arguments": {
      "client_id": "client_8c41d2",
      "service_id": "service_8c41d2",
      "date": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "waitlist_entry_id": "wl_2052",
    "client": "Jamie Cole",
    "service": "Women's cut",
    "date": "2026-10-17",
    "provider": "any"
  },
  "isError": false
}
```

## Notify waitlist

MCP tool: `vagaro_notify_waitlist`

Access: write. Confirm: waits for the user's OK before it runs.

Offers an open slot to the waitlist entries you pick, like choosing a client by hand in the You Pick mode. Returns how many clients were alerted. Clients receive the alert, so it reaches people outside your account. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `waitlist_entry_ids` | string[] | yes | Entries from list_waitlist. |
| `start` | datetime | yes | Start of the open slot. |
| `provider_id` | string | no | Provider of the open slot. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_notify_waitlist",
    "arguments": {
      "waitlist_entry_ids": [
        "waitlist entry ids"
      ],
      "start": "2026-10-01T09:00:00Z"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "alerted": 1,
    "waitlist_entry_ids": [
      "wl_2041"
    ],
    "start": "2026-10-14T14:00:00-07:00",
    "provider": "Alex"
  },
  "isError": false
}
```

## Reply to client

MCP tool: `vagaro_reply_to_client`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a message in an existing Connect chat. Set include_booking_link to add your appointment booking link. Once a client has closed a chat, Vagaro needs a messaging plan on your side before you can keep replying. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | Conversation ID from list_conversations. |
| `body` | string | yes | Message text. |
| `include_booking_link` | boolean | no | Attach your appointment booking link. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_reply_to_client",
    "arguments": {
      "conversation_id": "conversation_8c41d2",
      "body": "body"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversation_id": "cv_2290",
    "message_id": "msg_8814",
    "status": "sent",
    "sent_at": "2026-10-13T16:10:00-07:00"
  },
  "isError": false
}
```

## Reply to review

MCP tool: `vagaro_reply_to_review`

Access: write. Confirm: waits for the user's OK before it runs.

Posts your reply under one review. The reply is public to other Vagaro users, the customer is notified, and the customer cannot comment again. There is no edit tool; edit or delete a reply in Vagaro on the web, tablet, Pay Desk or PayPro. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `review_id` | string | yes | Review ID from list_reviews. |
| `body` | string | yes | Reply text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vagaro_reply_to_review",
    "arguments": {
      "review_id": "review_8c41d2",
      "body": "body"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "review_id": "rv_5521",
    "status": "published",
    "replied_at": "2026-10-13T16:20:00-07:00"
  },
  "isError": false
}
```