# Civitatis MCP tools

> Every Civitatis 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/civitatis

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)

13 tools for Civitatis on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your Civitatis provider panel account (username and password)
- Integration page: https://cotlet.dev/integrations/civitatis-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `civitatis_list_activities` | read | Your activities on Civitatis with destination and status. |
| `civitatis_list_bookings` | read | Bookings by activity date, with activity, time, number of people and status. |
| `civitatis_get_booking` | read | One booking: reference, activity, date and time, people, price and lead traveler contact. |
| `civitatis_get_availability` | read | Calendar of an activity: open and closed dates and the quota per day and time. |
| `civitatis_list_messages` | read | Messages with customers and the Civitatis booking department, newest first. |
| `civitatis_list_reviews` | read | Customer reviews of your activities with rating, text and date. |
| `civitatis_list_invoices` | read | Commission invoices from Civitatis with period, amount and a download link. |
| `civitatis_list_payments` | read | Monthly settlements: services rendered, commission, net amount and payment status. |
| `civitatis_close_dates` | write | Stop sales of an activity on a date range, all day or for chosen times. |
| `civitatis_open_dates` | write | Reopen sales of an activity on dates you closed before. |
| `civitatis_set_quota` | write | Limit the places sold for an activity on given days and times. |
| `civitatis_send_message` | write | Write to a customer about a booking, or to the Civitatis booking department. |
| `civitatis_request_payment` | write | Request payment for services rendered in the previous month, net of commission. |

## List activities

MCP tool: `civitatis_list_activities`

Access: read.

Returns every activity your provider account sells, with its destination and status. Use activity_id from each item in the other tools.

### Parameters

No parameters.

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "activities": [
      {
        "activity_id": "act_48213",
        "name": "Bike tour of the old town",
        "destination": "Madrid",
        "status": "active"
      },
      {
        "activity_id": "act_51907",
        "name": "Sunset cruise",
        "destination": "Madrid",
        "status": "active"
      }
    ]
  },
  "isError": false
}
```

## List bookings

MCP tool: `civitatis_list_bookings`

Access: read.

Lists bookings by activity date, in start time order, with the activity, time, number of people and status. By default it returns confirmed bookings for the next 7 days. Pass next_cursor back as cursor for the next page. Use booking_id with get_booking for the price and contact.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | no | First activity date. Default: today. |
| `to` | date | no | Last activity date. Default: 7 days from today. |
| `activity_id` | string | no | Only bookings for this activity. |
| `status` | enum | no | confirmed, cancelled or all. Default: confirmed. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "civitatis_list_bookings",
    "arguments": {
      "from": "2026-10-14",
      "to": "2026-10-14",
      "activity_id": "act_48213",
      "status": "confirmed"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "bookings": [
      {
        "booking_id": "bk_702154",
        "activity_id": "act_48213",
        "activity": "Bike tour of the old town",
        "date": "2026-10-12",
        "time": "10:00",
        "people": 3,
        "status": "confirmed"
      },
      {
        "booking_id": "bk_702160",
        "activity_id": "act_48213",
        "activity": "Bike tour of the old town",
        "date": "2026-10-12",
        "time": "10:00",
        "people": 2,
        "status": "confirmed"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get booking

MCP tool: `civitatis_get_booking`

Access: read.

Returns one booking with its reference, activity, date and time, number of people, price and the lead traveler contact as shown in the provider panel. Personal data is returned as the panel shows it and is not stored by Cotlet.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_id` | string | yes | Booking ID from list_bookings. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "bk_702154",
    "reference": "CIV-702154",
    "activity": "Bike tour of the old town",
    "date": "2026-10-12",
    "time": "10:00",
    "people": 3,
    "price": {
      "amount": 87,
      "currency": "EUR"
    },
    "status": "confirmed",
    "lead_traveler": {
      "name": "Sample Traveler",
      "email": "traveler@example.com",
      "phone": "+34 600 000 000"
    }
  },
  "isError": false
}
```

## Get availability

MCP tool: `civitatis_get_availability`

Access: read.

Returns the calendar of one activity for a date range: whether each date is open or closed, and the quota for each start time. Use it before and after close_dates or set_quota to check the result. The default range is the next 30 days.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | no | First date. Default: today. |
| `to` | date | no | Last date. Default: 30 days from today. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "activity_id": "act_51907",
    "days": [
      {
        "date": "2026-11-07",
        "status": "open",
        "slots": [
          {
            "time": "18:00",
            "quota": 12
          }
        ]
      },
      {
        "date": "2026-11-08",
        "status": "open",
        "slots": [
          {
            "time": "18:00",
            "quota": 20
          }
        ]
      },
      {
        "date": "2026-11-09",
        "status": "closed",
        "slots": []
      }
    ]
  },
  "isError": false
}
```

