> For the complete documentation index, see [llms.txt](https://help.calshare.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.calshare.net/mcp-server-guide.md).

# MCP Server Guide

Connect Calshare data and tools directly to external AI Agents using Model Context Protocol.

## 7.1. Architecture Overview

The **Calshare Model Context Protocol (MCP) Server** bridges the gap between Calshare's internal scheduling platform and modern AI Agents (like Cursor, Claude Desktop, and Gemini).

By connecting to this MCP server, agents gain autonomous access to calendars, real-time availability slots, and the ability to book appointments directly via the API.

The MCP Server is a lightweight Node.js application that runs on the same infrastructure as the Calshare backend. It leverages the official `@modelcontextprotocol/sdk` and acts as a translation layer:

```
AI Agent <---> [STDIO] <---> MCP Node.js Server <---> [HTTP REST V1] <---> Calshare MySQL Database
```

**Connection Transport:** The server is configured to communicate via **STDIO**. This means it should be invoked as a subprocess by the MCP Client (e.g., your IDE or Desktop App).

## 7.2. Setting Up Claude Desktop or Cursor

To give your AI Agent access to Calshare's data, you must configure the MCP Client to spawn this server.

{% stepper %}
{% step %}

## Open your MCP Client settings file:

* **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Cursor:** Go to Settings > Features > MCP > Add New MCP Server.
  {% endstep %}

{% step %}

## Add the following server configuration:

```json
{
  "mcpServers": {
    "calshare-mcp": {
      "command": "node",
      "args": [
        "/var/www/nurank.org/mcp-server/index.js"
      ]
    }
  }
}
```

> **SSH Tunneling Note:** If you are running the MCP client on your local machine, but the server is remote, you can tunnel the execution via SSH:
>
> `"command": "ssh", "args": ["root@calshare.net", "node", "/var/www/nurank.org/mcp-server/index.js"]`
> {% endstep %}
> {% endstepper %}

## 7.3. Available Tools (Functions)

The server exposes three primary tools. Agents will automatically discover these tools when connected.

### A. `get_calendars`

Retrieves all active calendars available in the system.

* **Input:** None
* **Output:** JSON array containing calendar objects (ID, name, theme, booking\_slug, settings).

### B. `get_available_slots`

Queries the booking engine for available time slots on a given date, calculating buffer times, durations, and concurrent slot capacities.

* **Input Parameters:**
  * `calendar_id` (Number) - The ID of the calendar.
  * `date` (String) - Target date in `YYYY-MM-DD` format.
* **Output:** JSON array of available times (e.g. `["09:00", "09:45", "10:30"]`).

### C. `create_booking`

Creates a confirmed booking for a user.

* **Input Parameters:**
  * `calendar_id` (Number) - The ID of the calendar.
  * `datetime` (String) - The exact date and time for the booking (`YYYY-MM-DD HH:MM:SS`).
  * `name` (String) - Client's name.
  * `email` (String) - Client's email (optional).
  * `service_names` (String) - Description of services requested (optional).
* **Output:** Success message and `event_id`.

## 7.4. Extending the MCP Server

If you need to add new capabilities (e.g., `cancel_booking` or `get_reminders`), follow these steps:

{% stepper %}
{% step %}
Open `/var/www/nurank.org/mcp-server/index.js`.
{% endstep %}

{% step %}
Add the new tool's schema inside the `ListToolsRequestSchema` handler.
{% endstep %}

{% step %}
Add the corresponding case in the `CallToolRequestSchema` switch statement, making an `apiClient` request to the appropriate V1 API endpoint.
{% endstep %}

{% step %}
Restart the MCP client to refresh the tools.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
**⚠️ Security & Authentication Warning:** The MCP Server uses a `MASTER_API_KEY` defined internally to authenticate with the `/api/v1/auth.php` endpoint. It operates on behalf of the `system` user, granting it administrative access across all calendars. Do not expose this key.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.calshare.net/mcp-server-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.