Skip to content
Last updated

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

EnvironmentMCP ServerOAuth2 Token
Staginghttps://mcp-staging.bookabletech.comhttps://bookabletech.uk.auth0.com/oauth/token
Productionhttps://mcp.bookabletech.comhttps://auth.bookabletech.com/oauth/token

Authentication

OAuth2 Client Credentials Flow

  1. Token Request: Exchange client credentials for access token

    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:

    {
  "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 connect an MCP Client that only supports local (stdio) servers to a Remote MCP Server, with auth support.

  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 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:

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

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