# Bookable MCP Server Connection Guide

The Bookable MCP Server is a TypeScript-based Model Context Protocol (MCP) server that provides seamless integration with the Bookable API for venue booking management.

## Server Information

### Endpoints

| Environment | MCP Server | OAuth2 Token |
|  --- | --- | --- |
| **Staging** | `https://mcp-staging.bookabletech.com` | `https://bookabletech.uk.auth0.com/oauth/token` |
| **Production** | `https://mcp.bookabletech.com` | `https://auth.bookabletech.com/oauth/token` |


## Authentication

### OAuth2 Client Credentials Flow

1. **Token Request**: Exchange client credentials for access token

```bash
curl --request POST \
  --url https://bookabletech.uk.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "api.bookabletech.com",
    "grant_type": "client_credentials"
  }'
```
2. **Token Response**:

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "venue:read venue-booking:create venue-booking:read venue-booking:update venue-booking:delete"
}
```


## Available Tools

### Venue Management

- **`get_venues`**: Retrieve paginated list of venues
- **`get_venue_by_id`**: Get specific venue details


### Availability & Booking

- **`check_venue_availability`**: Check venue availability
- **`create_venue_booking`**: Create new booking
- **`get_venue_bookings`**: List venue bookings
- **`get_venue_booking_by_id`**: Get specific booking
- **`update_venue_booking`**: Update existing booking
- **`cancel_venue_booking`**: Cancel booking


## Connection Methods

### Method 1: `mcp-remote` remote proxy

[mcp-remote](https://www.npmjs.com/package/mcp-remote) connect an MCP Client that only supports local (stdio) servers to a Remote MCP Server, with auth support.


```bash
  npx -y mcp-remote https://mcp-staging.bookabletech.com \
  --header Authorization:Bearer YOUR_ACCESS_TOKEN
```

### Method 2: Claude Desktop Extension

1. **Get the installer:**
  - Download the latest `.mcpb` file from the [Releases](https://github.com/The-Bookings-Group/bookable-mcp-server-claude-desktop-installation/releases) page
2. **Install in Claude Desktop:**
  - Option 1: Simply double-click the downloaded `.mcpb` file to install
  - Option 2: Open Claude Desktop
    - Go to `Settings` > `Extensions` > `Install from file`
    - Select the downloaded `.mcpb` file
3. **Configure the extension:**
  - In Claude Desktop, go to `Settings` > `Extensions`
  - Find "One-click connector to Bookable remote MCP" in the list
  - Click on the extension's settings/gear icon
  - Enter your Bookable credentials:
    - MCP Server URL
    - Authentication Server URL
    - Client ID and Client Secret (provided by Bookable)
  - Save the settings
  - Restart Claude Desktop if prompted


The extension will automatically handle authentication and connection to the Bookable MCP server.

### Method 3: Custom MCP Client

For custom applications, you can connect directly using the MCP SDK:


```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

const transport = new StreamableHTTPClientTransport(
  new URL(`https://mcp-staging.bookabletech.com`),
  {
    headers: {
      Authorization: `Bearer YOUR_ACCESS_TOKEN`,
    },
  },
);

await client.connect(transport);
```

**Note**: Replace `YOUR_ACCESS_TOKEN` with a valid OAuth2 access token obtained through the authentication flow described above.

## Error Handling

### Common HTTP Status Codes

- **401 Unauthorized**: Invalid or expired access token
- **403 Forbidden**: Insufficient permissions
- **400 Bad Request**: Invalid request parameters
- **404 Not Found**: Resource not found
- **429 Too Many Requests**: Rate limit exceeded
- **500 Internal Server Error**: Server-side error


### Error Response Format


```json
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error message description"
    }
  ]
}
```