## List messages

MCP tool: `civitatis_list_messages`

Access: read.

Lists message threads with customers and with the Civitatis booking department, newest first, with the booking each one is about and the last message. Set unread_only to see only what needs an answer.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `unread_only` | boolean | no | Only unread threads. Default: false. |
| `booking_id` | string | no | Only messages about this booking. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "threads": [
      {
        "booking_id": "bk_702154",
        "with": "customer",
        "unread": true,
        "last_message": "Where do we meet, and does the tour run in the rain?",
        "received_at": "2026-10-11T08:12:00+02:00"
      }
    ]
  },
  "isError": false
}
```

## List reviews

MCP tool: `civitatis_list_reviews`

Access: read.

Returns customer reviews of your activities with the rating, text and date, as the provider panel shows them. Filter by activity or by start date. Reviews are read only: Cotlet has no tool to answer or report them.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | no | Only reviews of this activity. |
| `since` | date | no | Only reviews on or after this date. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "reviews": [
      {
        "activity_id": "act_48213",
        "rating": 5,
        "text": "Great guide, easy route.",
        "date": "2026-09-21"
      },
      {
        "activity_id": "act_48213",
        "rating": 3,
        "text": "Meeting point was hard to find.",
        "date": "2026-09-14"
      }
    ]
  },
  "isError": false
}
```

## List invoices

MCP tool: `civitatis_list_invoices`

Access: read.

Lists the invoices Civitatis issues to you, which are commission invoices, with the period, amount and a download link. The default is the current year.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `year` | integer | no | Invoice year. Default: current year. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoices": [
      {
        "invoice_id": "inv_2026_09",
        "period": "2026-09",
        "amount": {
          "value": 620,
          "currency": "EUR"
        },
        "download_url": "https://www.civitatis.com/example/invoice/inv_2026_09.pdf"
      }
    ]
  },
  "isError": false
}
```

## List payments

MCP tool: `civitatis_list_payments`

Access: read.

Lists monthly settlements with the services rendered, the Civitatis commission, the net amount and the payment status. Use it before request_payment to see which months are still open. The default is the current year.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `year` | integer | no | Settlement year. Default: current year. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "payments": [
      {
        "month": "2026-09",
        "services": {
          "value": 3100,
          "currency": "EUR"
        },
        "commission": {
          "value": 620,
          "currency": "EUR"
        },
        "net": {
          "value": 2480,
          "currency": "EUR"
        },
        "status": "not_requested"
      },
      {
        "month": "2026-08",
        "services": {
          "value": 2750,
          "currency": "EUR"
        },
        "commission": {
          "value": 550,
          "currency": "EUR"
        },
        "net": {
          "value": 2200,
          "currency": "EUR"
        },
        "status": "paid"
      }
    ]
  },
  "isError": false
}
```

## Close dates

MCP tool: `civitatis_close_dates`

Access: write.

Closes an activity for a date range, for all start times or only the ones you list. It stops new sales only; bookings already made stay, and bookings_on_closed_slots tells you how many. close_dates runs without asking first: it messages no one and open_dates undoes it in one call.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | yes | First date to close. |
| `to` | date | yes | Last date to close. |
| `times` | string[] | no | Start times to close, e.g. ["10:00"]. Default: all times. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "civitatis_close_dates",
    "arguments": {
      "activity_id": "act_48213",
      "from": "2026-10-20",
      "to": "2026-10-22",
      "times": [
        "10:00",
        "16:00"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "activity_id": "act_48213",
    "activity": "Bike tour of the old town",
    "closed": [
      {
        "date": "2026-10-20",
        "times": [
          "10:00",
          "16:00"
        ]
      },
      {
        "date": "2026-10-21",
        "times": [
          "10:00",
          "16:00"
        ]
      },
      {
        "date": "2026-10-22",
        "times": [
          "10:00",
          "16:00"
        ]
      }
    ],
    "bookings_on_closed_slots": 0
  },
  "isError": false
}
```

## Open dates

MCP tool: `civitatis_open_dates`

Access: write.

Reopens an activity on dates you closed before, for all start times or only the ones you list. open_dates runs without asking first: it messages no one and close_dates undoes it in one call.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | yes | First date to open. |
| `to` | date | yes | Last date to open. |
| `times` | string[] | no | Start times to open. Default: all times. |

### tools/call

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

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "activity_id": "act_48213",
    "activity": "Bike tour of the old town",
    "opened": [
      {
        "date": "2026-10-22",
        "times": [
          "10:00",
          "16:00"
        ]
      }
    ]
  },
  "isError": false
}
```

## Set quota

MCP tool: `civitatis_set_quota`

Access: write.

Sets the maximum number of places sold per slot for a date range, optionally only on some weekdays and start times. places counts per slot, not per day. set_quota runs without asking first: it messages no one and another call restores the old limit.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | yes | First date. |
| `to` | date | yes | Last date. |
| `places` | integer | yes | Maximum places per slot. |
| `weekdays` | string[] | no | Only these days, e.g. ["sat", "sun"]. Default: every day. |
| `times` | string[] | no | Only these start times. Default: all times. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "civitatis_set_quota",
    "arguments": {
      "activity_id": "activity_8c41d2",
      "from": "2026-10-01",
      "to": "2026-10-01",
      "places": 1
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "activity_id": "act_51907",
    "activity": "Sunset cruise",
    "places": 12,
    "updated": [
      {
        "date": "2026-11-07",
        "times": [
          "18:00"
        ]
      },
      {
        "date": "2026-11-14",
        "times": [
          "18:00"
        ]
      },
      {
        "date": "2026-11-21",
        "times": [
          "18:00"
        ]
      },
      {
        "date": "2026-11-28",
        "times": [
          "18:00"
        ]
      }
    ]
  },
  "isError": false
}
```

## Send message

MCP tool: `civitatis_send_message`

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

Sends a message about one booking, to the customer or to the Civitatis booking department. It appears in the same thread as in the provider panel. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_id` | string | yes | Booking ID from list_bookings. |
| `to` | enum | no | customer or civitatis. Default: customer. |
| `body` | string | yes | Message text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "civitatis_send_message",
    "arguments": {
      "booking_id": "bk_702154",
      "to": "customer",
      "body": "Hi Sofia, we meet at the fountain in Plaza Mayor at 9:50. Your guide Marta will hold a blue umbrella."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "bk_702154",
    "to": "customer",
    "status": "sent",
    "sent_at": "2026-10-11T09:05:00+02:00"
  },
  "isError": false
}
```

## Request payment

MCP tool: `civitatis_request_payment`

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

Requests payment for the services of one past month, net of the Civitatis commission, the same request you make online in the control panel. Civitatis opens requests from the first day of the following month. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `month` | string | yes | Month to settle, YYYY-MM. Must be a past month. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "civitatis_request_payment",
    "arguments": {
      "month": "2026-09"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "month": "2026-09",
    "status": "requested",
    "net": {
      "value": 2480,
      "currency": "EUR"
    },
    "requested_at": "2026-10-01T09:00:00+02:00"
  },
  "isError": false
}
```